Versatile, Synchronous and Asynchronous, JSON Web Token (JWT) Assertion Profile for OAuth 2.0 Authorization GrantsOrangenicolas.aillery@orange.comOrangecharles.marais@orange.com
Security
OpenID MODRNA Working GroupOAuthJWTAssertionTokenSecurity TokenThis specification defines the use of a JSON Web Token (JWT) Bearer Token as a mean for
requesting an OAuth 2.0 access token in a versatile way, synchronous and asynchronous. This specification is a profile of and an extension to .
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 .
Unless otherwise noted, all the protocol parameter names and values are case sensitive.
All terms are as defined in the following specifications:
"The OAuth 2.0 Authorization Framework" ,
the OAuth Assertion Framework
, , and "JSON Web Token (JWT)" .
The versatile JWT profile enables a Client to get an Access Token on the token endpoint.
The versatile JWT profile is a profile to that extends the synchronous JWT profile, defined in .
The versatile JWT profile enables the OP to respond either in a synchronous or asyncronous way, depending on the grant approval process.
The versatile JWT profile, in abstract, follows the following steps.The Client sends a Access Token Request to the OpenID Provider (OP).The OP approves the grant (potentially involving the Resource Owner in an out of band mode).The OP responds to the Client with an Access Token.
In order to obtain the grant's approval, the OP may reuse a previously approved grant. It may also have some interactions with other parties.
This specification does not define the way a grant is approved.
In order to retrieve the Access Token, three flows are possible:
The Client gets the Access Token in the initial response.
Refer to for more details.
The Client regularly calls the Token Endpoint.
Refer to for more details.
The Client is notified on the Client Notification Endpoint.
Refer to for more details.
In this specification, the Client requests an asynchronous flow, but both asynchronous flows can become a synchronous flow if no asynchronism is necessary.
In this flow, the Client gets the Access Token in the initial response.
In this flow, the Client regularly calls the Token Endpoint.
In this flow, the Client is notified on the Client Notification Endpoint.
If the Client wants to use the Asynchrounous Push mode (), it MUST register its client_notification_endpoint.
The client_notification_endpoint is a callback URL on the Client.
If the client does not use the Asynchrounous Push mode, it can obtain the result by using the Asynchrounous Poll mode ().
Both mechanisms are not mutual exclusive, i.e. a given client_id can use both mechanisms, but not in the same transaction.
When the Client requires an Asynchronous Poll mode, the following flow can be synchronous or asynchronous.
If the flow is synchronous, the Client gets the Access Token in the initial response, as illustrated in .
If the flow is asynchronous, the Client has to regularly call the Token Endpoint, as illustrated in .
The initial Access Token Request to the token endpoint is defined in Section 2.1 of .
This specification proposes a specific grant_type for the Asynchronous Poll mode:
MANDATORY.
In order to enable the Asynchronous Poll mode, the grant_type value MUST be set to: urn:ietf:params:oauth:grant-type:jwt-bearer:versatile:poll_mode.
Using the grant_type urn:ietf:params:oauth:grant-type:jwt-bearer:versatile:poll_mode means that, in case of asynchronous response, the Client will use the Asynchronous Poll mode, defined in .
Authentication of the Client is optional, as described in Section 3.2.1 of OAuth 2.0 .
If the Client authenticated for the Initial Access Token Request defined in , it MUST authenticate for the Polling Request.
If the grant is approved, the token endpoint responds with a success response defined in ;
if the grant has not been approved yet, the token endpoint responds with a pending response defined in ;
otherwise it responds with an error, as defined in .
If the grant has been approved, the token endpoint responds with a success response defined in Section 5.1 of .
If the grant has not been aproved yet, the token endpoint responds with a HTTP 202 Accepted response.
The response body contains JSON structure, with the following attributes.
MANDATORY.
The transaction_id value is used to identify the transaction in the Polling Request, defined in .
The transaction_id SHOULD be a random value with a level of entropy high enough to prevent guessing and replay by a Client.
The transaction_id value is a case sensitive string.
OPTIONAL.
The expires_in value is lifetime in seconds of the transaction_id.
The expires_in value is an integer.
OPTIONAL.
The interval value is the minimum amount of time in seconds that the client SHOULD wait between polling requests to the token endpoint.
The interval value is an integer.
If the Access Token Request can not be processed, the token endpoint responds with an error, as defined in Section 5.2 of .
In order to detect that a pending grant has been approved, the Client can poll the token endpoint.
If the grant has been approved, the token endpoint reponds in the response.
Else, the token endpoint responds with HTTP 400 Bad Request.
A Client configured with a client_notification_endpoint MUST NOT send a Polling Request.
The Polling Request to the token endpoint is defined in Section 2.1 of .
This specification proposes a specific grant_type, an additional parameter transaction_id and the limitation to those two attributes:
MANDATORY. In order to indicate a Polling Request, the grant_type value MUST be set to urn:ietf:params:oauth:grant-type:jwt-bearer:versatile:polling.
MANDATORY.
The transaction_id value contains the transaction_id received from the Pending Response ().
The transaction_id value is a case sensitive string.
The parameters grant_type and transaction_id are the only attributes that the token endpoint SHOULD consider in a Polling Request.
Authentication of the Client is optional, as described in Section 3.2.1 of OAuth 2.0 .
If the grant has been approved, the token endpoint responds with a Successful Polling Response, defined in .
Else, the token endpoint responds with an Error Polling Response defined in .
If the grant has been approved, the token endpoint responds with a success response defined in Section 5.1 of .
If the grant has not been approved yet or if the Polling Request can not be processed, the token endpoint responds with an error, as defined in Section 5.2 of ,
with the following additional error codes, specific for the versatile JWT profile:
The Access Token Request is still pending as the authorization has not been gained yet.
The client should repeat the Access Token Request to the token endpoint.
The client is polling too quickly and should back off at a reasonable rate.
The transaction_id has expired. The client will need to make a new Access Token Request ().
The Client sent a polling request for a transaction_id that does not exist or is not valid for the requesting Client.
The Client sent a Polling Request whereas it set the grant_type to urn:ietf:params:oauth:grant-type:jwt-bearer:versatile:push_mode in the Access Token Request.
The error codes authorization_pending and slow_down are
considered soft errors. The client should continue to poll the token
endpoint by repeating the Polling Request () when
receiving soft errors, increasing the time between polls if a
slow_down error is received. Other error codes are considered hard
errors; the client should stop polling and react accordingly.
The interval at which the client polls MUST NOT be more frequent than
the interval parameter returned in the Pending Response ().
When the Client requires an Asynchronous Push mode, the following flow can be synchronous or asynchronous.
If the flow is synchronous, the Client gets the Access Token in the initial response, as illustrated in .
If the flow is asynchronous, The Client will be notified on the Client Notification Endpoint., as illustrated in .
The initial Access Token Request to the token endpoint is defined in Section 2.1 of .
This specification proposes a specific grant_type and an additional parameter client_notification_token for the Asynchronous Push mode:
MANDATORY.
In order to enable the Asynchronous Push mode, the grant_type value MUST be set to: urn:ietf:params:oauth:grant-type:jwt-bearer:versatile:push_mode.
Using the grant_type urn:ietf:params:oauth:grant-type:jwt-bearer:versatile:push_mode means that, in case of asynchronous response, the Client will use the Asynchronous Push mode, defined in .
MANDATORY if the Client uses the Asynchronous Push mode described in . MUST NOT be used otherwise.
The client_notification_token is an opaque token issued by the Client. The Client SHOULD NOT reuse a client_notification_token. The Client SHOULD use a random value with a level of entropy high enough to cover its security requirements.
The client_notification_token is a Bearer Token used by the Client to authorize the OP when the OP sends the Token Response to the Client Notification Endpoint.
The client_notification_token value is a case sensitive string.
Authentication of the Client is optional, as described in Section 3.2.1 of OAuth 2.0 .
If the grant is approved, the token endpoint responds with a success response defined in ;
if the grant has not been approved yet, the token endpoint responds with a pending response defined in ;
otherwise it responds with an error, as defined in .
If the grant has been approved, the token endpoint responds with a success response defined in Section 5.1 of .
If the grant has not been aproved yet, the token endpoint responds with a HTTP 202 Accepted response.
The response body contains JSON structure, with the following attributes.
MANDATORY.
The transaction_id value is used to identify the transaction in the Notifications, defined in .
The transaction_id SHOULD be a random value with a level of entropy high enough to prevent guessing.
The transaction_id value is a case sensitive string.
OPTIONAL.
The expires_in value is lifetime in seconds of the transaction_id.
The expires_in value is an integer.
If the Access Token Request can not be processed, the token endpoint responds with an error, as defined in Section 5.2 of ,
with the following additional error code, specific for the versatile JWT profile:
The Client set the grant_type to urn:ietf:params:oauth:grant-type:jwt-bearer:versatile:push_mode in the Access Token Request, but did not register a client_notification_endpoint.
If the Client registered a client_notification_endpoint, the OP MUST notify the Client when a pending grant has been approved or an error occured.
The Notification is sent to the Client using a HTTP POST on the Client Notification Endpoint.
Communication with the Client Notification Endpoint MUST utilize TLS.
A Client configured with a client_notification_endpoint MUST wait for a Notification on its client_notification_endpoint.
The OP sends the Notification of Success to the Client using HTTP POST.
The HTTP POST request MUST contain the following header:
MANDATORY.
The Authorization value contains the client_notification_token specified in the Access Token Request and used as a Bearer Token.
The Authorization value is a case sensitive string.
A Notification of Success contains a JSON object, as defined in Section 5.1 of , with the additional attribute transaction_id.
A Notification is a Notification of Error if the JSON object contains an error attribute. Otherwise, it's a Notification of Success.
MANDATORY.
The transaction_id links the Notification with a Pending Response ().
The OP sends the Notification of Error to the Client using HTTP POST.
The HTTP POST request MUST contain the following header:
MANDATORY.
The Authorization value contains the client_notification_token specified in the Access Token Request and used as a Bearer Token.
The Authorization value is a case sensitive string.
A Notification of Error contains a JSON object, as defined in Section 5.2 of , with the additional attribute transaction_id.
A Notification is a Notification of Error if the JSON object contains an error attribute. Otherwise, it's a Notification of Success.
MANDATORY.
The transaction_id links the Notification with a Pending Response ().
The Authorization value is a client_notification_token.
This client_notification_token enables to retrieve the transaction_id received in the Pending Response ().
The transaction_id in the Notification MUST match with the transaction_id received in the Pending Response ().
The acknowledgement MUST be a HTTP 200 OK. This HTTP response SHOULD be ignored by the OP.
For Interoperability Considerations, please refer to:
Section 7 of Section 5 of For Security Considerations, please refer to:
Section 10 of Section 8 of Section 6 of Section 11 of For Privacy Considerations, please refer to:
Section 7 of Section 12 of
This specification registers the following values in the IANA "OAuth Parameters" registry established by .
Parameter name: client_notification_tokenParameter usage location: Access Token RequestChange Controller: IESGSpecification Document: of this specificationParameter name: transaction_idParameter usage location: Polling RequestChange Controller: IESGSpecification Document: of this specification
This specification registers the following values in the IANA "OAuth URI" registry established by .
URN: urn:ietf:params:oauth:grant-type:jwt-bearer:versatile:push_modeCommon Name: Push mode of the Versatile JWT Bearer Token Grant Type Profile for OAuth 2.0Change Controller: IESGSpecification Document: of this specificationURN: urn:ietf:params:oauth:grant-type:jwt-bearer:versatile:poll_modeCommon Name: Poll mode of the Versatile JWT Bearer Token Grant Type Profile for OAuth 2.0Change Controller: IESGSpecification Document: of this specificationURN: urn:ietf:params:oauth:grant-type:jwt-bearer:versatile:pollingCommon Name: Polling for Versatile JWT Bearer Token Profile for OAuth 2.0Change Controller: IESGSpecification Document: of this specification
This specification registers the following values in the IANA "OAuth Extensions Error Registry" registry established by .
Error name: invalid_transaction_idError usage location: Error Polling ResponseRelated protocol extension: this specificationChange controller: IETFSpecification Document: of this specificationError name: forbidden_pollingError usage location: Error Polling ResponseRelated protocol extension: this specificationChange controller: IETFSpecification Document: of this specificationError name: forbidden_modeError usage location: Error ResponseRelated protocol extension: this specificationChange controller: IETFSpecification Document: of this specificationAssertion Framework for OAuth 2.0 Client Authentication and Authorization GrantsPing IdentitySalesforce.comMicrosoftMicrosoftJSON Web Token (JWT)Microsoftmbj@microsoft.comhttp://self-issued.info/Ping Identityve7jtb@ve7jtb.comNomura Research Instituten-sakimura@nri.co.jpOAuth ParametersIANA