LTI 1.3 Dynamic Registration or “How I Met Your Platform”.

LTI 1.3 has greatly advanced the integration of edtech applications. It offers improvements in security with the use of OIDC, Oauth2, and JWT tokens, and flexibility with the use of the LTI Advantages Services such Deep Linking, Grades and Assignments, and Membership.

While these improvements to LTI have been welcomed by the community, there still are some challenges with LTI adoption - most notably, the complicated exchange of configuration information between the Platform and the Tool. Today, manual processes and out-of-band communications are needed to exchange the long list of identifiers and URLs required to properly configure the integration.

The IMS community is aware of the problem and has been working hard to improve the configuration process through the Learning Tools Interoperability (LTI) Dynamic Registration Specification - (Link for IMS Members Only). The Dynamic Registration Specification will automate the exchange of configuration information between Tool and Platform, removing the need for manual processes and out-of-band communication.

As of this writing, Sakai, Moodle, and D2L have already implemented the Dynamic Registration Specification and it is expected that other major learning management systems will soon follow suit.

Everything Started with One URL

Sometimes a romance can start with a simple action, for example, someone attractive at a bar discreetly passes you their telephone number on a napkin. The “romance” between a tool and a platform can begin with something very simple too. The dynamic registration process only needs only one piece of information to start - a URL. Someone from the tool team sends the URL to the platform administrator via email (or phone call, or the tool’s admin portal - you get the point), and that’s it. The URL is the only information exchanged out-of-band. The rest of the process is automatic!

Of course, love is not so simple, and there are options to complicate this process (we will talk about them later), but the basic idea is: One unique URL starts the process!

FIGURE 1: I’m a visual learner, so I understand that maybe you want to see a diagram with the process in case you can’t wait to read each step explanation… so here it is … (Based on the diagram in the IMS Learning Tools Interoperability (LTI) Dynamic Registration Specification  - Link for IMS Members Only)

Step 1: The Platform Starts Flirting

Long love letters are something almost lost to antiquity. But, if you are a romantic like me, today is your lucky day. In the LTI world, the Tool and the Platform are going to start a courtship akin to those love letters of the past. And, like in real life, if they don’t say or do something wrong, and if the Platform Administrator (think in-laws) allows it, it could end in marriage.

In this courtship, the Platform makes the first move. That is, the Platform uses the URL to start the registration. This is designed in this way because the Platform Administrator must be the one making a decision as to whether a Tool is allowed to integrate with the Platform or not. Of course, the Platform Administrator only wants the best for the Platform, and doesn’t want all the Tools in the world indiscriminately integrating with the Platform!

So, one day, the Platform Administrator decides to give the Tool a shot and enters the URL into the Platform to let the romance begin.



FIGURE 2: Extremely simple but effective form in
Sakai to introduce the Initiate Registration endpoint URL.

The Platform will use that URL to call the “Initiate Registration” endpoint in the Tool with a GET message. But, the Platform is kind of coy, so it tells the Tool, “Hi… here is my address in case you want to contact me,” and then waits for the Tool to make the next move.

The Platform sends these 2 parameters:

openid_configuration: The URL where the Tool will read all the information about the Platform (as per OIDC Reg specification).

registration_token: An optional token. When sent, the Tool needs to use it in the registration request. Platform: “I sent to you my address and the key to my heart!”


Example:
Openid_configuration:

{
  "issuer" : "https://qa1-us.nightly.sakaiproject.org",
  "authorization_endpoint" : "https://qa1-us.nightly.sakaiproject.org/imsoidc/lti13/oidc_auth",
  "token_endpoint" : "https://qa1-us.nightly.sakaiproject.org/imsblis/lti13/token/5",
  "token_endpoint_auth_methods_supported" : [ "private_key_jwt" ],
  "token_endpoint_auth_signing_alg_values_supported" : [ "RS256" ],
  "jwks_uri" : "https://qa1-us.nightly.sakaiproject.org/imsblis/lti13/keyset/5",
  "registration_endpoint" : "https://qa1-us.nightly.sakaiproject.org/imsblis/lti13/registration_endpoint/5",
  "scopes_supported" : [ "openid" ],
  "response_types_supported" : [ "id_token" ],
  "subject_types_supported" : [ "public", "pairwise" ],
  "id_token_signing_alg_values_supported" : [ "RS256" ],
  "claims_supported" : [ "iss", "aud" ],
  "https://purl.imsglobal.org/spec/lti-platform-configuration" : {
    "product_family_code" : "sakailms.org",
    "version" : "21.1",
    "messages_supported" : [ {
      "type" : "LtiResourceLinkRequest",
      "placements" : [ ]
    }, {
      "type" : "LtiDeepLinkingRequest",
      "placements" : [ ]
    } ],
    "variables" : [ "User.id", "Person.email.primary" ]
  }
}

Registration_token: 161792293:73e8f0-a259-4d4-b948-ec3a4ae28

Step 2: The Tool Realizes that this can be a Serious Relationship

The Tool, suddenly awakened by this message, thinks, “OMG… the Platform sent me all the information to connect!” so, it calls to the URL received in the openid_configuration field and sees something link this:

FIGURE 4: Platform OpenID configuration example. Between me and you… don’t let the Tool know… but the platform really says this to every tool.

The important fields in this message are:

issuer: The Platform full name
authorization_endpoint: Where to start the OIDC process.
token_endpoint: To be used with Advantage services and some information about the token
jwks_uri: The public keys to validate signatures
registration_endpoint: Where to send the Tool information for the registration

...As well as additional information about the Platform preferences, so the Tool knows a little about the Platform and what it expects from this relationship. For example, the message types that the Platform accepts are defined in this claim: https://purl.imsglobal.org/spec/lti-platform-configuration.

Step 3: The Tool Tries to Seduce the Platform

The Tool now has all the information about the platform to prepare an answer that will impress the Platform.

In our example, we have a very straightforward Tool, but not all the tools are so confident about connecting with a Platform. As mentioned, the URL is the only data point needed in a basic Dynamic Registration, but each tool and platform could add intermediate steps that might require interaction with the user that is registering the Tool (usually the Platform Administrator). For example, Tool could ask for explicit permission from the Platform Administrator to set up the relationship with the Platform

Ok, let’s continue imagining that the Tool now has all the answers it needs and wants to continue the process. Again, this step is optional and some tools may choose to skip any manual intervention.

Finally, the Tool prepares the response and sends it to the Platform using the registration_endpoint specified before, and the Token (if present) received in the first message.

A typical answer from a Tool is kind of chatty. The Tool wants to impress the Platform so it sends all its capacities and endpoints:

redirtect_uris
initiate _login_uri
jwks_uri
tos_uri
Client_uri
policy_uri

And, of course, one parameter with configuration information called toolConfiguration:,

domain
target_link_uri
messages_supported (each one with its own target_link_uri, custom_parameters, placements)

Last but not least all the fun things that the Tool wants to do with the Platform (the scopes), for example:

“Hey, do you want me to send you gradebook items?“
"https://purl.imsglobal.org/spec/lti-ags/scope/lineitem",

“Hey, do you want me to see your scores?”
"https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly",

...And so on with all the possible scopes.

Here is the short example provided in the Learning Tools Interoperability (LTI) Dynamic Registration Specification (https://www.imsglobal.org/spec/lti-dr/v1p0):

{
    "application_type": "web",
    "response_types": ["id_token"],
    "grant_types": ["implict", "client_credentials"],
    "initiate_login_uri": "https://client.example.org/lti",
    "redirect_uris":
      ["https://client.example.org/callback",
       "https://client.example.org/callback2"],
    "client_name": "Virtual Garden",
    "client_name#ja": "バーチャルガーデン",
    "jwks_uri": "https://client.example.org/.well-known/jwks.json",
    "logo_uri": "https://client.example.org/logo.png",
    "client_uri": "https://client.example.org",
    "client_uri#ja": "https://client.example.org?lang=ja",
    "policy_uri": "https://client.example.org/privacy",
    "policy_uri#ja": "https://client.example.org/privacy?lang=ja",
    "tos_uri": "https://client.example.org/tos",
    "tos_uri#ja": "https://client.example.org/tos?lang=ja",
    "token_endpoint_auth_method": "private_key_jwt",
       "contacts": ["ve7jtb@example.org", "mary@example.org"],
    "scope": "https://purl.imsglobal.org/spec/lti-ags/scope/score",
    "https://purl.imsglobal.org/spec/lti-tool-configuration": {
        "domain": "client.example.org",
        "description": "Learn Botany by tending to your little (virtual) garden.",
        "description#ja": "小さな（仮想）庭に行くことで植物学を学びましょう。",
        "target_link_uri": "https://client.example.org/lti",
        "custom_parameters": {
            "context_history": "$Context.id.history"
        },
        "claims": ["iss", "sub", "name", "given_name", "family_name"],
        "messages": [
            {
                "type": "LtiDeepLinkingRequest",
                "target_link_uri": "https://client.example.org/lti/dl",
                "label": "Add a virtual garden",
                "label#ja": "バーチャルガーデンを追加する",
                "custom_parameters": {
                    "botanical_set":"12943,49023,50013"
                }
            }
        ]
    }
}

As you can see, the Tool registration information has everything that the Platform needs to know about the Tool.

Step 4: The Platform Falls for the Tool!

The Platform receives the Tool information and it’s up to the Platform to determine which Tool capabilities to take advantage of. To avoid misunderstandings, the Platform wants to make very clear the terms of the relationship, and sends back an acknowledged last message with a confirmation of the accepted information from the Tool, including the client_id and the deployment_id.

Platform: “Ok, I like you, and It is ok to send me gradebook items, but there is no way I will show you my scores…” or “we can use this placement or this other placement.” Suffice it to say, the platform will make it very clear to the Tool where the limits are with this last message.

With this last message comes the signal that the Tool was waiting for - the deployment_id ! It means that the Platform has the wedding date and the venue reserved. The Platform has said yes. Sure, the Platform Administrator could still say no at the last minute, but let’s just say, things are official now.

This response looks something like this:

{
   "client_uri":null,
   "grant_types":[
      "implict",
      "client_credentials"
   ],
   "application_type":"web",
   "initiate_login_uri":"https://test-lti.unicon.net/oidc/login_initiations",
   "logo_uri":null,
   "https://purl.imsglobal.org/spec/lti-tool-configuration":{
      "messages_supported":[
         {
            "target_link_uri":"https://test-lti.unicon.net/lti3/",
            "placements":null,
            "label":null,
            "type":"LtiDeepLinkingRequest",
            "custom_parameters":null,
            "icon_uri":null
         },
         {
            "target_link_uri":"https://test-lti.unicon.net/lti3/",
            "placements":null,
            "label":null,
            "type":"LtiResourceLinkRequest",
            "custom_parameters":null,
            "icon_uri":null
         }
      ],
      "domain":"test-lti.unicon.net",
      "target_link_uri":"https://test-lti.unicon.net/lti3/",
      "secondary_domains":null,
      "claims":[
         "iss",
         "aud"
      ],
      "description":"The Unicon Demo tool",
      "deployment_id":"1",
      "custom_parameters":null
   },
   "redirect_uris":[
      "https://test-lti.unicon.net/lti3/"
   ],
   "token_endpoint_auth_method":"private_key_jwt",
   "client_id":"f93e96e8-8504-4bb0-8553-ee147920ee42",
   "scope":[
      "openid",
      "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem",
      "https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly",
      "https://purl.imsglobal.org/spec/lti-ags/scope/score",
      "https://purl.imsglobal.org/spec/lti-reg/scope/registration",
      "https://purl.imsglobal.org/spec/lti-nrps/scope/contextmembership.readonly"
   ],
   "jwks_uri":"https://test-lti.unicon.net/jwks/jwk",
   "tos_uri":null,
   "client_name":"Unicon LTI 1.3",
   "contacts":null,
   "response_types":[
      "id_token"
   ],
   "policy_uri":null
}

Step 5: The Last Yes

Just like weddings in the movies, there is one last “speak now or forever hold their peace” moment where the Platform Administrator can confirm, deny, or configure something else. But really, this is the last chance! The Tool will display a final screen with a button to confirm the new relationship.

Upon confirmation, the Tool will send the last confirmation message using a javascript post message with a command like this:

(window.opener || window.parent).postMessage({subject:'org.imsglobal.lti.close'},'https://qa1-us.nightly.sakaiproject.org');

Now the Platform knows that the relationship has started, and will configure the Tool in the Platform.

Like a real-life reception, there is one more thing to do before the honeymoon can start. There is one last (optional) step where the Platform Administrator needs to agree (did Shakespeare write this specification?). By default, the registration of the Tool in the Platform is disabled. This is an opportunity for the Platform to present a dialog to ask for any last modifications, such as the display name for the Tool, and whether or not the Tool should be enabled.

The Honeymoon

Happily, the Platform Administrator enabled the Tool registration. In this very brief courtship, Tool and Platform got to know each other, decided what they are going to do together, (really the Platform has the last word on this), and are now free to integrate happily ever after.

To recap (in an unromantic way):

1.  The Platform receives (usually in a manual way) a URL to start the registration process.
2.  The Platform sends a GET to that URL with a token and the OpenID configuration endpoint.
3.  The Tool calls that configuration endpoint and gets all the info from the Platform including the registration endpoint.
4.  The Tool prepares the response (with or without optional human interaction) and sends it to the registration endpoint.
5. The Platform sends a response to the Tool’s request and the Tool sends the close postMessage to the Platform. This usually happens with a button in the Tool UI that the Platform Admin will click.
6. The Platform receives the postMessage as the last confirmation, closes the iframe, and (optionally) presents the last dialog to the Admin to make last-minute edits and/or enable the tool.

Useful Reading:

• For helpful background information on LTI dynamic registration, read this article’s prequel: Finally, An Easier Way to Onboard New Learning Apps: Meet LTI® 1.3 Dynamic Registration

Unicon is an active member of the IMS Community and serves on many boards. We actively help our clients adopt IMS Global Standards as both the tool and the platform. If you need more information about how to take advantage of the IMS standards and implement them within your products, please contact us.