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 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.

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:poll_mode or urn:ietf:params:oauth:grant-type:jwt-bearer:versatile:push_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 . 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 Client authenticated for the Initial Access Token Request defined in , it MUST authenticate for the Polling Request.

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%3Apush_mode &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 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 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 , 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.

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. Authentication of the Client is optional, as described in Section 3.2.1 of OAuth 2.0 .

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 set the grant_type to urn:ietf:params:oauth:grant-type:jwt-bearer:versatile:push 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 ().

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. 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 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. 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 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 specification registers the following values in the IANA "OAuth Parameters" registry established by .

Parameter name: client_notification_token Parameter usage location: Access Token Request Change Controller: IESG Specification Document: of this specification Parameter name: transaction_id Parameter usage location: Polling Request Change Controller: IESG Specification 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_mode Common Name: Push mode of the Versatile JWT Bearer Token Grant Type Profile for OAuth 2.0 Change Controller: IESG Specification Document: of this specification URN: urn:ietf:params:oauth:grant-type:jwt-bearer:versatile:poll_mode Common Name: Poll mode of the Versatile JWT Bearer Token Grant Type Profile for OAuth 2.0 Change Controller: IESG Specification Document: of this specification 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

This specification registers the following values in the IANA "OAuth Extensions Error Registry" registry established by .

Error name: authorization_pending Error usage location: Error Polling Response Related protocol extension: draft-ietf-oauth-device-flow-05 Change controller: IETF Specification Document: Section 3.5 of draft-ietf-oauth-device-flow-05 Error name: slow_down Error usage location: Error Polling Response Related protocol extension: draft-ietf-oauth-device-flow-05 Change controller: IETF Specification Document: Section 3.5 of draft-ietf-oauth-device-flow-05 Error name: expired_token Error usage location: Error Polling Response Related protocol extension: draft-ietf-oauth-device-flow-05 Change controller: IETF Specification Document: Section 3.5 of draft-ietf-oauth-device-flow-05 Error name: invalid_transaction_id Error usage location: Error Polling Response Related protocol extension: this specification Change controller: IETF Specification Document: of this specification Error name: forbidden_polling Error usage location: Error Polling Response Related protocol extension: this specification Change controller: IETF Specification Document: of this specification Error name: forbidden_mode Error usage location: Error Response Related protocol extension: this specification Change controller: IETF Specification Document: of this specification