LTI Platform Support

Engine provides LTI platform support (import and launch of links into LTI tools) for LTI 1.1 and 1.3. The Engine concept of a "course" corresponds to the LTI concept of a "resource link".

Metadata

Occasionally you may want to pass additional information about the content to the tool as part of the launch process. This can be done by specifying metadata when making the request to import a course. The metadata schema is as follows:

"description": "string",
"context": {
  "contextId": "string",
  "contextTitle": "string",
  "contextLabel": "string",
  "contextType": [
    "string"
  ]
},
"customParameters": [
  {
    "item": "string",
    "value": "string"
  }
]

All of the properties in the metadata schema, are optional, however, to use the Assignment and Grade Service in LTI 1.3, a contextId must be specified.

Note: In LTI, a context refers to a collection of resources, or what is commonly thought of as a course

A short description and example of each property is provided in the table below:

Optional Configuration Settings

The following configuration settings, if specified, will be passed to the LTI tool during launch:

• LtiConsumerProductFamily
• LtiConsumerVersion
• LtiConsumerName
• LtiConsumerDescription
• LtiConsumerUrl
• LtiConsumerEmail

LTI v1.3

Configuration

The following configuration settings are required for LTI 1.3 support:

• LtiConsumerIdentifier - A unique (a UUID is recommended) identifier for the product providing LTI support.
• LtiBaseUrl - A fully-qualified URL to the '/api' path under the Engine application. This value is used for determining absolute URLs for endpoints LTI 1.3 tools need to access.
• LtiPlatformIssuer An HTTPS URL identifying the LTI 1.3 platform. JSON Web Tokens sent to the tool will have this value in the iss claim, so tools should be configured to expect this value.
• RemoteDeliverPageUrl - Must be an absolute URL for LTI 1.3 support.

The following optional settings may also be specified:

• LtiJsonWebTokenExpiry
• EncryptionPassword - This setting should be specified so that the generated keys are stored encrypted.

Importing LTI 1.3 Links

Connector Import

An LTI 1.3 link may be imported only via Content Connector. The process of registering an LTI 1.3 tool with a connector involves two steps.

First, an LTI 1.3 connector must be created with a POST request to the /api/v2/contentConnectors endpoint with the following schema:

{
  "contentConnectorType": "ContentConnector.Lti13",
  "configuration": {
    "toolPublicKey": "string",
    "toolOidcLoginInitiationsEndpoint": "string",
    "toolOidcLaunchRedirectUris": ["string"]
    }
}

All of the fields in the schema are required.

• toolPublicKey - The RSA 256 public key associated with the tool.
• toolOidcLoginInitiationsEndpoint - The endpoint the platform will use to initiate the OpenID Connect authorization flow
• toolOidcLaunchRedirectUris - One or more URIs where the OIDC Authorization Response can be sent

A successful request will return the connectorId as a UUID in the response.

Second, the LTI 1.3 tool must be configured with information about the LTI 1.3 platform. This information can be retrieved by making a GET request to the /api/v2/contentConnectors endpoint with the includeAdditionalInstanceInformation=true query parameter and locating the entry corresponding to the connectorId from the first step. The response will contain an additionalInstanceInformation schema with the following keys:

"additionalInstanceInformation": {
    "toolClientId": "string",
    "oidcAuthorizationUrl": "string",
    "jwksEndpoint": "string",
    "issuer": "string",
    "deploymentId": "string",
    "accessTokenUrl": "string"
}

Each value (except accessTokenUrl) should be supplied to the LTI 1.3 tool to complete the registration process. accessTokenUrl is only needed if Assignment and Grade Services support is desired.

• toolClientId - The OAuth Client Id for the tool. JSON Web Tokens sent to the tool will have this value in the aud claim.
• oidcAuthorizationUrl - The endpoint where the tool should send the OIDC Authorization Request.
• jwksEndpoint - A link to access the platform's JSON Web Key Set. This will be an absolute, unsecured URL to the /plugin/lti13/{connectorId}/jwks endpoint.
• issuer - The value of the required LtiPlatformIssuer configuration setting.
• deploymentId - An identifier for the integration between the platform and the tool. Identical to the connectorId.
• accessTokenUrl - The endpoint the tool should use to retrieve an OAuth 2.0 access token that it will use to access the platform's Assignment and Grade Services endpoints. This will be an absolute, unsecured URL to the /plugin/lti13/{connectorId}/token endpoint.

Once the connector has been created, an LTI 1.3 link can be imported using a POST request to the /api/v2/courses endpoint with the url and title passed in as follows:

{
  "connectorReferenceRequest": {
    "connectorId": "string",
    "metadataForConnector": {
        "url": "string",
        "title": "string"
        "ltiMetadata": {
          "context": {
            "contextId": "string"
         }
      }
    }
  }
}

The url in this schema is the endpoint that will be executed at the end of the OpenID Connect authentication flow. This value will be passed in the https://purl.imsglobal.org/spec/lti/claim/target_link_uri claim in the JSON Web Token.

Optional metadata can be specified with an ltiMetadata key in the metadataForConnector schema.

Once imported, the link may be launched through the normal course launch process.

Assignment and Grade Services

LTI 1.3 connectors provide support for recording and retrieving grades via the LTI Assignment and Grade Services specification. For the Assignment and Grade service to be used, a valid contextId should be supplied in the ltiMetadata API schema. The contextId should be a unique, opaque identifier for the context. For LTI 1.3, this identifier must not exceed 255 ASCII characters and must be provided if any other context claims are also provided. An example value for this property would be a guid like c1d887f0-a1a3-4bca-ae25-c375edcc131a.

Terminology

Line Items

Each LTI link imported into Engine corresponds to one line item. Different versions of the link will correspond to different line items. Currently, the tool is unable to create additional line items to associate with the link.

User Ids

Each registration in Engine corresponds to one userId. If a DELETE request is made to the /registrations/{registrationId}/progress endpoint, the tool will no longer be able to set or access grades for the userId corresponding to that registrationId. A new userId can be generated by re-launching the link for that registration.

Authorization

Access Token

To access the Assignment and Grade endpoints, tools will need an OAuth 2.0 access token which can be requested using the /plugin/lti13/{connectorId}/token endpoint. A successful request will return a token with https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly and https://purl.imsglobal.org/spec/lti-ags/scope/score scopes, which will give the tool access to the following endpoints:

• plugin/lti13/{connectorId}/{contextId}/lineItems/{lineItemId}/scores
• plugin/lti13/{connectorId}/{contextId}/lineItems/{lineItemId}/results
• plugin/lti13/{connectorId}/{contextId}/lineItems/{lineItemId}/results/{userId}

Grading

While the configured LTI tools will be able to read and write scores for line items using the endpoints defined above, limited information about LTI 1.3 registrations will also be available via the main Engine /registrations endpoints.

Registration Completion

The registrationCompletion value for an LTI 1.3 registration will be UNKNOWN if no scores have been received or if a score with the activityProgress value set to Initialized has been received . This value will be set to COMPLETED if the activityProgress value received is Completed or Submitted and to INCOMPLETE if the activityProgress value received is Started or InProgress.

Registration Success

Currently registrationSuccess for an LTI 1.3 registration will always contain UNKNOWN.

Recording Grades

An LTI 1.3 registration will be updated with the provided score if the gradingProgress value is set to FullyGraded, Pending, or PendingManual, provided that a score has actually been provided. In cases where either the scoreMaximum is 0, or the scoreMaximum is less than the scoreGiven, the scaled score will be set to NaN. Otherwise, the scaled score will be set to scoreGiven divided by scoreMaximum.

Enabling Lobbing

For the Engine implementation of Assignment and Grade Services to be fully compliant, StoreRuntimeDataAsLob should be set to 'true' (which is the default).

Without this setting enabled, the platform will not be able to validate that the timestamp field on an incoming score update request is later than the timestamp on the last successful update request. Instead, score update requests will be processed in the order that they are received.

Key Rotation

The LTI 1.3 connector provides a mechanism to rotate the RSA 256 key pairs associated with the platform. Rotation is done by making a POST request to /api/v2/plugin/lti13/{connectorId}/rotateKeys with the following body:

{
  "expiry": "string"
}

expiry must be a valid UTC date-time If the expiry time has not passed, a request to the /plugin/lti13/{connectorId}/jwks endpoint will return both the newly generated key and the previous key (for a maximum of two total keys at any given time). Once expiry passes, the endpoint will return a single key until another rotateKeys request with a non-expired expiry is made.

LTI v1.1

Configuration

The following configuration settings are required for LTI 1.1 support:

• LtiConsumerIdentifier - A unique (a UUID is recommended) identifier for the product providing LTI support.
• LtiBaseUrl - A fully-qualified URL to the '/api' path under the Engine application. This value is used for determining the absolute URL for the Basic Outcomes endpoint LTI 1.1 tools will use to report scores.

Importing LTI 1.1 Links

To import an LTI 1.1 link you will need the following information about it:

• Consumer Key - The OAuth 1.0 Consumer Key supplied by the tool
• Shared Secret - The OAuth 1.0 Secret supplied by the tool
• Url - The Launch Url supplied by the tool
• Title - A descriptive title for the content

Links may be imported either directly or with a connector. Both options are detailed below.

Once imported, the link may be launched through the normal course launch process and tracked via LTI Basic Outcomes.

Direct Import

An LTI 1.1 link may be imported directly using a POST request to api/v2/courses/. The minimal schema required for import is:

  "lti11LinkReferenceRequest": {
    "url": "string",
    "key": "string",
    "sharedSecret": "string",
    "title": "string"
  }

Optional metadata can be specified with an ltiLinkMetadata key in the lti11LinkReferenceRequest schema. Details can be found in the API documentation.

Connector Import

An LTI 1.1 link may also be imported via Content Connector. This is useful in cases where you have multiple links using the same credentials, because it allows you to specify the credentials in only one place.

An LTI 1.1 Content Connector can be created using a POST request to api/v2/ContentConnectors with the following information:

{
  "contentConnectorType": "ContentConnector.Lti11",
  "configuration": {
    "key": "string",
    "sharedSecret": "string"
  }
}

A successful request to create a connector will return a UUID identifying the connector. This connectorId must be specified in subsequent requests to import content using the connector.

Once the connector has been created, an LTI 1.1 link can be imported using a POST request to the /api/v2/courses endpoint with the url and title passed in as follows:

{
  "connectorReferenceRequest": {
    "connectorId": "string",
    "metadataForConnector": {
        "url": "string",
        "title": "string"
    }
  }
}

Optional metadata can be specified with an ltiMetadata key in the metadataForConnector schema.

Scoring

LTI 1.1 allows scores to be recorded on a scale from 0-1 via Basic Outcomes. In Engine these scores are scaled on a scale from 0-100. No completion information is recorded about LTI link launches.