Versatile, Synchronous and Asynchronous, JSON Web Token (JWT) Assertion Profile for OAuth 2.0 Authorization Grants

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.

These steps are illustrated in the following diagram: +--------+ +--------+ | |----(1) Access Token Request--------------->| | | | | | | | +------------------------------------| | | Client | | (2) Obtaining the grant's approval | OP | | | +----------------------------------->| | | | | | | |<----(3) 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 flow, the Client gets the Access Token in the initial response.

+--------+ +--------+ | |----(1) Access Token Request--------------->| | | | | | | | +------------------------------------| | | Client | | (2) Obtaining the grant's approval | OP | | | +----------------------------------->| | | | | | | |<----(3) Successful Response----------------| | +--------+ +--------+

In this flow, the Client regularly calls the Token Endpoint.

+--------+ +--------+ | |----(1a) Access Token Request-------------->| | | | | | | |<----(1b) Pending Response------------------| | | | | | | | +------------------------------------| | | Client | | (2) Obtaining the grant's approval | OP | | | +----------------------------------->| | | | | | | |----(3a) Polling Request------------------->| | | | | | | |<----(3b) Successful Polling Response-------| | +--------+ +--------+

In this flow, the Client is notified on the Client Notification Endpoint.

+--------+ +--------+ | |----(1a) Access Token Request-------------->| | | | | | | |<----(1b) Pending Response------------------| | | | | | | | +------------------------------------| | | Client | | (2) Obtaining the grant's approval | OP | | | +----------------------------------->| | | | | | | |<----(3a) Notification of Success-----------| | | | | | | |----(3b) Acknowledgement------------------->| | +--------+ +--------+

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 MUST obtain the result by using the Asynchrounous Poll mode (). Both mechanisms are mutual exclusive, i.e. a given client_id can only use one of these mechanisms.

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: MANDATORY. In order to enable an asynchronous mode, the grant_type value MUST be set to urn:ietf:params:oauth:grant-type:jwt-bearer:versatile. 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 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.

The following is a non-normative example of an initial Access Token Request. POST /token.oauth2 HTTP/1.1 Host: example.as.com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type %3Ajwt-bearer%3Aversatile &assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9. ZhwP[...omitted for brevity...]. paC4[...omitted for brevity...] &scope=scope_a%20scope_b &client_notification_token=vO4n2DAeRrcWE0VAlo4I

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 .

The following is a non-normative example of a Successful Response. HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "access_token": "SlAV32hkKG", "token_type": "Bearer", "refresh_token": "8xLOxBtZp8", "expires_in": 3600 }

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 attribute contains the transaction_id value. The transaction_id value is used to identify the transaction in the asynchronous modes defined in and . The transaction_id value is a case sensitive string OPTIONAL. The expires_in attribute contains the expires_in value. The expires_in value is lifetime in seconds of the transaction_id. The expires_in value is an integer. OPTIONAL. The interval attribute contains the interval value. 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.

The following is a non-normative example of a Pending Response. HTTP/1.1 202 Accepted Content-Type: application/json { "transaction_id": "b0f9f8022e344f9984dcc7d3d4d4", "expires_in": 1800, "interval": 5 }

If the Access Token Request can not be processed, the token endpoint responds with an error, as defined in Section 5.2 of .

The following is a non-normative example of an Error Response. HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store { "error":"invalid_grant", "error_description":"Audience validation failed" }

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.

The following is a non-normative example of an Polling Request. POST /token.oauth2 HTTP/1.1 Host: example.as.com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer %3Aversatile%3Apolling &transaction_id=b0f9f8022e344f9984dcc7d3d4d4

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 .

The following is a non-normative example of a Successful Polling Response. HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "access_token": "SlAV32hkKG", "token_type": "Bearer", "refresh_token": "8xLOxBtZp8", "expires_in": 3600 }

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 is configured with a client_notification_endpoint. 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 ().

The following is a non-normative example of an Error Polling Response. HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store { "error":"invalid_transaction_id", "error_description":"The transaction_id is not valid." }

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. MANDATORY. The transaction_id links the Notification with a Pending Response ().

The following is a non-normative example of a Notification of Success. POST /notification HTTP/1.1 Host: example.client.com Authorization: Bearer vO4n2DAeRrcWE0VAlo4I Content-Type: application/json { "transaction_id": "b0f9f8022e344f9984dcc7d3d4d4", "access_token": "SlAV32hkKG", "token_type": "Bearer", "refresh_token": "8xLOxBtZp8", "expires_in": 3600 }

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. MANDATORY. The transaction_id links the Notification with a Pending Response ().

The following is a non-normative example of a Notification of Error. POST /notification HTTP/1.1 Host: example.client.com Authorization: Bearer vO4n2DAeRrcWE0VAlo4I Content-Type: application/json { "transaction_id": "b0f9f8022e344f9984dcc7d3d4d4", "error":"invalid_grant", "error_description":"Audience validation failed" }

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.

The following is a non-normative example of an Acknowledgement. HTTP/1.1 200 OK

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 section registers the value grant-type:jwt-bearer:versatile in the IANA "OAuth URI" registry established by "An IETF URN Sub-Namespace for OAuth" . URN: urn:ietf:params:oauth:grant-type:jwt-bearer:versatile Common Name: Versatile JWT Bearer Token Grant Type Profile for OAuth 2.0 Change Controller: IESG Specification Document: of this specification

This section registers the value grant-type:jwt-bearer:versatile:polling in the IANA "OAuth URI" registry established by "An IETF URN Sub-Namespace for OAuth" . URN: urn:ietf:params:oauth:grant-type:jwt-bearer:versatile:polling Common Name: Polling for Versatile JWT Bearer Token Profile for OAuth 2.0 Change Controller: IESG Specification Document: of this specification