1. class
  2. Tsugi
  3. \
  4. Util
  5. \
  6. LTI13

LTI13

class LTI13

This is a general purpose LTI 1.3 class with no Tsugi-specific dependencies.

https://www.imsglobal.org/spec/lti/v1p3/

Constants

VERSION_CLAIM

MESSAGE_TYPE_CLAIM

MESSAGE_TYPE_RESOURCE

MESSAGE_TYPE_DEEPLINK

MESSAGE_TYPE_CONTENT_REVIEW

MESSAGE_TYPE_PRIVACY

RESOURCE_LINK_CLAIM

CONTEXT_ID_CLAIM

DEPLOYMENT_ID_CLAIM

ROLES_CLAIM

PRESENTATION_CLAIM

DOCUMENT_TARGET

DOCUMENT_TARGET_FRAME

DOCUMENT_TARGET_IFRAME

DOCUMENT_TARGET_WINDOW

RETURN_URL

LTI11_TRANSITION_CLAIM

FOR_USER_CLAIM

NAMESANDROLES_CLAIM

ENDPOINT_CLAIM

DEEPLINK_CLAIM

CUSTOM_CLAIM

MEDIA_TYPE_MEMBERSHIPS

MEDIA_TYPE_LINEITEM

MEDIA_TYPE_LINEITEMS

SCORE_TYPE

RESULTS_TYPE

TOOL_PLATFORM_CLAIM

PRODUCT_FAMILY_CODE

LINEITEM_TIMESTAMP

LINEITEM_SCOREGIVEN

LINEITEM_SCOREMAXIMUM

LINEITEM_COMMENT

LINEITEM_USERID

ACTIVITY_PROGRESS

ACTIVITY_PROGRESS_INITIALIZED

ACTIVITY_PROGRESS_STARTED

ACTIVITY_PROGRESS_INPROGRESS

ACTIVITY_PROGRESS_SUBMITTED

ACTIVITY_PROGRESS_COMPLETED

GRADING_PROGRESS

GRADING_PROGRESS_FULLYGRADED

GRADING_PROGRESS_PENDING

GRADING_PROGRESS_PENDINGMANUAL

GRADING_PROGRESS_FAILED

GRADING_PROGRESS_NOTREADY

Methods

static 
extract_issuer_key(string $jwt)

Pull out the issuer_key from a JWT

static 
extract_issuer_key_string($issuer)

Pull out the composite issuer_key from issuer and audience

static string
raw_jwt(array $request_data = false)

Find the JWT in the request data

static mixed
parse_jwt(string $raw_jwt, boolean $required_fields = true)

Parse and validate a raw JWT

static string
dump_jwt(object $jwt)

Print out the contents of the JWT

static Returns
isRequestDetail(array $request_data = false)

Returns true if this is an LTI 1.3 message with minimum values to meet the protocol

static Returns
isRequest(array $request_data = false)

Returns true if this is an LTI 1.3 message with minimum values to meet the protocol

static mixed
verifyPublicKey(string $raw_jwt, string $public_key, string $algs = false)

Verify the Public Key for this request

static boolean
isValidMessageType(string $lti_message_type)

Check the incoming message type

static boolean
isValidVersion(string $lti_version)

Check the incoming message version

static string
handle_curl_error($ch, $debug_log)

Handle a curl that fails

static 
jonPostel(object $body, array $failures)

Apply Jon Postel's Law as appropriate

static mixed
getGradeToken($subject, $lti13_token_url, $lti13_privkey, $lti13_kid, $lti13_token_audience, $deployment_id, $debug_log = false)

Retrieve a grade token

static mixed
getNRPSToken($subject, $lti13_token_url, $lti13_privkey, $lti13_kid, $lti13_token_audience, $deployment_id, $debug_log = false)

Retrieve a Names and Roles Provisioning Service (NRPS) token

static mixed
getNRPSWithSourceDidsToken($subject, $lti13_token_url, $lti13_privkey, $lti13_kid, $lti13_token_audience, $deployment_id, $debug_log = false)

Retrieve a Names and Roles Provisioning Service (NRPS) token with source_dids

static mixed
getLineItemsToken($subject, $lti13_token_url, $lti13_privkey, $lti13_kid, $lti13_token_audience, $deployment_id, $debug_log = false)

Retrieve a LineItems token

static mixed
sendLineItemResult($user_id, $grade, $scoreMaximum, $comment, $lineitem_url, $access_token, array $extra = false, array $debug_log = false)

Send a line item result

static mixed
loadNRPS(string $membership_url, $access_token, array $debug_log = false)

Load the memberships and roles if we can get it from the LMS

static mixed
loadLineItems($lineitems_url, $access_token, $debug_log = false)

Load our lineitems from the LMS

static mixed
loadLineItem($lineitem_url, $access_token, $debug_log = false)

Load the detiail for a lineitem from the LMS

static mixed
loadResults($lineitem_url, $access_token, $debug_log = false)

Load the results for a line item

static mixed
deleteLineItem($lineitem_url, $access_token, $debug_log = false)

Delete a lineitem from the LMS

static mixed
createLineItem($lineitems_url, $access_token, object $lineitem, $debug_log = false)

Create a lineitem in the LMS

static mixed
updateLineItem($lineitem_url, $access_token, $lineitem, $debug_log = false)

Update a lineitem in the LMS

static array
get_access_token($scope, $subject, $lti13_token_url, $lti13_privkey, $lti13_kid = false, $lti13_token_audience = false, $deployment_id = false, $debug_log = false)

Retrieve an access token

static mixed
extract_access_token(array $token_data, array $debug_log = false)

Extract an access token from returned data

static array
base_jwt(string $issuer, string $subject, array $debug_log = false)

Build up a basic JWT

static string
encode_jwt(array $jwt_claim, string $lti13_privkey, string $lti13_kid = false)

Sign and encode a JWT

static 
build_jwt_html(string $launch_url, string $jws, boolean $dodebug = true, array $extra = false)

Build an HTML form to submit a JWT

static 
generatePKCS8Pair($publicKey, $privateKey)

No description

static string
cleanup_PKCS8(string $private_key)

Cleanup common mess-ups in PKCS8 strings

static string
getLTI11TransitionBase(object $lj)

Compute the base string for a Launch JWT

static string
signLTI11Transition(object $lj, string $secret)

Compute the OAuth signature for an LTI 1.3 Launch JWT

static mixed
checkLTI11Transition(object $lj, string $key, string $secret)

Check the OAuth signature for an LTI 1.3 Launch JWT

static string
compute_HMAC_SHA256(object $message, string $secret)

Compute the HMAC256 of a string (part of LTI 1.1 Transition)

static 
extractKeyFromKeySet($keyset_str, $kid)

Extract a public key from a string containing a JSON keyset

Details

at line 84
static extract_issuer_key(string $jwt)

Pull out the issuer_key from a JWT

Parameters

string $jwt The parsed JWT

at line 94
static extract_issuer_key_string($issuer)

Pull out the composite issuer_key from issuer and audience

Parameters

$issuer

at line 106
static string raw_jwt(array $request_data = false)

Find the JWT in the request data

Parameters

array $request_data An optional prarameter if you want to pull the data from somewhere other than $_REQUEST.

Return Value

string The JWT from the request or false if there is no JWT.

at line 123
static mixed parse_jwt(string $raw_jwt, boolean $required_fields = true)

Parse and validate a raw JWT

Parameters

string $raw_jwt The encoded JWT (a string)
boolean $required_fields Whether to throw an error if the required fields are missing. You can set this to false if you just want to parse and dump a JWT for debugging.

Return Value

mixed The parsed fields in an object as long as there are no errors. If there are errors, a string with the error message is returned.

at line 153
static string dump_jwt(object $jwt)

Print out the contents of the JWT

Parameters

object $jwt The parsed JWT object.

Return Value

string The output of the JWT suitable for printing (escaping needed)

at line 176
static Returns isRequestDetail(array $request_data = false)

Returns true if this is an LTI 1.3 message with minimum values to meet the protocol

Parameters

array $request_data An optional prarameter if you want to pull the data from somewhere other than $_REQUEST.

Return Value

Returns true if this has a valid JWT, false if this is not a JWT at all, or a string with an error message if this parses as a JWT but is missing required data.

at line 194
static Returns isRequest(array $request_data = false)

Returns true if this is an LTI 1.3 message with minimum values to meet the protocol

Parameters

array $request_data An optional prarameter if you want to pull the data from somewhere other than $_REQUEST.

Return Value

Returns true if this has a valid JWT, false if this is not a JWT at all.

at line 213
static mixed verifyPublicKey(string $raw_jwt, string $public_key, string $algs = false)

Verify the Public Key for this request

Parameters

string $raw_jwt The raw JWT from the request
string $public_key The public key
string $algs The algorithm to use for validating the key.

Return Value

mixed This returns true if the request verified. If the request did not verify, this returns the exception that was generated.

at line 243
static boolean isValidMessageType(string $lti_message_type)

Check the incoming message type

Parameters

string $lti_message_type The incoming message type from the request.

Return Value

boolean True if this is an LTI 1.1 or LTI 1.3 message type.

at line 255
static boolean isValidVersion(string $lti_version)

Check the incoming message version

Parameters

string $lti_version The incoming message type from the request.

Return Value

boolean True if this is an LTI 1.1 or LTI 2.0 message version.

at line 265
static string handle_curl_error($ch, $debug_log)

Handle a curl that fails

Parameters

$ch
$debug_log

Return Value

string The error message

at line 292
static jonPostel(object $body, array $failures)

Apply Jon Postel's Law as appropriate

Postel's Law - https://en.wikipedia.org/wiki/Robustness_principle

"TCP implementations should follow a general principle of robustness: be conservative in what you do, be liberal in what you accept from others."

By default, Jon Postel mode is off and we are stricter than we need to be. This works well because it reduces the arguments with the certification folks. But if you add:

 $CFG->jon_postel = true;

Tsugi will follow Jon Postel's law.

Parameters

object $body The body of the JWT
array $failures A string array of failures (pass by reference)

at line 330
static mixed getGradeToken($subject, $lti13_token_url, $lti13_privkey, $lti13_kid, $lti13_token_audience, $deployment_id, $debug_log = false)

Retrieve a grade token

Parameters

$subject
$lti13_token_url
$lti13_privkey
$lti13_kid
$lti13_token_audience
$deployment_id
$debug_log

Return Value

mixed Returns the token (string) or false on error.

at line 349
static mixed getNRPSToken($subject, $lti13_token_url, $lti13_privkey, $lti13_kid, $lti13_token_audience, $deployment_id, $debug_log = false)

Retrieve a Names and Roles Provisioning Service (NRPS) token

Parameters

$subject
$lti13_token_url
$lti13_privkey
$lti13_kid
$lti13_token_audience
$deployment_id
$debug_log

Return Value

mixed Returns the token (string) or false on error.

at line 368
static mixed getNRPSWithSourceDidsToken($subject, $lti13_token_url, $lti13_privkey, $lti13_kid, $lti13_token_audience, $deployment_id, $debug_log = false)

Retrieve a Names and Roles Provisioning Service (NRPS) token with source_dids

This should require both the lineitems and grade permission I think. But some clarification is needed to make sure this is done correctly.

Parameters

$subject
$lti13_token_url
$lti13_privkey
$lti13_kid
$lti13_token_audience
$deployment_id
$debug_log

Return Value

mixed Returns the token (string) or false on error.

at line 386
static mixed getLineItemsToken($subject, $lti13_token_url, $lti13_privkey, $lti13_kid, $lti13_token_audience, $deployment_id, $debug_log = false)

Retrieve a LineItems token

Parameters

$subject
$lti13_token_url
$lti13_privkey
$lti13_kid
$lti13_token_audience
$deployment_id
$debug_log

Return Value

mixed Returns the token (string) or false on error.

at line 408
static mixed sendLineItemResult($user_id, $grade, $scoreMaximum, $comment, $lineitem_url, $access_token, array $extra = false, array $debug_log = false)

Send a line item result

Parameters

$user_id The user for this grade
$grade Value to send
$scoreMaximum The amount that $grade is realative to
$comment An optional comment
$lineitem_url The REST endpoint (id) for this line item
$access_token The access token for this request
array $extra A set of key value extensions to be added/replaced in the request
array $debug_log An optional array passed by reference. Actions taken will be logged into this array.

Return Value

mixed Returns the token (string) or false on error.

at line 496
static mixed loadNRPS(string $membership_url, $access_token, array $debug_log = false)

Load the memberships and roles if we can get it from the LMS

Parameters

string $membership_url The REST endpoint for memberships
$access_token The access token for this request
array $debug_log If this is an array, debug information is returned as the process progresses.

Return Value

mixed If this works it returns the NRPS object. If it fails, it returns a string.

at line 594
static mixed loadLineItems($lineitems_url, $access_token, $debug_log = false)

Load our lineitems from the LMS

Parameters

$lineitems_url The REST endpoint (id) for the line items
$access_token The access token for this request
$debug_log Returns a log of actions taken

Return Value

mixed If this works it returns the LineItems array. If it fails, it returns a string.

at line 647
static mixed loadLineItem($lineitem_url, $access_token, $debug_log = false)

Load the detiail for a lineitem from the LMS

Parameters

$lineitem_url The REST endpoint (id) for this line item
$access_token The access token for this request
$debug_log Returns a log of actions taken

Return Value

mixed If this works it returns the LineItem object. If it fails, it returns a string.

at line 701
static mixed loadResults($lineitem_url, $access_token, $debug_log = false)

Load the results for a line item

Parameters

$lineitem_url The REST endpoint (id) for this line item
$access_token The access token for this request
$debug_log Returns a log of actions taken

Return Value

mixed If this works it returns the Results array. If it fails, it returns a string.

at line 764
static mixed deleteLineItem($lineitem_url, $access_token, $debug_log = false)

Delete a lineitem from the LMS

Parameters

$lineitem_url The REST endpoint (id) for this line item
$access_token The access token for this request
$debug_log Returns a log of actions taken

Return Value

mixed If this works it returns true. If it fails, it returns a string.

at line 830
static mixed createLineItem($lineitems_url, $access_token, object $lineitem, $debug_log = false)

Create a lineitem in the LMS

Parameters

$lineitems_url The REST endpoint (id) for this line item
$access_token The access token for this request
object $lineitem The fields for the new line item

$newitem = new \stdClass();
$newitem->scoreMaximum = 100;
$newitem->label = 'Week 3 Feedback';
$newitem->resourceId = '2987487943';
$newitem->tag = 'optional';
$debug_log Returns a log of actions taken

Return Value

mixed If this works it returns an array including the new line item url. If it fails, it returns a string.

at line 899
static mixed updateLineItem($lineitem_url, $access_token, $lineitem, $debug_log = false)

Update a lineitem in the LMS

Parameters

$lineitem_url
$access_token
$lineitem
$debug_log

Return Value

mixed If this works it returns true. If it fails, it returns a string.

at line 957
static array get_access_token($scope, $subject, $lti13_token_url, $lti13_privkey, $lti13_kid = false, $lti13_token_audience = false, $deployment_id = false, $debug_log = false)

Retrieve an access token

Parameters

$scope
$subject
$lti13_token_url
$lti13_privkey
$lti13_kid
$lti13_token_audience
$deployment_id
$debug_log

Return Value

array The retrieved and parsed JSON data. There is no validation performed, and we might have got a 403 and received no data at all.

at line 1026
static mixed extract_access_token(array $token_data, array $debug_log = false)

Extract an access token from returned data

Parameters

array $token_data The JSON response to a token request, parsed in an array of key / value pairs.
array $debug_log An optional array passed by reference. Actions taken will be logged into this array.

Return Value

mixed This returns the token as a string if it is successful, or false

at line 1056
static array base_jwt(string $issuer, string $subject, array $debug_log = false)

Build up a basic JWT

Parameters

string $issuer Who we are
string $subject Who we are
array $debug_log An optional array passed by reference. Actions taken will be logged into this array.

Return Value

array The basic fields of the JWT are populated

at line 1079
static string encode_jwt(array $jwt_claim, string $lti13_privkey, string $lti13_kid = false)

Sign and encode a JWT

Parameters

array $jwt_claim An array of key/value pairs for the claims
string $lti13_privkey The private key to use to sign the JWT
string $lti13_kid The key id to include in the JWT (optional)

Return Value

string The signed JWT

at line 1105
static build_jwt_html(string $launch_url, string $jws, boolean $dodebug = true, array $extra = false)

Build an HTML form to submit a JWT

Parameters

string $launch_url The URL to send the JWT
string $jws The signed JWT
boolean $dodebug dodebug Whether to auto submit the JWT or pause with some debugging output.
array $extra some extra/optional parameters

formattr - Additional text to include within the <form tag
button - The text of the botton (ie. to allow I18N)

@return string The HTML to send to the browser

at line 1150
static generatePKCS8Pair($publicKey, $privateKey)

Parameters

$publicKey
$privateKey

at line 1186
static string cleanup_PKCS8(string $private_key)

Cleanup common mess-ups in PKCS8 strings

Often when public/private keys are pasted, stuff is added or lines run together or stuff is missing from the string. The PHP library is a little picky on these things so this routine just checks for common boo-boos and fixes them. As they say in Office Space, "We fixed the glitch."

Parameters

string $private_key The possible ill-formatted private key

Return Value

string The hopefully better formatted private key

at line 1239
static string getLTI11TransitionBase(object $lj)

Compute the base string for a Launch JWT

See: https://www.imsglobal.org/spec/lti/v1p3/migr#lti-1-1-migration-claim

Parameters

object $lj The Launch JSON Web Token with the LTI 1.1 transition data

Return Value

string This is null if the base string cannot be computed

at line 1272
static string signLTI11Transition(object $lj, string $secret)

Compute the OAuth signature for an LTI 1.3 Launch JWT

See: https://www.imsglobal.org/spec/lti/v1p3/migr#lti-1-1-migration-claim

Parameters

object $lj The Launch JSON Web Token with the LTI 11 transition data
string $secret The OAuth secret

Return Value

string This is null if the signature cannot be computed

at line 1296
static mixed checkLTI11Transition(object $lj, string $key, string $secret)

Check the OAuth signature for an LTI 1.3 Launch JWT

See: https://www.imsglobal.org/spec/lti/v1p3/migr#lti-1-1-migration-claim

Parameters

object $lj The Launch JSON Web Token with the LTI 11 transition data
string $key The OAuth key
string $secret The OAuth secret

Return Value

mixed true if the signature matches, false if the JWT the signature does not match, and a string with an error if the JWT data is malformed.

at line 1328
static string compute_HMAC_SHA256(object $message, string $secret)

Compute the HMAC256 of a string (part of LTI 1.1 Transition)

See: https://www.imsglobal.org/spec/lti/v1p3/migr#lti-1-1-migration-claim

Based on: https://www.jokecamp.com/blog/examples-of-creating-base64-hashes-using-hmac-sha256-in-different-languages/#php

Parameters

object $message The message to sign
string $secret The secret used to sign the message

Return Value

string The signed message

at line 1338
static extractKeyFromKeySet($keyset_str, $kid)

Extract a public key from a string containing a JSON keyset

Parameters

$keyset_str
$kid