4.1.1 Using JSON Web Tokens with OAuth 2.0 Client-Credentials Grant

In this approach, a Consumer generates a JWT [RFC7519] bearer token as a means for authentication in requesting an OAuth 2.0 access token, which it can then use to authorize requests to services as per [RFC7523].

The JWT payload MUST contain at least the following Claims:

{
    "iss" : "tool.com",
    "sub" : "www.example.com",
    "aud" : ["https://www.example.com/lti/auth/token"],
    "iat" : "1485907200",
    "exp" : "1485907500",
    "jti" : "29f90c047a44b2ece73d00a09364d49b"
}        
      

The aud Claim MUST contain a value that identifies the authorization server as an intended audience. The Consumer MAY use the token endpoint URL of the authorization server as a value for an aud element to identify the authorization server as an intended audience of the JWT. The authorization server MUST reject any JWT that does not contain its own identity as the intended audience. This information MUST be sent as an array even when there is only one value.

The iat Claim MUST be the time at which the Consumer generated the JWT.

The exp Claim MUST be an absolute expiry time for the message (typically five minutes after the iat timestamp); the Consumer MUST honor this expiry time, though it MAY also choose to expire the JWT at an earlier time (but no earlier than the iat value). This exp timestamp SHOULD also indicate when the jti value expires and could be re-used.

The Consumer MAY include other top-level Claims in the JWT and, if it does so, the authorization server MAY ignore them.

The above JSON structure represents the first, payload element of the JWT. The Consumer MUST also add a second, header element, referred to as the JSON Object Signing and Encryption (JOSE) header, that defines the algorithm it used to sign the token.

{
    "typ" : "JWT",
    "alg" : "RS256"
}
      

The approved list of algorithms that MUST be used for JWT signing, and permitted as the value of alg is given in the Best Practices.

The Consumer MUST generate a third, signature element by applying the algorithm to the contents of both the header and payload elements (see [RFC7515] for how to create a JSON Web Signature, JWS). The Consumer then forms the value of the JWT by separately base-64 encoding each of the three elements and concatenating them with a period (.) as a separator character i.e.

JWT = base64_encode(JOSE Header).base64_encode(Claim Set Payload).base64_encode(JWS Signature)        
      

creating a JWT of (line breaks added for clarity):

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
.eyJpc3MiOiJ0b29sLmNvbSIsInN1YiI6Ind3dy5leGFtcGxlLmNvbSIsImF1ZCI6Imh0dHBzOi8vd3d3Lm
V4YW1wbGUuY29tL2x0aS9hdXRoL3Rva2VuIiwiaWF0IjoiMTQ4NTkwNzIwMCIsImV4cCI6IjE0ODU5MDc1
MDAiLCJqdGkiOiIyOWY5MGMwNDdhNDRiMmVjZTczZDAwYTA5MzY0ZDQ5YiJ9
.liArqLDIF-xGcCu8ythy0HlzntxwZ90AYTnwH-daCQQ        
      

The Consumer's resulting authorization request uses the following POST parameters:

• grant_type=client_credentials

• client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer

• client_assertion= the Consumer's generated JWT

• scope=https://purl.imsglobal.org/spec/lti-ags/scope/lineitem https://purl.imsglobal.org/spec/lti-ags/scope/result/read

This leads to a request with the following form (with line breaks for clarity):

POST /lti/auth/token HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
.eyJpc3MiOiJ0b29sLmNvbSIsInN1YiI6Ind3dy5leGFtcGxlLmNvbSIsImF1ZCI6Imh0dHBzOi8vd3d3LmV4YW1wbGUuY29tL2x0aS9hdXRoL3R
va2VuIiwiaWF0IjoiMTQ4NTkwNzIwMCIsImV4cCI6IjE0ODU5MDc1MDAiLCJqdGkiOiIyOWY5MGMwNDdhNDRiMmVjZTczZDAwYTA5MzY0ZDQ5YiJ9
.liArqLDIF-xGcCu8ythy0HlzntxwZ90AYTnwH-daCQQ
&scope=http%3A%2F%2Fimsglobal.org%2Fspec%2Flti-ags%2Fscope%2Flineitem%20http%3A%2F%2Fimsglobal.org%2Fspec%2Flti-ags%2Fscope%2Fresult%2Fread        

The authorization server decodes the JWT and MUST validate the values for the iss, sub, exp, aud and jti claims, followed by verifying the signature. If it finds the request to be a valid, it generates and returns an access token, with a response of this form:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token" : "dkj4985kjaIAJDJ89kl8rkn5",
    "token_type" : "bearer",
    "expires_in" : 3600,
    "scope" : "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem https://purl.imsglobal.org/spec/lti-ags/scope/result/read"    
}        

As per [RFC7519] the token MUST ONLY contain ASCII characters (0x20-0x7A) and SHOULD be at least 15 characters in length. The token MAY be a JWT (see below). 1EdTech recommends a default expiry time of 1 hour (3600 seconds). The bearer of the token can use it until the token expires (as evidenced by a failed request) but 1EdTech recommends that a Consumer manages tokens such that once they have expired (allowing for clock skew between the systems), it requests a new one when needed.

{
    "sub" : "www.example.com",
    "iat" : "1485907200",
    "exp" : "1485907500",
    "imsglobal.org.security.scope" : "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem https://purl.imsglobal.org/spec/lti-ags/scope/result/read"    
}          

{
    "typ" : "JWT",
    "alg" : "RS256"
}          

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ3d3cuZXhhbXBsZS5jb20iLCJpYXQiOiIxNDg1OTA3MjAwIiwiZXhwIjoiMTQ4NTkwNzUwMCIsImltc2dsb2JhbC5vcmcuc2VjdXJpdHkuc2NvcGUiOiJMdGlMaW5rU2V0dGluZ3MgU2NvcmUuaXRlbS5QVVQifQ.UWCuoD05KDYVQHEcciTV88YYtWWMwgb3sTbrjwxGBZA          
        

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ3d3cuZXhhbXBsZS5jb20iLCJpYXQiOiIxNDg1OTA3MjAwIiwiZXhwIjoiMTQ4NTkwNzUwMCIsImltc2dsb2JhbC5vcmcuc2VjdXJpdHkuc2NvcGUiOiJMdGlMaW5rU2V0dGluZ3MgU2NvcmUuaXRlbS5QVVQifQ.UWCuoD05KDYVQHEcciTV88YYtWWMwgb3sTbrjwxGBZA",
    "token_type" : "bearer",
    "expires_in" : 3600,
    "scope" : "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem https://purl.imsglobal.org/spec/lti-ags/scope/result/read"
}          
        

4.1.2 Token Revocation

There may be deployments in which revocation of an access token is useful. The Token Revocation process is based upon [RFC7009]. The Consumer requests the revocation of a particular token by making an HTTP POST request (using TLS) to the token revocation endpoint URL.

The client constructs the request by including the following parameters using the "application/x-www-form-urlencoded" format in the HTTP request entity-body:

token

REQUIRED. The token that the client wants to get revoked.

token_type_hint

REQUIRED. MUST be set to access_token.

An example of the request message is shown below:

POST /revoke HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

token=45ghiukldjahdnhzdauz&token_type_hint=access_token
    

The authorization server responds with HTTP status code 200 if the token has been revoked successfully or if the client submitted an invalid token.

When the request for revocation is rejected the error presentation conforms to the definition in Section 5.2 of [RFC6749]. The following additional error code is defined for the token revocation endpoint:

unsupported_token_type

The authorization server does not support the revocation of the presented token type. That is, the client tried to revoke an access token on a server not supporting this feature.

4.2.1 Using JSON Web Tokens with OAuth 2.0 Authorization Code Grant

In this approach, a Consumer generates a JWT [RFC7519] bearer token as a means for authentication in requesting an OAuth 2.0 access token, which it can then use to authorize requests to services as per [RFC7523]. This is similar to the approach for using JSON Web Tokens with OAuth 2.0 Client-Credentials Grant (see Section 4.1). The JWT payload MUST use the same set of claims as listed in Section 4.1. When using the same set of values as per Section 4.1 this leads to a request with the following form (with line breaks for clarity):

POST /lti/auth/token HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
.eyJpc3MiOiJ0b29sLmNvbSIsInN1YiI6Ind3dy5leGFtcGxlLmNvbSIsImF1ZCI6Imh0dHBzOi8vd3d3LmV4YW1wbGUuY29tL2x0aS9hdXRoL3R
va2VuIiwiaWF0IjoiMTQ4NTkwNzIwMCIsImV4cCI6IjE0ODU5MDc1MDAiLCJqdGkiOiIyOWY5MGMwNDdhNDRiMmVjZTczZDAwYTA5MzY0ZDQ5YiJ9
.liArqLDIF-xGcCu8ythy0HlzntxwZ90AYTnwH-daCQQ
&scope=http%3A%2F%2Fimsglobal.org%2Fspec%2Flti-ags%2Fscope%2Flineitem%20http%3A%2F%2Fimsglobal.org%2Fspec%2Flti-ags%2Fscope%2Fresult%2Fread        

The authorization server decodes the JWT and MUST validate the values for the iss, sub, exp, aud and jti claims, followed by verifying the signature. If it finds the request to be a valid, it generates and returns an access token, with a response of this form:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token" : "dkj4985kjaIAJDJ89kl8rkn5",
    "token_type" : "bearer",
    "expires_in" : 3600,
    "scope" : "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem https://purl.imsglobal.org/spec/lti-ags/scope/result/read"    
}        

As per [RFC7519] the token MUST ONLY contain ASCII characters (0x20-0x7A) and SHOULD be at least 15 characters in length. The token MAY be a JWT (see below). 1EdTech recommends a default expiry time of 1 hour (3600 seconds). The bearer of the token can use it until the token expires (as evidenced by a failed request) but 1EdTech recommends that a Consumer manages tokens such that once they have expired (allowing for clock skew between the systems), it requests a new one when needed.

4.2.2 Token Refresh

When requesting an access token as part of the Authorization Code Grant process, an Authorization Server MAY return a 'Refresh Token'. The refresh token can be used to obtain new access tokens using the same authorization grant: this is described in Section 6 of [RFC6749]. The use of the Refresh Token avoids the choreography for obtaining the credentials to gain access to the Authorization Server.

The Consumer makes a refresh request to the token endpoint by adding the following parameters using the application/x-www-form-urlencoded format with a character encoding of UTF-8 in the HTTP request entity-body the set of parameters (Section 6 of [RFC6749]) used to request an access token are:

grant_type

REQUIRED. Value MUST be set to refresh_token.

refresh_token

REQUIRED. The refresh token issued to the Consumer.

scope

REQUIRED. The scope of the access request. The requested scope MUST NOT include any scope not originally granted by the resource owner.

An example of the request message is shown below in which two scopes (scopename1 and scopename2) are identified:

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&scope=scopename1%20scopename2
    		

If valid and authorized, the authorization server issues an access token as described earlier in Section 4.2 of this document. If the request failed verification or is invalid, the authorization server returns an error response as described earlier in Section 4.2 of this document.

The authorization server MAY issue a new refresh token, in which case the client MUST discard the old refresh token and replace it with the new refresh token. The authorization server MAY revoke the old refresh token after issuing a new refresh token to the client. If a new refresh token is issued, the refresh token scope MUST be identical to that of the refresh token included by the Consumer in the request.

4.2.3 Token Revocation

There may be deployments in which revocation of an access token is useful. The Token Revocation process is based upon [RFC7009]. The Consumer requests the revocation of a particular token by making an HTTP POST request (using TLS) to the token revocation endpoint URL. Note that [RFC7009] states that implementations MUST support the revocation of refresh tokens and SHOULD support the revocation of access tokens.

The client constructs the request by including the following parameters using the "application/x-www-form-urlencoded" format in the HTTP request entity-body:

token

REQUIRED. The token that the client wants to get revoked.

token_type_hint

REQUIRED. MUST be set to either access_token or refresh_token.

An example of the request message is shown below:

POST /revoke HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token
    

The authorization server responds with HTTP status code 200 if the token has been revoked successfully or if the client submitted an invalid token.

When the request for revocation is rejected the error presentation conforms to the definition in Section 5.2 of [RFC6749]. The following additional error code is defined for the token revocation endpoint:

unsupported_token_type

The authorization server does not support the revocation of the presented token type. That is, the client tried to revoke an access token on a server not supporting this feature.

4.3.1 Consumer Registration

The actual client registration starts when the Consumer posts a registration request to the authorization server (the mechanism for obtaining the specific endpoint is described in Obtaining the Registration URL). Use of an Initial Access Token with a client registration request is OPTIONAL. Use of the 'Software Statement' is NOT RECOMMENDED. Use of a Software Statement will be clarified in later versions of the Security Framework. The client registration request is sent to the client registration endpoint and the process for obtaining that URL is described in the next sub-section. The client registration request MUST be sent using HTTPS with the TLS 1.2 or 1.3 protocol.

The properties of the JSON body MUST be implemented as described in the following list. All URLs MUST use HTTPS (e.g. https://example.com/logo.png). All required properties MUST be present in the registration request in order for it to be accepted by the authorization server. Arrays MUST be used even when a single value is to be sent.

client_name

REQUIRED. The human-readable name of the Consumer.

client_uri

REQUIRED. URL string of a web page that which describes the Consumer.

tos_uri

REQUIRED. URL string that points to a human-readable Terms of Service document for the Consumer that describes a contractual relationship between the end-user and the client that the end-user accepts when authorizing the Consumer.

policy_uri

REQUIRED. URL string that points to a human-readable privacy policy document that describes how the deployment organization collects, uses, retains, and discloses personal data.

software_id

REQUIRED. A unique identifier string assigned by the Consumer developer or software publisher used by registration endpoints to identify the Consumer software to be dynamically registered. This value SHOULD remain the same for all instances of the Consumer software.

software_version

REQUIRED. A version identifier string for the Consumer software identified by software_id. The value of the software_version SHOULD change on any update to the Consumer software identified by the same software_id.

redirect_uris

REQUIRED ARRAY. The set of redirection URI strings for use in the OAuth 2.0 flow.

scope

REQUIRED. In the registration request, this is a string containing a space-separated list of scope values that this Consumer may include when requesting access tokens.

token_endpoint_auth_method

OPTIONAL. String indicator of the requested authentication method for the token endpoint. For the Security Framework, only permitted value is client_secret_basic. Therefore, the client uses the HTTP Basic as defined in OAuth 2.0 [RFC6749], Section 2.3.1. If omitted, the default is client_secret_basic.

grant_types

OPTIONAL ARRAY. Array of OAuth 2.0 grant type strings. The permitted values are:

• client_credentials - the client credentials grant type defined in OAuth 2.0
• authorization_code - the authorization code grant type defined in OAuth 2.0
• refresh_token - the refresh token grant type defined in OAuth 2.0

If the token endpoint is used in the grant type, the value of this parameter MUST be the same as the value of the grant_type parameter passed to the token endpoint defined in the grant type definition. If omitted, the default behavior is that the client will use only the authorization_code Grant Type.

response_types

OPTIONAL ARRAY. Array of the OAuth 2.0 response type strings that the Consumer can use at the authorization endpoint. The ONLY permitted value is code which denotes the authorization code response type defined in OAuth 2.0.

logo_uri

OPTIONAL. URL string that references a logo for the Consumer. If present, the server SHOULD display this image to the end-user during approval. The value of this field MUST point to a valid image file.

contacts

OPTIONAL ARRAY. Array of strings representing ways to contact people responsible for this Consumer, typically email addresses. The authorization server MAY make these contact addresses available to end-users for support requests for the Consumer. Privacy constraints MUST be supported as applicable

jwks_uri

OPTIONAL. URL string referencing the JSON Web Key (JWK) Set [RFC7517] document for the Consumer, which contains the client’s public keys. The value of this field MUST point to a valid JWK Set document. Use of this parameter is preferred over the jwks parameter, as it allows for easier key rotation. The jwks_uri and jwks parameters MUST NOT both be present in the same request or response.

jwks

OPTIONAL. Consumer JSON Web Key Set [RFC7517] document value, which contains the consumer’s public keys. The value of this field MUST be a JSON object containing a valid JWK Set. These keys can be used by higher-level protocols that use signing or encryption. This parameter is intended to be used by clients that cannot use the jwks_uri parameter, such as native clients that cannot host public URLs. The jwks_uri and jwks parameters MUST NOT both be present in the same request or response.

An example Client Registration request message is shown below.

POST https://clrauth.azurewebsites.net/connect/register HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8

{
    "client_name": "Example Consumer",
    "client_uri": "https://consumer.example.com/",
    "logo_uri": "https://consumer.example.com/logo.png",
    "tos_uri": "https://consumer.example.com/terms",
    "policy_uri": "https://consumer.example.com/privacy",
    "software_id": "c88b6ed8-269e-448e-99be-7e2ff47167d1",
    "software_version": "v4.0.30319",
    "redirect_uris": [
        "https://consumer.example.com/Authorize"
    ],
    "token_endpoint_auth_method": "client_secret_basic",
    "grant_types": [
        "authorization_code",
        "refresh_token"
    ],
    "response_types": [
        "code"
    ],
    "scope": "https://purl.imsglobal.org/spec/clr/v1p0/scope/delete https://purl.imsglobal.org/spec/clr/v1p0/scope/readonly https://purl.imsglobal.org/spec/clr/v1p0/scope/replace"
}
					

Several of the properties above require the provision of URIs. Use of these could be abused for server-side request forgery. Therefore the Security Considerations, Section 5 of [RFC7591], SHOULD be followed.

If the authorization server accepts the registration request, it will store the information provided in the request and respond HTTP 201 Created with a registration response that includes a set of client credentials for the Consumer to use when requesting access tokens. All the information provided by the Consumer MUST be returned to the Consumer, including modifications to the properties as the authorization server deems necessary. The Client Registration response body, for a successful request, MUST also contain the following information:

client_id

REQUIRED. OAuth 2.0 client identifier string. It SHOULD NOT be currently valid for any other registered Consumer.

client_secret

REQUIRED. OAuth 2.0 client secret string. This MUST be unique for each client_id and SHOULD be unique for multiple instances of a client using the same client_id. This value is used by confidential clients to authenticate to the token endpoint, as described in OAuth 2.0 [RFC6749], Section 2.3.1..

client_id_issued_at

REQUIRED. Time at which the client identifier was issued. The time is represented as the number of seconds from 1970-01-01T00:00:00Z as measured in UTC until the date/time of issuance.

client_secret_expires_at

REQUIRED. Time at which the client secret will expire or 0 if it will not expire. The time is represented as the number of seconds from 1970-01-01T00:00:00Z as measured in UTC until the date/time of expiration.

An example Client Registration response message for a successful request is shown below.

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
	"client_id": "4ad36680810420ed",
	"client_secret": "af7aa0d679778e12",
	"client_id_issued_at": 1565715850,
	"client_secret_expires_at": 1597338250,
	"client_name": "Example Consumer",
	"client_uri": "https://consumer.example.com/",
	"logo_uri": "https://consumer.example.com/logo.png",
	"tos_uri": "https://consumer.example.com/terms",
	"policy_uri": "https://consumer.example.com/privacy",
	"software_id": "c88b6ed8-269e-448e-99be-7e2ff47167d1",
	"software_version": "v4.0.30319",
	"redirect_uris": [
		"https://consumer.example.com/Authorize"
	],
	"token_endpoint_auth_method": "client_secret_basic",
	"grant_types": [
		"authorization_code",
		"refresh_token"
	],
	"response_types": [
		"code"
	],
	"scope": "https://purl.imsglobal.org/spec/clr/v1p0/scope/readonly"
}
					

When a registration error condition occurs, the authorization server returns an HTTP 400 status code (unless otherwise specified) with content type "application/json" consisting of a JSON object describing the error in the response body. The properties used are:

error

REQUIRED. Single ASCII error code string. The permitted value space is:

• invalid_redirect_uri - the value of one or more redirection URIs is invalid.
• invalid_client_metadata - the value of one of the Consumer metadata fields is invalid and the server has rejected this request. Note that an authorization server MAY choose to substitute a valid value for any requested parameter of a Consumer’s metadata.
• invalid_software_statement - the software statement presented is invalid. This MUST only be returned if a Software Statement has been supplied in the registration request. Use of a Software Statement is NOT RECOMMENDED.
• unapproved_software_statement - the software statement presented is not approved for use by this authorization server. This MUST only be returned if a Software Statement has been supplied in the registration request. Use of a Software Statement is NOT RECOMMENDED.

error_description

OPTIONAL. Human-readable ASCII text description of the error used for debugging.

4.3.2 Obtaining the Registration URL

To start the registration process, the Consumer must obtain the Provider's domain authority. When presented with an unknown Provider the Consumer MUST request the Provider's Service Description Document (SDD). The endpoint for reading the SDD is '.../discovery'. Rate-limited access to this endpoint is RECOMMENDED. An example request for an SDD takes the form of (this example is for an 1EdTech Comprehensive Learner Record based-service):

GET /ims/clr/v1p0/discovery HTTP/1.1
Host: provider.example.com
Accept: application/json     
    				

Access to the discovery endpoint MUST NOT be protected. The SDD MUST be provided over HTTPS with TLS 1.2 or 1.3.

The response to this request is the SDD supplied as a JSON encoded payload. The structure and format of this payload MUST follow that of the OpenAPI 3.0 Specification [OAS3P0]. The SDD being supplied MUST be a profiled version of the OpenAPI 3.0 (JSON) file provided as one of the artifacts released as part of the definition of an 1EdTech service specification. This profiled version contains all of the details about the supported set of service end-points, the supported optional data fields, definitions of the proprietary data fields supplied using the permitted extension mechanisms, definitions of the available proprietary endpoints, and information about the security mechanisms.

The URL for the Client Registration MUST be contained in the property named x-imssf-registrationUrl. This is an 1EdTech controlled extension to the OpenAPI specification. This new property is inserted into the securitySchemes within the components section of the OpenAPI file structure. An example of the partial OpenAPI file is shown below.

...
"components" : {
    "securitySchemes" : {
        "OAuth2CCG" : {
            "type" : "oauth2",
            "description" : "OAuth 2.0 Client Credentials authorization",
            "x-imssf-registrationUrl" : "provider.example.com/registration",
            "flows" : {
                "clientCredentials" : {
                    "tokenUrl" : "provider.example.com/token",
                    "scopes" : {
                        "https://purl.imsglobal.org/spec/clr/v1p0/scope/delete" : "...",
                        "https://purl.imsglobal.org/spec/clr/v1p0/scope/readonly" : "...",
                        "https://purl.imsglobal.org/spec/clr/v1p0/scope/replace" : "..."
                    }
                }
            }
        },
        "OAuth2ACG" : {
            "type" : "oauth2",
            "description" : "OAuth 2.0 Authorization Code Grant authorization",
            "x-imssf-registrationUrl" : "provider.example.com/registration",
            "flows" : {
                "authorizationCode" : {
                    "tokenUrl" : "provider.example.com/token",
                    "authorizationUrl" : "provider.example.com/authorize",
                    "refreshUrl" : "provider.example.com/token",
                    "scopes" : {
                        "https://purl.imsglobal.org/spec/clr/v1p0/scope/delete" : "...",
                        "https://purl.imsglobal.org/spec/clr/v1p0/scope/readonly" : "...",
                        "https://purl.imsglobal.org/spec/clr/v1p0/scope/replace" : "..."
                    }
                }
            }
        }
    },
    "schemas" : {
                 ...
    }
}
...
					

A more detailed example is given in the Appendices.

An implementation MAY also provide the OpenAPI 3.0 (YAML) file. YAML files permit human-readable annotations of the contents - this is not possible with the JSON equivalent. Access to the YAML-based version of the OpenAPI file is outside the scope of this framework.

Upon receiving a SDD from a Provider, the requester SHOULD respect the Cache-Control and Expires headers if present in the response and configure local cache to match the directives it declares. If directives include one of no-cache, no-store, the requester SHOULD NOT cache the data for future interactions. If directives include max-age or if an Expires header is present, the requester SHOULD cache the SDD data, if valid, up to the expiration indicated, either at the time indicated by the Expires header or max-age seconds from request time.

4.3.3 Consumer Registration Management

There will be some scenarios in which the Consumer registration information may need to be read, and/or changed and/or deleted. Management of client registration information is covered in [RFC7592]: 'OAuth 2.0 Dynamic Client Registration Management Protocol'. Support for Client Registration Management is OPTIONAL. If a binding of an 1EdTech service specification wishes to make Client Registration Management available, the following MUST be completed:

• The functionality MUST comply with the [RFC7952] and the subset of features to be used MUST be clearly identified. For example only some of read, update and delete capabilities may be available
• The conformance requirements, in the corresponding Conformance & Certification document, MUST state whether support for Client Registration Management is OPTIONAL or REQUIRED. Support of the features available in [RFC7952] MUST be identified as either OPTIONAL or REQUIRED
• Access to the Client Registration Management endpoints MUST be secured as per [RFC6750] (the appropriate registration access token MUST be supplied in the response to the Consumer Registration request). The security considerations addressed in Section 5 [RFC7592], 'Security Considerations', MUST be followed
• The client registration management information exchange MUST be secured at the transport-layer using either TLS 1.2 or TLS 1.3.

5.1.1 OpenID Connect Launch Flow Overview

The Implicit Flow exchange consists of the 6 steps as defined in Section 3.2.1 of OpenID Connect Core [OPENID-CCORE]. However, in order to stop the work flow being vulnerable to the 'Login Cross-Site Request Forgery (CSRF)' each message request MUST be treated as a 3rd party initiated login, as defined in OpenID Connect: Initiating Login from a Third Party, which triggers an OpenID Connect Implicit flow between the tool, acting as the Relying Party, and the platform, acting as the Identity Provider.

In 3rd party initiated login, the login flow is initiated by an OpenID Provider or another party, rather than the Relying Party. In this case, the initiator redirects to the Relying Party at its login initiation endpoint, which requests that the Relying Party send an Authentication Request to a specified OpenID Provider. This login initiation endpoint can be a deep link at the Relying Party, rather than a default landing page.

The OpenID Connect launch flow is shown in Figure 7.

As part of the out-of-band registration process the following information must also be distributed:

• The Tool must provide the single URL that the Platform will use to initiate the OpenID Connect authorization flow (called the '3rd Party initiated login end-point');

• The Tool must provide one or multiple redirect URIs that are valid end points where the authorization response can be sent. The number of distinct redirect URIs to be supported by a platform is not specified;

• The Platform must provide the single end-point to which the browser will be redirected, by the Tool, to initiate the OpenID Connect authentication flow (called the OIDC Authorization end-point').

5.1.2 ID Token

In order to enable the authentication of end users, OpenID Connect extends OAuth 2.0 with the ID Token data structure. The ID Token is a security token that contains Claims about the Authentication of an end user made by an authorization server when using a Tool, and potentially other requested Claims. The ID Token is represented as a JWT [RFC7519] and the JWS is produced using the Platform's Private Key. See Section 2 of [OPENID-CCORE] for more information regarding the ID Token.

The ID Token uses these Claims:

iss

REQUIRED. Issuer Identifier for the Issuer of the message i.e. the Platform. The iss value is a case-sensitive URL using the HTTPS scheme that contains: scheme, host; and, optionally, port number, and path components; and, no query or fragment components.

aud

REQUIRED. Audience(s) for whom this ID Token is intended i.e. the Tool. It MUST contain the OAuth 2.0 client_id of the Tool as an audience value. It MAY also contain identifiers for other audiences. In the general case, the aud value is an array of case-sensitive strings. In the common special case when there is one audience, the aud value MAY be a single case-sensitive string. It is RECOMMENDED that an array is used even when only a single value is to be sent.

sub

REQUIRED. Subject Identifier. A locally unique and never reassigned identifier within the Issuer for the end user, which is intended to be consumed by the Tool, (for example, it might be something like 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4). It MUST NOT exceed 255 ASCII characters in length. The sub value is a case-sensitive string. This MUST be the same value as the Platform's User ID for the end user.

exp

REQUIRED. Expiration time on or after which the Tool MUST NOT accept the ID Token for processing. When processing this parameter, the Tool MUST verify that the time expressed in this Claim occurs after the current date/time. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. This Claim's value MUST be a JSON number representing the number of seconds offset from 1970-01-01T00:00:00Z (UTC). See [RFC3339] for details regarding date/times in general and UTC in particular.

iat

REQUIRED. Time at which the Issuer generated the JWT. Its value is a JSON number representing the number of seconds offset from 1970-01-01T00:00:00Z (UTC) until the generation time.

nonce

REQUIRED. String value used to associate a Tool session with an ID Token, and to mitigate replay attacks. The nonce value is a case-sensitive string.

azp

OPTIONAL. Authorized party - the party to which the ID Token was issued. If present, it MUST contain the OAuth 2.0 Tool ID of this party. This Claim is only needed when the Token has a single audience value and that audience is different than the authorized party. It MAY be included even when the authorized party is the same as the sole audience. The azp value is a case-sensitive string containing a String or URI value.

The Claims in an ID Token JWT might look like this (non-normative) example:

{
    "iss": "https://lms.uofexample.edu",             // Platform Issuer Identifier
    "sub": "24400320",                               // Subject Identifier of the User
    "aud": "s6BhdRkqt3",                             // Client Identifier for the Client
    "nonce": "n-0S6_WzA2Mj",
    "exp": 1311281970,
    "iat": 1311280970
}          
        

The User information passed upon launch depends upon relevant privacy settings the Platform must apply. At a minimum, the Platform must present a permanent identifier for the user in the sub Claim.

5.1.3 Authentication Response Validation

Tools MUST validate the ID Token in the token response in the following manner:

1. The Tool MUST Validate the signature of the ID Token according to JSON Web Signature [RFC7515], Section 5.2 using the Public Key from the Platform;

2. The Issuer Identifier for the Platform MUST exactly match the value of the iss (Issuer) Claim (therefore the Tool MUST previously have been made aware of this identifier);

3. The Tool MUST validate that the aud (audience) Claim contains its client_id value registered as an audience with the Issuer identified by the iss (Issuer) Claim. The aud (audience) Claim MAY contain an array with more than one element. The Tool MUST reject the ID Token if it does not list the client_id as a valid audience, or if it contains additional audiences not trusted by the Tool. The request message will be rejected with a HTTP code of 401;

4. If the ID Token contains multiple audiences, the Tool SHOULD verify that an azp Claim is present;

5. If an azp (authorized party) Claim is present, the Tool SHOULD verify that its client_id is the Claim's value;

6. The alg value SHOULD be the default of RS256 or the algorithm sent by the Tool in the id_token_signed_response_alg parameter during its registration. The approved list of algorithms that MUST be used is given in the Best Practices;

7. The current time MUST be before the time represented by the exp Claim;

8. The Tool MAY use the iat Claim to reject tokens that were issued too far away from the current time, limiting the amount of time that it needs to store nonces used to prevent attacks. The Tool MAY define its own acceptable time range;

9. The ID Token MUST contain a nonce Claim. The Tool SHOULD verify that it has not yet received this nonce value (within a Tool-defined time window), in order to help prevent replay attacks. The Tool MAY define its own precise method for detecting replay attacks.

5.2.1 Form Parameter

The sender sends the JWT via a form HTTP POST with a single parameter:

JWT (REQUIRED). JWS-signed token containing the Message Claims. The JWS is produced using the Tool's Private Key.

5.2.2 Tool JWT

The Tool JWT is a security token which contains Claims about the Authentication of an end user made by an authorization server when using a Tool, and potentially other requested Claims. The Tool JWT is represented as a JWT [RFC7519].

The Tool JWT uses these claims:

iss

REQUIRED. Issuer Identifier for the Issuer of the message i.e. the Tool. It must be the OAuth 2.0 client_id of the Tool (this MAY be provided to it by the Platform upon registration of the Tool).

aud

REQUIRED. Audience(s) for whom this Tool JWT is intended. It MUST contain the case-sensitive URL used by the Platform to identify itself as an Issuer in platform-originating Messages. In the common special case when there is one audience, the aud value MAY be a single case-sensitive string. It is RECOMMENDED that an array is used even when only a single value is to be sent.

exp

REQUIRED. Expiration time on or after which the Platform MUST NOT accept the Tool JWT for processing. When processing this parameter, the Platform MUST verify that the time expressed in this Claim occurs after the current date/time. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew (see the Best Practice Recommendations on compensating for clock skew). This Claim's value MUST be a JSON number representing the number of seconds offset from 1970-01-01T00:00:00Z (UTC). See [RFC3339] for details regarding date/times in general and UTC in particular.

iat

REQUIRED. Time at which the Issuer generated the Tool JWT. Its value is a JSON number representing the number of seconds offset from 1970-01-01T00:00:00Z (UTC) until the generation time.

nonce

REQUIRED. String value used to associate a Tool session with a Tool JWT, and to mitigate replay attacks. The nonce value is a case-sensitive string.

azp

OPTIONAL. Authorized party - the party to which the Tool JWT was issued. If present, it MUST contain the same value as in the aud Claim. The azp value is a case-sensitive string containing a String or URI value.

The Claims in a Tool JWT might look like this (non-normative) example:

{
    "iss": "s6BhdRkqt3",                               // Client Identifier of the Client
    "aud": "https://lms.uofexample.edu",               // Platform Issuer Identifier
    "nonce": "n-0S6_WzA2Mj",
    "exp": 1311281970,
    "iat": 1311280970
}          

5.2.3 Authentication Response Validation

Platforms MUST Validate the Message Tool JWT in the Token Response in the following manner:

1. The Platform MUST validate the signature of the Tool JWT according to JSON Web Signature [RFC7518] using the algorithm the Tool specifies in the alg header parameter of the JOSE Header. The Platform must use the Public Key from the Tool to validate the message;

2. The client_id for the Tool MUST exactly match the value of the iss (Issuer) Claim;

3. The Platform MUST validate that the aud (audience) Claim contains its advertised Issuer URL. The Platform must reject the Tool JWT if it does not list the Platform as a valid audience, or if it contains additional audiences not trusted by the Platform;

4. If the Token contains multiple audiences, the Platform SHOULD verify that an azp Claim is present;

5. If an azp (authorized party) Claim is present, the Platform SHOULD verify that its Issuer URL is the Claim Value.

6. The alg value SHOULD be the default of RS256 or the algorithm specified by the Platform to the Tool during registration. The approved list of algorithms that MUST be used is given in the Best Practices;

7. The current time MUST be before the time represented by the exp Claim;

8. The Platform MAY use the iat to reject tokens that were issued to far away from the current time, limiting the amount of time that it needs to store nonces used to prevent attacks. The Platform MAY define its own acceptable time range;

9. The Tool JWT MUST contain a nonce Claim. The Platform SHOULD verify that it has not yet received this nonce value (within a Platform-defined time window), in order to prevent replay attacks. The Platform MAY define its own precise method for detecting replay attacks.

5.5.1 Dynamic Registration Protocol Overview

This registration protocol uses the OIDC Discovery [OPENID-DIS] and OIDC Dynamic Client Registration [OPENID-DCR] specifications. In the context of this specification, the Tool plays the role of the Consumer (or Client or Relying Party), and the Platform the one of the OpenID Provider. Therefore, the registration is done in four phases:

1. The Platform initiates the registration by using the initiate registration endpoint supplied by the Tool. This is mediated by the browser, typically by opening an IFrame to the initiate registration end-point. The tool may include a User Interface (UI) to complete the registration on the tool side;
2. The tool discovers the platform's OpenID configuration using the provided openid-configuration endpoint, as defined in OIDC Discovery [OPENID-DIS] specification;
3. The tool uses the registration endpoint present in the OpenID configuration to request a registration as per OIDC Dynamic Client Registration [OPENID-DCR] specification. The platform must immediately grant or deny the registration. A successful registration means the tool is properly configured, but it is not activated yet;
4. The platform administrator may then review, alter, reject or activate the newly added registration.

The choreography for the OpenID Connect-based dynamic client registration process is shown in Figure 9.

While the openid-configuration exposes the platform's offered capabilities to the tool, and the tool's registration includes the scopes and claims it requests access for, this process is not aimed at negotiating a contract. A Platform should accept a registration and actually allow only a subset of the required capabilities, reflected in the returned tool's registration. Furthermore, a platform admin may always either restrict or extend the offered capabilities (claims, scopes, variables) to a given tool. As usual, a Tool should not make assumptions about what is available and handle gracefully the cases were some capabilities such as claims and/or services are not exposed.

5.5.2 Registration Initiation Request (Step 1)

The registration initiation launch allows the registration flow to be triggered from the platform UI, typically by opening an IFrame or a new Tab to that endpoint. How the initiate registration request endpoint is shared is not specified and happens out-of-band. It may be the same registration endpoint for all registration requests or specific for a given registration request. For example the tool may generate a specific registration URL for each institution and communicate it to the platform administrator to trigger the registration.

The initiation launch is a User Agent redirect to the initiation registration URL and appends the following query parameters to the URL:

openid_configuration

REQUIRED. The endpoint to the open id configuration to be used for this registration, encoded as per [RFC3986] Section 3.4.

registration_token

OPTIONAL. the registration access token. If present, it must be used as the access token by the tool when making the registration request to the registration endpoint exposed in the OpenID configuration.

The registration token MUST be:

• Short lived - typically 1 hour to allow enough time for some UI interaction on the tool side happening before the actual registration request is made
• Usable only once - the token must not allow more than one registration.

5.5.3 Discovery and OpenID Configuration (Step 2)

This section follows the OIDCDiscovery specification [OPENID-DIS] but relaxes the requirement on the OpenID Configuration Endpoint's URL since the URL is actually passed during the initiate registration request, allowing the platform to possibly tailor a configuration for a given registration.

The Platform must make to the OpenID Configuration URL's endpoint as a path concatenated with the Issuer. If applicable, the appended path should be the OIDCDiscovery defined /.well-known/openid-configuration. The URL may also contain query parameters. The URL must not contain any fragment parameter. For example, considering the OpenID Configuration declares the issuer as https://platform.example.com, the following URLs would be valid OpenID Configuration endpoints:

• https://platform.example.com/.well-known/openid-configuration
• https://platform.example.com/.well-known/openid-configuration?r=7462647772
• https://platform.example.com/.well-known/lti-openid-configuration
• https://platform.example.com/lti/openid-configuration
• https://platform.example.com/lti/openid-configuration/reg/849021

The following URLs are not valid and a Tool must abort the registration:

• https://attacker.io/.well-known/openid-configuration
• https://platform.example.org/.well-known/openid-configuration
• https://lti.platform.example.com/openid-configuration
• https://example.com/.well-known/openid-configuration

The Tool receives the OpenID configuration endpoint as a query parameter in the initiate registration request. The tool must not make any assumption about the OpenID configuration endpoint time-to-live, nor should it assume that the endpoint is meant to be shared and/or reused for other registration requests. For example, a platform may issue a short lived endpoint to a specific tool administrator so that registration can be initiated; the registration endpoint present in the OpenID configuration would then be a single usage endpoint, only allowing a single tool to be registered. Registering another tool would require the platform to deliver another openid-configuration endpoint to the tool's administrator.

An OpenID Provider Configuration Document MUST be queried using an HTTP GET request at the previously specified path. The response is a set of Claims about the OpenID Provider's configuration, including all necessary endpoints and public key location information. A successful response MUST use the 200 OK HTTP status code and return a JSON object using the application/json content type that contains a set of Claims as its members that are a subset of the metadata values defined below. Other Claims MAY also be returned.

The properties to be used for the Platform configuration payload are based upon the definitions in Section 3 of the OpenID Connect Discovery 1.0 specification [OPENID-DIS]. The properties of the JSON body MUST be implemented as described in the following list. All URLs MUST use HTTPS (e.g. https://example.com/logo.png). All required properties MUST be present in the configuration request in order for it to be accepted by the tool. Arrays MUST be used even when a single value is to be sent. Claims with zero elements MUST be omitted from the response.

issuer

REQUIRED. Platform's issuer value. A URL using the https scheme with no query or fragment component that the OpenID Provider asserts as its Issuer Identifier.

authorization_endpoint

REQUIRED. URL of the OAuth 2.0 Authorization Endpoint as per [OPENID-CCORE].

token_endpoint

REQUIRED. URL of the endpoint for the tool to request a token to access services.

jwks_uri

REQUIRED. URL of the Platform JWK Set endpoint. This may be specific per registration if the platform's issued a dedicated discovery end-point for that registration.

registration_endpoint

REQUIRED. URL of the registration endpoint. It MAY be a one time use only end-point and/or protected by access token. See [OPENID-DIS].

scopes_supported

REQUIRED ARRAY. MUST contain openid and the scopes of the supported services.

response_types_supported

REQUIRED ARRAY. MUST contain id_token and MAY offer additional values.

subject_types_supported

REQUIRED ARRAY. An array of supported Subject Identifiers as defined OpenID Core 1.0 specifications. Valid types are public (indicates the same sub is passed across tools for a given end-user) and pairwise (indicates a different sub value will be passed to different tools for the same end-user).

id_token_signing_alg_values_supported

REQUIRED ARRAY. MUST contain RS256 and MAY offer additional values. The approved list of algorithms that MUST be used is given in the Best Practices.

token_endpoint_auth_methods_supported

REQUIRED ARRAY. MUST contain private_key_jwt and MAY offer additional values.

token_endpoint_auth_signing_alg_values_supported

REQUIRED ARRAY. MUST contain RS256 and MAY offer additional values. The approved list of algorithms that MUST be used as the value of alg is given in the Best Practices.

claims_supported

REQUIRED ARRAY. OpenID claims supported by this Platform.

authorization_server

OPTIONAL. The authorization server identifier to be used as the aud when requesting an access token. If not specified, the tool must use the token_endpoint as the aud value when requesting an access token.

userinfo_endpoint

OPTIONAL. URL of the Platform's UserInfo Endpoint [OPENID-CCORE]. This URL MUST use the https scheme and MAY contain port, path, and query parameter components.

response_modes_supported

OPTIONAL ARRAY. response_mode values that this Platform supports, as specified in OAuth 2.0 Multiple Response Type Encoding Practices [OAUTH2-RESP]. If omitted, the default for Dynamic OpenID Providers is [query, fragment].

grant_types_supported

OPTIONAL ARRAY. Contains a list of the OAuth 2.0 Grant Type values that this Platform supports. Dynamic OpenID Providers MUST support the authorization_code and implicit Grant Type values and MAY support other Grant Types. If omitted, the default value is [authorization_code, implicit]. Use of the implicit grant MUST only be used in the context of OpenID Connect.

acr_values_supported

OPTIONAL ARRAY. Contains a list of the Authentication Context Class References that this Platform supports.

id_token_encryption_alg_values_supported

OPTIONAL ARRAY. Contains a list of the JWE encryption algorithms (alg values) supported by the Platform for the ID Token to encode the Claims in a JWT [RFC7519]

id_token_encryption_enc_values_supported

OPTIONAL ARRAY. Contains a list of the JWE encryption algorithms (enc values) supported by the Platform for the ID Token to encode the Claims in a JWT [RFC7519].

userinfo_signing_alg_values_supported

OPTIONAL ARRAY. Contains a list of the JWS signing algorithms (alg values) [RFC7518] supported by the UserInfo Endpoint to encode the Claims in a JWT [RFC7519]. The value none MAY be included.

userinfo_encryption_alg_values_supported

OPTIONAL ARRAY. Contains a list of the JWE encryption algorithms (alg values) [RFC7518] supported by the UserInfo Endpoint to encode the Claims in a JWT [RFC7519].

userinfo_encryption_enc_values_supported

OPTIONAL ARRAY. Contains a list of the JWE encryption algorithms (enc values) [RFC7518] supported by the UserInfo Endpoint to encode the Claims in a JWT [RFC7519].

request_object_signing_alg_values_supported

OPTIONAL ARRAY. Contains a list of the JWS signing algorithms (alg values) supported by the Platform for Request Objects, which are described in Section 6.1 of OpenID Connect Core 1.0 [OPENID-CCORE]. These algorithms are used both when the Request Object is passed by value (using the request parameter) and when it is passed by reference (using the request_uri parameter). Servers MUST support none and RS256. The approved list of algorithms that MUST be used is given in the Best Practices.

request_object_encryption_alg_values_supported

OPTIONAL ARRAY. Contains a list of the JWE encryption algorithms (alg values) supported by the Platform for Request Objects. These algorithms are used both when the Request Object is passed by value and when it is passed by reference.

request_object_encryption_enc_values_supported

OPTIONAL ARRAY. Contains a list of the JWE encryption algorithms (enc values) supported by the Platform for Request Objects. These algorithms are used both when the Request Object is passed by value and when it is passed by reference.

display_values_supported

OPTIONAL ARRAY. Contains a list of the display parameter values that the OpenID Provider supports. These values are described in Section 3.1.2.1 of OpenID Connect Core 1.0 [OPENID-CCORE].

claim_types_supported

OPTIONAL ARRAY. Contains a list of the Claim Types that the OpenID Provider supports. These Claim Types are described in Section 5.6 of OpenID Connect Core 1.0 [OPENID-CCORE]. Values defined by this specification are normal, aggregated, and distributed. If omitted, the implementation supports only normal Claims.

service_documentation

OPTIONAL. URL of a page containing human-readable information that developers might want or need to know when using the Platform. In particular, if the OpenID Provider does not support Dynamic Client Registration, then information on how to register Clients needs to be provided in this documentation.

claims_locales_supported

OPTIONAL ARRAY. Languages and scripts supported for values in Claims being returned, represented as a JSON array of BCP47 [RFC5646] language tag values. Not all languages and scripts are necessarily supported for all Claim values.

ui_locales_supported

OPTIONAL ARRAY. Languages and scripts supported for the user interface, represented as a JSON array of BCP47 [RFC5646] language tag values.

claims_parameter_supported

OPTIONAL. Boolean value specifying whether the Platform supports use of the claims parameter, with true indicating support. If omitted, the default value is false.

request_parameter_supported

OPTIONAL. Boolean value specifying whether the Platform supports use of the request parameter, with true indicating support. If omitted, the default value is false.

request_uri_parameter_supported

OPTIONAL. Boolean value specifying whether the Platform supports use of the request_uri parameter, with true indicating support. If omitted, the default value is true.

require_request_uri_registration

OPTIONAL. Boolean value specifying whether the Platform requires any request_uri values used to be pre-registered using the request_uris registration parameter. Pre-registration is REQUIRED when the value is true. If omitted, the default value is false.

op_policy_uri

OPTIONAL. URL that the Platform provides to the person registering the Tool to read about the Platform's requirements on how the Relying Party can use the data provided by the Platform. The registration process SHOULD display this URL to the person registering the Tool if it is given.

op_tos_uri

OPTIONAL. URL that the Platform provides to the person registering the Client to read about Platform's terms of service. The registration process SHOULD display this URL to the person registering the Client if it is given.

A non-normative example response payload is given below:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "issuer": "https://server.example.com",
    "authorization_endpoint":  "https://server.example.com/connect/authorize",
    "token_endpoint": "https://server.example.com/connect/token",
    "token_endpoint_auth_methods_supported": ["private_key_jwt"],
    "token_endpoint_auth_signing_alg_values_supported": ["RS256"],
    "jwks_uri": "https://server.example.com/jwks.json",
    "registration_endpoint": "https://server.example.com/connect/register",
    "scopes_supported": ["openid", 
       "https://purl.imsglobal.org/spec/lti-gs/scope/contextgroup.readonly",
       "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"],
    "response_types_supported": ["id_token"],
    "subject_types_supported": ["public", "pairwise"],
    "id_token_signing_alg_values_supported": ["RS256", "ES256"],
    "claims_supported": ["sub", "iss", "name", "given_name", "family_name", "nickname", 
                         "picture", "email", "locale"]
}
					

The issuer value returned MUST be identical to the Issuer URL that was directly used to retrieve the configuration information. This MUST also be identical to the iss Claim value in ID Tokens issued from this Issuer.

5.5.4 Client Registration (Step 3)

This section follows the OpenID Connect Dynamic Client Registration [OPENID-DCR] specification. The tool requests a registration using the registration_endpoint advertised in the openid-configuration. As per [OPENID-DCR] Section 3, this end point should preferably be open but may be short lived; a platform may require the tool to include an initial access token in the request. If so, the registration initiation request will include the token to use for that registration request. To to guard against impersonation attacks, a tool must validate the OpenID Configuration URL using the rules described in the previous section and reject the registration request if the validation fails.

The properties of the JSON body MUST be implemented as described in the following list. All URLs MUST use https (e.g. https://example.com/logo.png) and all URLs MUST have the same hostname. All required properties MUST be present in the configuration request in order for it to be accepted by the tool. Arrays MUST be used even when a single value is to be sent. Claims with zero elements MUST be omitted from the response.

application_type

REQUIRED. Kind of the application. This MUST have a value of web.

redirect_uris

REQUIRED ARRAY. Redirection URI values MUST exactly match the redirect_uri parameter value used in each Authorization Request, with the matching performed as described in Section 6.2.1 of [RFC3986] (Simple String Comparison).

response_types

REQUIRED ARRAY. Containing a list of the OAuth 2.0 response_type values that the Tool is declaring that it will restrict itself to using.

grant_types

REQUIRED ARRAY. The list of the OAuth 2.0 Grant Types that the Client is declaring that it will restrict itself to using. The Grant Type values used by OpenID Connect are:

• client_credentials
• authorization_code
• implicit
• implicit_token

The following table lists the correspondence between response_type values that the Tool will use and grant_type values that MUST be included in the registered grant_types list:

• code maps to authorization_code, client_credentials
• id_token maps to implicit, client_credentials
• code id_token maps to implicit
• code_token maps to authorization_code, implicit, client_credentials
• code token id_token maps to authorization_code, implicit, client_credentials

If omitted, the default is that the Client will use only the authorization_code Grant Type.

initiate_login_uri

REQUIRED. URI using the https scheme that a third party can use to initiate a login by the Tool, as specified in Section 4 of OpenID Connect Core 1.0 [OPENID-CCORE]]. The URI MUST accept requests via both GET and POST. The Tool MUST understand the login_hint and iss parameters and SHOULD support the target_link_uri parameter.

client_name

REQUIRED. Name of the Tool to be presented to the End-User. If desired, representation of this Claim in different languages and scripts is represented as described in Section 2.1 of [OPENID-DCR].

jwks_uri

REQUIRED. URL for the Tool's JSON Web Key Set document. If the Tool signs requests to the Server, it contains the signing key(s) the Server uses to validate signatures from the Client. The JWK Set MAY also contain the Tool's encryption keys(s), which are used by the Server to encrypt responses to the Tool. When both signing and encryption keys are made available, a use (Key Use) parameter value is REQUIRED for all keys in the referenced JWK Set to indicate each key's intended usage. Although some algorithms allow the same key to be used for both signatures and encryption, doing so is NOT RECOMMENDED, as it is less secure.

token_endpoint_auth_method

REQUIRED. Requested Client Authentication method for the Token Endpoint. The value MUST be private_key_jwt.

scope

REQUIRED. In the registration request, this is a string containing a space-separated list of scope values that this Tool MUST include when requesting access tokens. If omitted, the authorization server MAY register a Consumer with a default set of scopes. In the registration response, this is a list of scopes the authorization server supports.

logo_uri

OPTIONAL. URL that references a logo for the Tool application. If present, the server SHOULD display this image to the End-User during approval. The value of this field MUST point to a valid image file. If desired, representation of this Claim in different languages and scripts is represented as described in Section 2.1 [OPENID-DCR].

contacts

OPTIONAL ARRAY. Array of e-mail addresses of people responsible for this Client. This might be used by some providers to enable a Web user interface to modify the Client information.

client_uri

OPTIONAL. URL of the home page of the Tool. The value of this field MUST point to a valid Web page. If present, the server SHOULD display this URL to the End-User in a followable fashion. If desired, representation of this Claim in different languages and scripts is represented as described in Section 2.1 [OPENID-DCR].

policy_uri

OPTIONAL. URL that the Tool provides to the End-User to read about how the profile data will be used. The value of this field MUST point to a valid web page. The Platform SHOULD display this URL to the End-User if it is given. If desired, representation of this Claim in different languages and scripts is represented as described in Section 2.1 [OPENID-DCR].

tos_uri

OPTIONAL. URL that the Tool provides to the End-User to read about the Tool's terms of service. The value of this field MUST point to a valid web page. The Platform SHOULD display this URL to the End-User if it is given. If desired, representation of this Claim in different languages and scripts is represented as described in Section 2.1 [OPENID-DCR].

jwks

PROHIBITED. In the 1EdTech Security Framework use of the jwks_uri property is REQUIRED and so, as defined in [OPENID-DCR], use of the jwks is PROHIBITED.

sector_identifier_uri

OPTIONAL. URL using the https scheme to be used in calculating Pseudonymous Identifiers by the Platform. The URL references a file with a single JSON array of redirect_uri values.

subject_type

OPTIONAL. Subject type requested for responses to this Tool. The subject_types_supported Discovery parameter contains a list of the supported subject_type values for this server. Valid types include pairwise and public.

id_token_signed_response_alg

OPTIONAL. JWS alg algorithm REQUIRED for signing the ID Token issued to this Tool. The value none MUST NOT be used as the ID Token alg value unless the Tool uses only Response Types that return no ID Token from the Authorization Endpoint (such as when only using the Authorization Code Flow). The default, if omitted, is RS256. The approved list of algorithms that MUST be used is given in the Best Practices. The public key for validating the signature is provided by retrieving the JWK Set referenced by the jwks_uri element from OpenID Connect Discovery 1.0 [OPENID-DIS].

id_token_encrypted_response_alg

OPTIONAL. JWE alg algorithm REQUIRED for encrypting the ID Token issued to this Tool. If this is requested, the response will be signed then encrypted, with the result being a Nested JWT, as defined in [RFC7519]. The default, if omitted, is that no encryption is performed.

id_token_encrypted_response_enc

OPTIONAL. JWE enc algorithm REQUIRED for encrypting the ID Token issued to this Client. If id_token_encrypted_response_alg is specified, the default for this value is A128CBC-HS256. When id_token_encrypted_response_enc is included, id_token_encrypted_response_alg MUST also be provided.

userinfo_signed_response_alg

OPTIONAL. JWS alg algorithm REQUIRED for signing UserInfo Responses. If this is specified, the response will be JWT [RFC7519] serialized, and signed using JWS. The default, if omitted, is for the UserInfo Response to return the Claims as a UTF-8 encoded JSON object using the application/json content-type.

userinfo_encrypted_response_alg

OPTIONAL. JWE alg algorithm REQUIRED for encrypting UserInfo Responses. If both signing and encryption are requested, the response will be signed then encrypted, with the result being a Nested JWT, as defined in [RFC7519]. The default, if omitted, is that no encryption is performed.

userinfo_encrypted_response_enc

OPTIONAL. JWE enc algorithm REQUIRED for encrypting UserInfo Responses. If userinfo_encrypted_response_alg is specified, the default for this value is A128CBC-HS256. When userinfo_encrypted_response_enc is included, userinfo_encrypted_response_alg MUST also be provided.

request_object_signing_alg

OPTIONAL. JWS alg algorithm that MUST be used for signing Request Objects sent to the Platform. All Request Objects from this Tool MUST be rejected, if not signed with this algorithm. Request Objects are described in Section 6.1 of OpenID Connect Core 1.0 [OPENID-CCORE]. This algorithm MUST be used both when the Request Object is passed by value (using the request parameter) and when it is passed by reference (using the request_uri parameter). Servers SHOULD support RS256. The value none MAY be used. The default, if omitted, is that any algorithm supported by the Platform and the Tool MAY be used.

request_object_encryption_alg

OPTIONAL. JWE alg algorithm the Tool is declaring that it may use for encrypting Request Objects sent to the Platform. This parameter SHOULD be included when symmetric encryption will be used, since this signals to the Platform that a client_secret value needs to be returned from which the symmetric key will be derived, that might not otherwise be returned. The Tool MAY still use other supported encryption algorithms or send unencrypted Request Objects, even when this parameter is present. If both signing and encryption are requested, the Request Object will be signed then encrypted, with the result being a Nested JWT, as defined in [RFC7519]. The default, if omitted, is that the RP is not declaring whether it might encrypt any Request Objects.

request_object_encryption_enc

OPTIONAL. JWE enc algorithm the Tool is declaring that it may use for encrypting Request Objects sent to the Platform. If request_object_encryption_alg is specified, the default for this value is A128CBC-HS256. When request_object_encryption_enc is included, request_object_encryption_alg MUST also be provided.

token_endpoint_auth_signing_alg

OPTIONAL. JWS alg algorithm that MUST be used for signing the JWT [RFC7519] used to authenticate the Client at the Token Endpoint for the private_key_jwt and client_secret_jwt authentication methods. All Token Requests using these authentication methods from this Client MUST be rejected, if the JWT is not signed with this algorithm. The approved list of algorithms that MUST be used is given in the Best Practices. The value none MUST NOT be used. The default, if omitted, is that any algorithm supported by the Platform and the Tool MAY be used.

default_max_age

OPTIONAL. Default Maximum Authentication Age. Specifies that the End-User MUST be actively authenticated if the End-User was authenticated longer ago than the specified number of seconds. The max_age request parameter overrides this default value. If omitted, no default Maximum Authentication Age is specified.

require_auth_time

OPTIONAL. Boolean value specifying whether the auth_time Claim in the ID Token is REQUIRED. It is REQUIRED when the value is true. If this is false, the auth_time Claim can still be dynamically requested as an individual Claim for the ID Token using the claims request parameter described in Section 5.5.1 of OpenID Connect Core 1.0 [OPENID-CCORE]. If omitted, the default value is false.

default_acr_values

OPTIONAL. Default requested Authentication Context Class Reference values. Array of strings that specifies the default acr values that the Platform is being requested to use for processing requests from this Tool, with the values appearing in order of preference. The Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value in the issued ID Token. The acr Claim is requested as a Voluntary Claim by this parameter. The acr_values_supported discovery element contains a list of the supported acr values supported by this server. Values specified in the acr_values request parameter or an individual acr Claim request override these default values.

initiate_login_uri

OPTIONAL. URI using the https scheme that a third party can use to initiate a login by the Tool, as specified in Section 4 of OpenID Connect Core 1.0 [OPENID-CCORE]. The URI MUST accept requests via both GET and POST. The Tool MUST understand the login_hint and iss parameters and SHOULD support the target_link_uri parameter.

request_uris

OPTIONAL ARRAY. The request_uri values that are pre-registered by the Tool for use at the Platform. Servers MAY cache the contents of the files referenced by these URIs and not retrieve them at the time they are used in a request. Platforms can require that request_uri values used be pre-registered with the require_request_uri_registration discovery parameter.

An HTTP POST message MUST be sent to the Client Registration Endpoint with the desired Tool configuration. The content type must be application/json. If provided by the platform, the tool must include the token as Bearer Token in the Authentication http header. A non-normative example is given below:

						
POST /connect/register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: server.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJ .

{
    "application_type": "web",
    "response_types": ["id_token"],
    "grant_types": ["implicit", "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",
    "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-nrps/scope/contextmembership.readonly"
}							
						

							
{
    "client_id": "709sdfnjkds12",
    "registration_client_uri":
      "https://server.example.com/connect/register?client_id=709sdfnjkds12",
    "application_type": "web",
    "response_types": ["id_token"],
    "grant_types": ["implicit", "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",
    "jwks_uri": "https://client.example.org/.well-known/jwks.json",
    "logo_uri": "https://client.example.org/logo.png",
    "token_endpoint_auth_method": "private_key_jwt",
    "contacts": ["ve7jtb@example.org", "mary@example.org"],
    "scope": "https://purl.imsglobal.org/spec/lti-ags/scope/score"
}
							

5.5.5 Registration Completed and Activation (Step 4)

Once the registration is completed, successfully or not, the Tool should notify the Platform by sending an HTML5 Web Message [WebMessaging] indicating the window may be closed. Depending on whether the platform opened the registration in an IFrame or a new tab, either window.parent or window.opener should be called.

Refer to the relevant 1EdTech specification for the details of the corresponding messaging.

5.5.6 Client Registration Management

There will be some scenarios in which the Client registration information may need to be read, and/or changed and/or deleted. When using OpenID Connect, management of client registration information is covered in [OPENID-DCR]. Support for Client Registration Management is OPTIONAL. If a binding of an 1EdTech service specification wishes to make Client Registration Management available, the following MUST be completed:

• The functionality MUST comply with the [OPENID-DCR] and the subset of features to be used MUST be clearly identified. For example only some of read, update and delete capabilities may be available
• The conformance requirements, in the corresponding Conformance & Certification document, MUST state whether support for Client Registration Management is OPTIONAL or REQUIRED. Support of the features available in [OPENID-DCR] MUST be identified as either OPTIONAL or REQUIRED
• Access to the Client Registration Management endpoints MUST be secured as per [RFC6750] (this makes use of the original registration access token)
• The client registration management information exchange MUST be secured at the transport-layer using either TLS 1.2 or TLS 1.3.

7.1.1 Expires_In Values and Renewing the Access Token

The recommended value of the 'expires_in' attribute is 3600 i.e. one hour. This means that the validity of the access token expires one hour after the time it was issued. Client-credentials based OAuth 2 does NOT permit the use of access token refreshing. Therefore, once an access token has expired, a new access token MUST be requested. The same set of credentials MAY be reused when requesting a new access token. However, these credentials MAY also expire: if they expire then a request for an access token using these credentials MUST be refused. The use of expiry times for credentials is implementation dependent.

Token Refresh is permitted with Authorization Code Grant. An Authorization Server is NOT REQUIRED to support token refresh.

7.1.2 Authorization Code Details

The Authorization Code MUST be used only once. A lifetime for the authorization code of 600 seconds (10 minutes) is RECOMMENDED. If an authorization code is used more than once, the authorization server MUST deny the request and SHOULD revoke (when possible) all tokens previously issued based on that authorization code. The authorization code is bound to the client identifier and redirection URI

7.1.3 Scope Naming Conventions

When requesting an access token it is a requirement, for access to an 1EdTech-compliant service, to identify the set of scopes for the access request. The set of scopes that are available as part of an 1EdTech service are defined in the corresponding specification document. In this document is the naming convention that SHOULD be adopted for those scopes. This naming convention is based upon a broader set of guidelines created by 1EdTech for all of its generated artifacts. The format for a scope is:

						
https://purl.imsglobal.org/spec/[shortname]/[version]/scope/[scopeleaf].[action]
        				

where:

[shortname] The abbreviated name of the service specification e.g. or for OneRoster, lti for LTI, etc.

[version] The version of the service specification e.g. v1p0, v2p1, etc.

[scopeleaf] An appropriate term for the collection of endpoints being covered by the scope.

[action] A term that reflects that nature of the scope. The suggested values are:

• readonly for a set of endpoints that permit read only using the GET verb

• createput for a set of endpoints that permit creation using the PUT verb

• createpost for a set of endpoints that permit creation using the POST verb

• update for a set of endpoints that permit changing of an established resource

• replace for a set of endpoints that permit overwriting of an established resource

• delete for a set of endpoints that permit delete only

• all for access to all of endpoints supported for the version of the identified specification

An example of some scopes that have already been defined by 1EdTech are:

https://purl.imsglobal.org/spec/or/v1p2/scope/gradebook.delete          
        			

which is used in OneRoster 1.2 to permit access to the endpoints that allow a gradebook resource to be deleted, and:

https://purl.imsglobal.org/spec/rs/v1p0/scope/resource.readonly          
        			

which is used in LTI Resource Search 1.0 to permit access to the endpoints that allow access to the information about a set of resources.

7.1.4 Managing Scopes

1EdTech REQUIRES the use of scopes when obtaining an access token. The definition of the set of scopes for a service is contained within the corresponding 1EdTech specification. Therefore, an authorization server MUST be made aware of these scopes. Either the credentials or the JWT claim set supplied when requesting the access token must be used to determine if the requesting client is permitted to request access depending on those scopes. Scope definitions are immutable and permanent.

The way in which an authorization server obtains the information about the set of permitted scopes for a service is implementation dependent. An authorization server MUST support validation of scopes with respect to access token provision. A scope MUST NOT be allocated if it is not contained within the request for the access token.

The set of scopes to be used in a service are defined within the 1EdTech service specification. The specification MAY also permit the definition and use of proprietary scopes i.e. to extend the set scopes defined in the 1EdTech specification.

7.4.1 Prohibiting the Login CSRF Vulnerability

For Platform initiated message exchanges the combination of the full six steps of the 'Implicit Flow' with the 'Initiating Login from a Third Party' mechanisms of the [OPENID-CCORE] prevents vulnerability to Login CSRF attacks. This vulnerability does NOT occur in Tool initiated exchanges because the user is already logged into the platform. The Platform must verify that the data claim returned in the Tool initiated message was generated by the current user’s session in a corresponding Tool launch.

7.4.2 Symmetric vs. Asymmetric Keys with JWT

The primary difference between the use of Symmetric and Asymmetric keys is that the same key is used in both end-systems when using Symmetric keys. When using Asymmetric keys the end-systems have their own public and private key pairs. 1EdTech RECOMMENDS the use of Asymmetric keys. If symmetric keys are used then the associated 1EdTech service specification MUST explain and justify why that approach has been adopted. Asymmetric key usage should reduce a system's vulnerability but the overall vulnerability of a system is based upon the combination of many issues.

7.5.1 Handling Clock Drift

Clock drift refers to several related phenomena where a clock does not run at exactly the same rate as a reference clock (see Wikipedia). Therefore, after some time the clock "drifts apart" or gradually desynchronizes from the other clock. All clocks are subject to drift, causing eventual divergence unless resynchronized.

Accurate clock alignment is important whenever absolute time-based data exchanges are used. It is recommended that a margin of error of less than or equal to 300s is used to compensate for clock drift. In many cases this margin should be much smaller e.g. less than 5% of the maximum time period being used.