| OAuth Working Group | M. Jones |
| Internet-Draft | Microsoft |
| Intended status: Standards Track | J. Bradley |
| Expires: September 14, 2017 | B. Campbell |
| Ping Identity | |
| W. Denniss | |
| March 13, 2017 |
OAuth 2.0 Token Binding
draft-ietf-oauth-token-binding-02
This specification enables OAuth 2.0 implementations to apply Token Binding to Access Tokens, Authorization Codes, and Refresh Tokens. This cryptographically binds these tokens to a client's Token Binding key pair, possession of which is proven on the TLS connections over which the tokens are intended to be used. This use of Token Binding protects these tokens from man-in-the-middle and token export and replay attacks.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 14, 2017.
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
This specification enables OAuth 2.0 [RFC6749] implementations to apply Token Binding (TLS Extension for Token Binding Protocol Negotiation [I-D.ietf-tokbind-negotiation], The Token Binding Protocol Version 1.0 [I-D.ietf-tokbind-protocol] and Token Binding over HTTP [I-D.ietf-tokbind-https]) to Access Tokens, Authorization Codes, and Refresh Tokens. This cryptographically binds these tokens to a client's Token Binding key pair, possession of which is proven on the TLS connections over which the tokens are intended to be used. This use of Token Binding protects these tokens from man-in-the-middle and token export and replay attacks.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].
This specification uses the terms "Access Token", "Authorization Code", "Authorization Endpoint", "Authorization Server", "Client", "Protected Resource", "Refresh Token", and "Token Endpoint" defined by OAuth 2.0 [RFC6749], the terms "Claim" and "JSON Web Token (JWT)" defined by JSON Web Token (JWT) [JWT], the term "User Agent" defined by RFC 7230 [RFC7230], and the terms "Provided", "Referred", "Token Binding" and "Token Binding ID" defined by Token Binding over HTTP [I-D.ietf-tokbind-https].
Token Binding of refresh tokens is a straightforward first-party scenario, applying term "first-party" as used in Token Binding over HTTP [I-D.ietf-tokbind-https]. It cryptographically binds the refresh token to the client's Token Binding key pair, possession of which is proven on the TLS connections between the client and the token endpoint. This case is straightforward because the refresh token is both retrieved by the client from the token endpoint and sent by the client to the token endpoint. Unlike the federated scenarios described in Section 4 (Federation Use Cases) of Token Binding over HTTP [I-D.ietf-tokbind-https] and the access token case described in the next section, only a single TLS connection is involved in the refresh token case.
Token Binding a refresh token requires that the authorization server do two things. First, when refresh token is sent to the client, the authorization server needs to remember the Provided Token Binding ID and remember its association with the issued refresh token. Second, when a token request containing a refresh token is received at the token endpoint, the authorization server needs to verify that the Provided Token Binding ID for the request matches the remembered Token Binding ID associated with the refresh token. If the Token Binding IDs do not match, the authorization server should return an error in response to the request.
How the authorization server remembers the association between the refresh token and the Token Binding ID is an implementation detail that beyond the scope of this specification. Some authorization servers will choose to store the Token Binding ID (or a cryptographic hash of it, such a SHA-256 hash [SHS]) in the refresh token itself, provided it is integrity-protected, thus reducing the amount of state to be kept by the server. Other authorization servers will add the Token Binding ID value (or a hash of it) to an internal data structure also containing other information about the refresh token, such as grant type information. These choices make no difference to the client, since the refresh token is opaque to it.
This section provides an example of what the interactions around a Token Bound refresh token might look like, along with some details of the involved processing. Token Binding of refresh tokens is most useful for native application clients so the example has protocol elements typical of a native client flow. Extra line breaks in all examples are for display purposes only.
A native application client makes the following access token request with an authorization code using a TLS connection where Token Binding has been negotiated. A PKCE code_verifier is included because use the of PKCE is considered best practice for native application clients [I-D.ietf-oauth-native-apps]. The base64url-encoded representation of the exported keying material (EKM) from that TLS connection is p6ZuSwfl6pIe8es5KyeV76T4swZmQp0_awd27jHfrbo, which is needed to validate the Token Binding Message.
POST /as/token.oauth2 HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded Sec-Token-Binding: AIkAAgBBQGto7hHRR0Y5nkOWqc9KNfwW95dEFmSI_tCZ_Cbl 7LWlt6Xjp3DbjiDJavGFiKP2HV_2JSE42VzmKOVVV8m7eqAAQOKiDK1Oi0z6v4X5B P7uc0pFestVZ42TTOdJmoHpji06Qq3jsCiCRSJx9ck2fWJYx8tLVXRZPATB3x6c24 aY0ZEAAA grant_type=authorization_code&code=4bwcZesc7Xacc330ltc66Wxk8EAfP9j2 &code_verifier=2x6_ylS390-8V7jaT9wj.8qP9nKmYCf.V-rD9O4r_1 &client_id=example-native-client-id
Figure 1: Initial Request with Code
A refresh token is issued in response to the prior request. Although it looks like a typical response to the client, the authorization server has bound the refresh token to the Provided Token Binding ID from the encoded Token Binding message in the Sec-Token-Binding header of the request. In this example, that binding is done by saving the Token Binding ID alongside other information about the refresh token in some server side persistent storage. The base64url-encoded representation of that Token Binding ID is AgBBQGto7hHRR0Y5nkOWqc9KNfwW95dEFmSI_tCZ_Cbl7LWlt6Xjp3DbjiDJavGFiKP2HV_2JSE42VzmKOVVV8m7eqA.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store
{
"access_token":"EdRs7qMrLb167Z9fV2dcwoLTC",
"refresh_token":"ACClZEIQTjW9arT9GOJGGd7QNwqOMmUYfsJTiv8his4",
"token_type":"Bearer",
"expires_in":3600
}
Figure 2: Successful Response
When the access token expires, the client requests a new one with a refresh request to the token endpoint. In this example, the request is made on a new TLS connection so the EKM (base64url-encoded: va-84Ukw4Zqfd7uWOtFrAJda96WwgbdaPDX2knoOiAE) and signature in the Token Binding Message are different than in the initial request.
POST /as/token.oauth2 HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded Sec-Token-Binding: AIkAAgBBQGto7hHRR0Y5nkOWqc9KNfwW95dEFmSI_tCZ_Cbl 7LWlt6Xjp3DbjiDJavGFiKP2HV_2JSE42VzmKOVVV8m7eqAAQCpGbaG_YRf27qOra L0UT4fsKKjL6PukuOT00qzamoAXxOq7m_id7O3mLpnb_sM7kwSxLi7iNHzzDgCAkP t3lHwAAA refresh_token=ACClZEIQTjW9arT9GOJGGd7QNwqOMmUYfsJTiv8his4 &grant_type=refresh_token&client_id=example-native-client-id
Figure 3: Refresh Request
However, because the Token Binding ID is long-lived and may span multiple TLS sessions and connections, it is the same as in the initial request. That Token Binding ID is what the refresh token is bound to, so the authorization server is able to verify it and issue a new access token.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store
{
"access_token":"bwcESCwC4yOCQ8iPsgcn117k7",
"token_type":"Bearer",
"expires_in":3600
}
Figure 4: Successful Response
Token Binding for access tokens cryptographically binds the access token to the client's Token Binding key pair, possession of which is proven on the TLS connections between the client and the protected resource. Token Binding is applied to access tokens in a similar manner to that described in Section 4 (Federation Use Cases) of Token Binding over HTTP [I-D.ietf-tokbind-https]. It also builds upon the mechanisms for Token Binding of ID Tokens defined in OpenID Connect Token Bound Authentication 1.0 [OpenID.TokenBinding].
In the OpenID Connect [OpenID.Core] use case, HTTP redirects are used to pass information between the identity provider and the relying party; this HTTP redirect makes the Token Binding ID of the relying party available to the identity provider as the Referred Token Binding ID, information about which is then added to the ID Token. No such redirect occurs between the authorization server and the protected resource in the access token case; therefore, information about the Token Binding ID for the TLS connection between the client and the protected resource needs to be explicitly communicated by the client to the authorization server to achieve Token Binding of the access token.
This information is passed to the authorization server using the Referred Token Binding ID, just as in the ID Token case. The only difference is that the client needs to explicitly communicate the Token Binding ID of the TLS connection between the client and the protected resource to the Token Binding implementation so that it is sent as the Referred Token Binding ID in the request to the authorization server. This functionality provided by Token Binding implementations is described in Section 5 (Implementation Considerations) of Token Binding over HTTP [I-D.ietf-tokbind-https].
Note that to obtain this Token Binding ID, the client may need to establish a TLS connection between itself and the protected resource prior to making the request to the authorization server so that the Provided Token Binding ID for the TLS connection to the protected resource can be obtained. How the client retrieves this Token Binding ID from the underlying Token Binding API is implementation and operating system specific. An alternative, if supported, is for the client to generate a Token Binding key to use for the protected resource, use the Token Binding ID for that key, and then later use that key when the TLS connection to the protected resource is established.
For access tokens returned directly from the authorization endpoint, such as with the implicit grant defined in Section 4.2 of OAuth 2.0 [RFC6749], the Token Binding ID of the client's TLS channel to the protected resource is sent with the authorization request as the Referred Token Binding ID in the Sec-Token-Binding header, and is used to Token Bind the access token.
Upon receiving the Referred Token Binding ID in an authorization request, the authorization server associates (Token Binds) the ID with the access token in a way that can be accessed by the protected resource. Such methods include embedding the Referred Token Binding ID (or a cryptographic hash of it) in the issued access token itself, possibly using the syntax described at Section 3.4, or through token introspection [RFC7662]. The method for associating the referred token binding ID with the access token is determined by the authorization server and the protected resource, and is beyond the scope for this specification.
This section provides an example of what the interactions around a Token Bound access token issued from the authorization endpoint might look like, along with some details of the involved processing. Extra line breaks in all examples are for display purposes only.
The client directs the user-agent to make the following HTTP request to the authorization endpoint. It is a typical authorization request that, because Token Binding was negotiated on the underlying TLS connection and the user-agent was signaled to reveal the Referred Token Binding, also includes the Sec-Token-Binding header with a Token Binding Message that contains both a Provided and Referred Token Binding. The base64url-encoded EKM from the TLS connection over which the request was made is jI5UAyjs5XCPISUGQIwgcSrOiVIWq4fhLVIFTQ4nLxc.
GET /as/authorization.oauth2?response_type=token &client_id=example-client-id&state=rM8pZxG1c3gKy6rEbsD8s &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb HTTP/1.1 Host: server.example.com Sec-Token-Binding: ARIAAgBBQIEE8mSMtDy2dj9EEBdXaQT9W3Rq1NS-jW8ebPoF 6FyL0jIfATVE55zlircgOTZmEg1xeIrC3DsGegwjs4bhw14AQGKDlAXFFMyQkZegC wlbTlqX3F9HTt-lJxFU_pi16ezka7qVRCpSF0BQLfSqlsxMbYfSSCJX1BDtrIL7PX j__fUAAAECAEFA1BNUnP3te5WrwlEwiejEz0OpesmC5PElWc7kZ5nlLSqQTj1ciIp 5vQ30LLUCyM_a2BYTUPKtd5EdS-PalT4t6ABADgeizRa5NkTMuX4zOdC-R4cLNWVV O8lLu2Psko-UJLR_XAH4Q0H7-m0_nQR1zBN78nYMKPvHsz8L3zWKRVyXEgAA
Figure 5: Authorization Request
The authorization server issues an access token and delivers it to the client by redirecting the user-agent with the following HTTP response:
HTTP/1.1 302 Found Location: https://client.example.org/cb#state=rM8pZxG1c3gKy6rEbsD8s &expires_in=3600&token_type=Bearer &access_token=eyJhbGciOiJFUzI[...omitted for brevity...]8xy5W5sQ
Figure 6: Authorization Request
The access token is bound to the Referred Token Binding ID from the authorization request, which when represented as a JWT, as described in Section 3.4, contains the SHA-256 hash of the Token Binding ID as the value of the tbh (token binding hash) member of the cnf (confirmation) claim. The confirmation claim portion of the JWT Claims Set is shown in the following figure.
{
...other claims omitted for brevity...
"cnf":{
"tbh": "vowQESa_MgbGJwIXaFm_BTN2QDPwh8PhuBm-EtUAqxc"
}
}
Figure 7: Confirmation Claim
For access tokens returned from the token endpoint, the Token Binding ID of the client's TLS channel to the protected resource is sent as the Referred Token Binding ID in the Sec-Token-Binding header, and is used to Token Bind the access token. This applies to all the grant types from OAuth 2.0 [RFC6749] using the token endpoint, including, but not limited to the refresh and authorization code token requests, as well as some extension grants, such as JWT assertion authorization grants [RFC7523].
Upon receiving the Referred Token Binding ID in a token request, the authorization server associates (Token Binds) the ID with the access token in a way that can be accessed by the protected resource. Such methods include embedding the Referred Token Binding ID (or a cryptographic hash of it) in the issued access token itself, possibly using the syntax described at Section 3.4, or through token introspection [RFC7662]. The method for associating the referred token binding ID with the access token is determined by the authorization server and the protected resource, and is beyond the scope for this specification.
Note that if the request results in a new refresh token being generated, it can be Token bound using the Provided Token Binding ID, per Section 2.
This section provides an example of what the interactions around a Token Bound access token issued from the token endpoint might look like, along with some details of the involved processing. Extra line breaks in all examples are for display purposes only.
The client makes an access token request to the token endpoint and includes the Sec-Token-Binding header with a Token Binding Message that contains both Provided and Referred Token Binding IDs. The Provided Token Binding ID is used to validate the token binding of the refresh token in the request (and to Token Bind a new refresh token, if one is issued), and the Referred Token Binding ID is used to Token Bind the access token that is generated. The base64url-encoded EKM from the TLS connection over which the access token request was made is 4jTc5e1QpocqPTZ5l6jsb6pRP18IFKdwwPvasYjn1-E.
POST /as/token.oauth2 HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded Sec-Token-Binding: ARIAAgBBQJFXJir2w4gbJ7grBx9uTYWIrs9V50-PW4ZijegQ 0LUM-_bGnGT6DizxUK-m5n3dQUIkeH7ybn6wb1C5dGyV_IAAQDDFToFrHt41Zppq7 u_SEMF_E-KimAB-HewWl2MvZzAQ9QKoWiJCLFiCkjgtr1RrA2-jaJvoB8o51DTGXQ ydWYkAAAECAEFAuC1GlYU83rqTGHEau1oqvNwy0fDsdXzIyT_4x1FcldsMxjFkJac IBJFGuYcccvnCak_duFi3QKFENuwxql-H9ABAMcU7IjJOUA4IyE6YoEcfz9BMPQqw M5M6hw4RZNQd58fsTCCslQE_NmNCl9JXy4NkdkEZBxqvZGPr0y8QZ_bmAwAA refresh_token=gZR_ZI8EAhLgWR-gWxBimbgZRZi_8EAhLgWRgWxBimbf &grant_type=refresh_token&client_id=example-client-id
Figure 8: Access Token Request
The authorization server issues an access token bound to the Referred Token Binding ID and delivers it in a response the client.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store
{
"access_token":"eyJhbGciOiJFUzI1NiIsImtp[...omitted...]1cs29j5c3",
"token_type":"Bearer",
"expires_in":3600
}
Figure 9: Authorization Request
The access token is bound to the Referred Token Binding ID of the access token request, which when represented as a JWT, as described in Section 3.4, contains the SHA-256 hash of the Token Binding ID as the value of the tbh (token binding hash) member of the cnf (confirmation) claim. The confirmation claim portion of the JWT Claims Set of the access token is shown in the following figure.
{
...other claims omitted for brevity...
"cnf":{
"tbh": "7NRBu9iDdJlYCTOqyeYuLxXv0blEA-yTpmGIrAwKAws"
}
}
Figure 10: Confirmation Claim
Upon receiving a token bound access token, the protected resource validates the binding by comparing the Provided Token Binding ID to the Token Binding ID for the access token. Alternatively, cryptographic hashes of these Token Binding ID values can be compared. If the values do not match, the resource access attempt MUST be rejected with an error.
For example, a protected resource request using the access token from Section 3.2.1 would look something like the following. The base64url-encoded EKM from the TLS connection over which the request was made is 7LsNP3BT1aHHdXdk6meEWjtSkiPVLb7YS6iHp-JXmuE. The protected resource validates the binding by comparing the Provided Token Binding ID from the Sec-Token-Binding header to the token binding hash confirmation of the access token. Extra line breaks in the example are for display purposes only.
GET /api/stuff HTTP/1.1 Host: resource.example.org Content-Type: application/x-www-form-urlencoded Sec-Token-Binding: AIkAAgBBQLgtRpWFPN66kxhxGrtaKrzcMtHw7HV8yMk_-MdR XJXbDMYxZCWnCASRRrmHHHL5wmpP3bhYt0ChRDbsMapfh_QAQN1He3Ftj4Wa_S_fz ZVns4saLfj6aBoMSQW6rLs19IIvHze7LrGjKyCfPTKXjajebxp-TLPFZCc0JTqTY5 _0MBAAAA
Figure 11: Protected Resource Request
If the access token is represented as a JWT, the token binding information SHOULD be represented in the same way that it is in token bound OpenID Connect ID Tokens [OpenID.TokenBinding]. That specification defines the new JWT Confirmation Method RFC 7800 [RFC7800] member tbh (token binding hash) to represent the SHA-256 hash of a Token Binding ID in an ID Token. The value of the tbh member is the base64url encoding of the SHA-256 hash of the Token Binding ID.
The following example demonstrates the JWT Claims Set of an access token containing the base64url encoding of the SHA-256 hash of a Token Binding ID as the value of the tbh (token binding hash) element in the cnf (confirmation) claim:
{
"iss": "https://server.example.com",
"aud": "https://resource.example.org",
"sub": "brian@example.com"
"iat": 1467324320,
"exp": 1467324920,
"cnf":{
"tbh": "7NRBu9iDdJlYCTOqyeYuLxXv0blEA-yTpmGIrAwKAws"
}
}
Figure 12: JWT with Token Binding Hash Confirmation Claim
There are two variations for Token Binding of an authorization code. One is appropriate for native application clients and the other for web server clients. The nature of where the various components reside for the different client types demands different methods of Token Binding the authorization code so that it is bound to a Token Binding key on the end user's device. This ensures that a lost or stolen authorization code cannot be successfully utilized from a different device. For native application clients, the code is bound to a Token Binding key pair that the native client itself possesses. For web server clients, the code is bound to a Token Binding key pair on the end user's browser. Both variations utilize the extensible framework of Proof Key for Code Exchange (PKCE) [RFC7636], which enables the client to show possession of a certain key when exchanging the authorization code for tokens. The following subsections individually describe each of the two PKCE methods respectively.
This section describes a PKCE method suitable for native application clients that cryptographically binds the authorization code to a Token Binding key pair on the client, which the client proves possession of on the TLS connection during the access token request containing the authorization code. The authorization code is bound to the Token Binding ID that the native application client uses to resolve the authorization code at the token endpoint. This binding ensures that the client that made the authorization request is the same client that is presenting the authorization code.
As defined in Proof Key for Code Exchange [RFC7636], the client sends the code challenge as part of the OAuth 2.0 authorization request with the two additional parameters: code_challenge and code_challenge_method.
For this Token Binding method of PKCE, TB-S256 is used as the value of the code_challenge_method parameter.
The value of the code_challenge parameter is the base64url encoding (per Section 5 of [RFC4648] with all trailing padding ('=') characters omitted and without the inclusion of any line breaks or whitespace) of the SHA-256 hash of the Provided Token Binding ID that the client will use when calling the authorization server's token endpoint. Note that, prior to making the authorization request, the client may need to establish a TLS connection between itself and the authorization server's token endpoint in order to establish the appropriate Token Binding ID.
When the authorization server issues the authorization code in the authorization response, it associates the code challenge and method values with the authorization code so they can be verified later when the authorization code is presented in the access token request.
For example, a native application client sends an authorization request by sending the user's browser to the authorization endpoint. The resulting HTTP request looks something like the following (with extra line breaks for display purposes only).
GET /as/authorization.oauth2?response_type=code &client_id=example-native-client-id&state=oUC2jyYtzRCrMyWrVnGj &code_challenge=rBlgOyMY4teiuJMDgOwkrpsAjPyI07D2WsEM-dnq6eE &code_challenge_method=TB-S256 HTTP/1.1 Host: server.example.com
Figure 13: Authorization Request
Upon receipt of the authorization code, the client sends the access token request to the token endpoint. The Token Binding Protocol [I-D.ietf-tokbind-protocol] is negotiated on the TLS connection between the client and the authorization server and the Sec-Token-Binding header, as defined in Token Binding over HTTP [I-D.ietf-tokbind-https], is included in the access token request. The authorization server extracts the Provided Token Binding ID from the header value, hashes it with SHA-256, and compares it to the code_challenge value previously associated with the authorization code. If the values match, the token endpoint continues processing as normal (as defined by OAuth 2.0 [RFC6749]). If the values do not match, an error response indicating "invalid_grant" MUST be returned.
The Sec-Token-Binding header contains sufficient information for verification of the authorization code and its association to the original authorization request. However, PKCE [RFC7636] requires that a code_verifier parameter be sent with the access token request, so the static value provided_tb is used to meet that requirement and indicate that the Provided Token Binding ID is used for the verification.
An example access token request, correlating to the authorization request in the previous example, to the token endpoint over a TLS connection for which Token Binding has been negotiated would look like the following (with extra line breaks for display purposes only). The base64url-encoded EKM from the TLS connection over which the request was made is pNVKtPuQFvylNYn000QowWrQKoeMkeX9H32hVuU71Bs.
POST /as/token.oauth2 HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded Sec-Token-Binding: AIkAAgBBQEOO9GRFP-LM0hoWw6-2i318BsuuUum5AL8bt1sz lr1EFfp5DMXMNW3O8WjcIXr2DKJnI4xnuGsE6GywQd9RbD0AQJDb3xyo9PBxj8M6Y jLt-6OaxgDkyoBoTkyrnNbLc8tJQ0JtXomKzBbj5qPtHDduXc6xz_lzvNpxSPxi42 8m7wkAAA grant_type=authorization_code&code=mJAReTWKX7zI3oHUNd4o3PeNqNqxKGp6 &code_verifier=provided_tb&client_id=example-native-client-id
Figure 14: Authorization Request
This section describes a PKCE method suitable for web server clients, which cryptographically binds the authorization code to a Token Binding key pair on the browser. The authorization code is bound to the Token Binding ID that the browser uses to deliver the authorization code to a web server client, which is sent to the authorization server as the Referred Token Binding ID during the authorization request. The web server client conveys the Token Binding ID to the authorization server when making the access token request containing the authorization code. This binding ensures that the authorization code cannot successfully be played or replayed to the web server client from a different browser than the one that made the authorization request.
As defined in Proof Key for Code Exchange [RFC7636], the client sends the code challenge as part of the OAuth 2.0 Authorization Request with the two additional parameters: code_challenge and code_challenge_method.
The client must send the authorization request through the browser such that the Token Binding ID established between the browser and itself is revealed to the authorization server's authorization endpoint as the Referred Token Binding ID. Typically, this is done with an HTTP redirection response and the Include-Referred-Token-Binding-ID header, as defined in Section 5.3 of Token Binding over HTTP [I-D.ietf-tokbind-https].
For this Token Binding method of PKCE, referred_tb is used for the value of the code_challenge_method parameter.
The value of the code_challenge parameter is referred_tb. The static value for the required PKCE parameter indicates that the authorization code is to be bound to the Referred Token Binding ID from the Token Binding Message sent in the Sec-Token-Binding header of the authorization request.
When the authorization server issues the authorization code in the authorization response, it associates the Token Binding ID (or hash thereof) and code challenge method with the authorization code so they can be verified later when the authorization code is presented in the access token request.
For example, the web server client sends the authorization request by redirecting the browser to the authorization endpoint. That HTTP redirection response looks like the following (with extra line breaks for display purposes only).
HTTP/1.1 302 Found Location: https://server.example.com?response_type=code &client_id=example-web-client-id&state=P4FUFqYzs1ij3ffsYCP34d3 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb &code_challenge=referred_tb&code_challenge_method=referred_tb Include-Referred-Token-Binding-ID: true
Figure 15: Redirect the Browser
The redirect includes the Include-Referred-Token-Binding-ID response header field that signals to the user-agent that it should reveal, to the authorization server, the Token Binding ID used on the connection to the web server client. The resulting HTTP request to the authorization server looks something like the following (with extra line breaks for display purposes only). The base64url-encoded EKM from the TLS connection over which the request was made is 7gOdRzMhPeO-1YwZGmnVHyReN5vd2CxcsRBN69Ue4cI.
GET /as/authorization.oauth2?response_type=code &client_id=example-web-client-id&state=dryo8YFpWacbUPjhBf4Nvt51 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb &code_challenge=referred_tb &code_challenge_method=referred_tb HTTP/1.1 Host: server.example.com Sec-Token-Binding: ARIAAgBBQB-XOPf5ePlf7ikATiAFEGOS503lPmRfkyymzdWw HCxl0njjxC3D0E_OVfBNqrIQxzIfkF7tWby2ZfyaE6XpwTsAQBYqhFX78vMOgDX_F d_b2dlHyHlMmkIz8iMVBY_reM98OUaJFz5IB7PG9nZ11j58LoG5QhmQoI9NXYktKZ RXxrYAAAECAEFAdUFTnfQADkn1uDbQnvJEk6oQs38L92gv-KO-qlYadLoDIKe2h53 hSiKwIP98iRj_unedkNkAMyg9e2mY4Gp7WwBAeDUOwaSXNz1e6gKohwN4SAZ5eNyx 45Mh8VI4woL1BipLoqrJRoK6dxFkWgHRMuBROcLGUj5PiOoxybQH_Tom3gAA
Figure 16: Authorization Request
The web server client receives the authorization code from the browser and extracts the Provided Token Binding ID from the Sec-Token-Binding header of the request. The client sends the base64url-encoded (per Section 5 of [RFC4648] with all trailing padding ('=') characters omitted and without the inclusion of any line breaks or whitespace) Provided Token Binding ID as the value of the code_verifier parameter in the access token request to the authorization server's token endpoint. The authorization server compares the value of the code_verifier parameter to the Token Binding ID value previously associated with the authorization code. If the values match, the token endpoint continues processing as normal (as defined by OAuth 2.0 [RFC6749]). If the values do not match, an error response indicating "invalid_grant" MUST be returned.
Continuing the example from the previous section, the authorization server sends the code to the web server client by redirecting the browser to the client's redirect_uri, which results in the browser making a request like the following (with extra line breaks for display purposes only) to the web server client over a TLS channel for which Token Binding has been established. The base64url-encoded EKM from the TLS connection over which the request was made is EzW60vyINbsb_tajt8ij3tV6cwy2KH-i8BdEMYXcNn0.
GET /cb?state=dryo8YFpWacbUPjhBf4Nvt51&code=jwD3oOa5cQvvLc81bwc4CMw Host: client.example.org Sec-Token-Binding: AIkAAgBBQHVBU530AA5J9bg20J7yRJOqELN_C_doL_ijvqpW GnS6AyCntoed4UoisCD_fIkY_7p3nZDZADMoPXtpmOBqe1sAQEwgC9Zpg7QFCDBib 6GlZki3MhH32KNfLefLJc1vR1xE8l7OMfPLZHP2Woxh6rEtmgBcAABubEbTz7muNl Ln8uoAAA
Figure 17: Authorization Response to Web Server Client
The web server client takes the Provided Token Binding ID from the above request from the browser and sends it, base64url encoded, to the authorization server in the code_verifier parameter of the authorization code grant type request. Extra line breaks in the example request are for display purposes only.
POST /as/token.oauth2 HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded Authorization: Basic b3JnLmV4YW1wbGUuY2xpZW50OmlldGY5OGNoaWNhZ28= grant_type=authorization_code&code=jwD3oOa5cQvvLc81bwc4CMw &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Eorg%2Fcb &client_id=example-web-client-id &code_verifier=AgBBQHVBU530AA5J9bg20J7yRJOqELN_C_doL_ijv qpWGnS6AyCntoed4UoisCD_fIkY_7p3nZDZADMoPXtpmOBqe1s
Figure 18: Exchange Authorization Code
Many OAuth implementations will be deployed in situations in which not all participants support Token Binding. Any of combination of the client, the authorization server, the protected resource, and the user agent may not yet support Token Binding, in which case it will not work end-to-end.
It is a context-dependent deployment choice whether to allow interactions to proceed in which Token Binding is not supported or whether to treat Token Binding failures at any step as fatal errors. Particularly in dynamic deployment environments in which End Users have choices of clients, authorization servers, protected resources, and/or user agents, it is RECOMMENDED that authorizations using one or more components that do not implement Token Binding be allowed to successfully proceed. This enables different components to be upgraded to supporting Token Binding at different times, providing a smooth transition path for phasing in Token Binding. However, when Token Binding has been performed, any Token Binding key mismatches MUST be treated as fatal errors.
If all the participants in an authorization interaction support Token Binding and yet one or more of them does not use it, this is likely evidence of a downgrade attack. In this case, the authorization SHOULD be aborted with an error. For instance, if the protected resource knows that the authorization server and the user agent both support Token Binding and yet the access token received does not contain Token Binding information, this is almost certainly a sign of an attack.
The authorization server, client, and protected resource can determine whether the others support Token Binding using the metadata values defined in the next section. They can determine whether the user agent supports Token Binding by whether it negotiated Token Binding for the TLS connection.
Clients supporting Token Binding that also support the OAuth 2.0 Dynamic Client Registration Protocol [RFC7591] use these metadata values to declare their support for Token Binding of access tokens and refresh tokens:
Authorization servers supporting Token Binding that also support OAuth 2.0 Authorization Server Metadata [OAuth.AuthorizationMetadata] use these metadata values to declare their support for Token Binding of access tokens and refresh tokens:
Protected resources supporting Token Binding that also support the OAuth 2.0 Protected Resource Metadata [OAuth.ResourceMetadata] use this metadata value to declare their support for Token Binding of access tokens:
If a refresh request is received by the authorization server containing a Referred Token Binding ID and the refresh token in the request is not itself token bound, then it is not clear that token binding the access token adds significant value. This situation should be considered an open issue for discussion by the working group.
This specification registers the following client metadata definitions in the IANA "OAuth Dynamic Client Registration Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]:
This specification registers the following metadata definitions in the IANA "OAuth Authorization Server Metadata" registry established by [OAuth.AuthorizationMetadata]:
This specification registers the following client metadata definition in the IANA "OAuth Protected Resource Metadata" registry established by [OAuth.ResourceMetadata]:
This specification requests registration of the following Code Challenge Method Parameter Names in the IANA "PKCE Code Challenge Methods" registry [IANA.OAuth.Parameters] established by [RFC7636].
| [I-D.ietf-tokbind-https] | Popov, A., Nystrom, M., Balfanz, D., Langley, A. and J. Hodges, "Token Binding over HTTP", Internet-Draft draft-ietf-tokbind-https-08, February 2017. |
| [I-D.ietf-tokbind-negotiation] | Popov, A., Nystrom, M., Balfanz, D. and A. Langley, "Transport Layer Security (TLS) Extension for Token Binding Protocol Negotiation", Internet-Draft draft-ietf-tokbind-negotiation-07, February 2017. |
| [I-D.ietf-tokbind-protocol] | Popov, A., Nystrom, M., Balfanz, D., Langley, A. and J. Hodges, "The Token Binding Protocol Version 1.0", Internet-Draft draft-ietf-tokbind-protocol-13, February 2017. |
| [IANA.OAuth.Parameters] | IANA, "OAuth Parameters" |
| [JWT] | Jones, M., Bradley, J. and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015. |
| [OAuth.AuthorizationMetadata] | Jones, M., Sakimura, N. and J. Bradley, "OAuth 2.0 Authorization Server Metadata", Internet-Draft draft-ietf-oauth-discovery-06, March 2017. |
| [OAuth.ResourceMetadata] | Jones, M. and P. Hunt, "OAuth 2.0 Protected Resource Metadata", Internet-Draft draft-jones-oauth-resource-metadata-01, January 2017. |
| [OpenID.TokenBinding] | Jones, M., Bradley, J. and B. Campbell, "OpenID Connect Token Bound Authentication 1.0", July 2016. |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC4648] | Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006. |
| [RFC6749] | Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012. |
| [RFC7230] | Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014. |
| [RFC7636] | Sakimura, N., Bradley, J. and N. Agarwal, "Proof Key for Code Exchange by OAuth Public Clients", RFC 7636, DOI 10.17487/RFC7636, September 2015. |
| [RFC7662] | Richer, J., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015. |
| [RFC7800] | Jones, M., Bradley, J. and H. Tschofenig, "Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)", RFC 7800, DOI 10.17487/RFC7800, April 2016. |
| [SHS] | National Institute of Standards and Technology, "Secure Hash Standard (SHS)", FIPS PUB 180-4, March 2012. |
| [I-D.ietf-oauth-native-apps] | Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", Internet-Draft draft-ietf-oauth-native-apps-08, March 2017. |
| [OpenID.Core] | Sakimura, N., Bradley, J., Jones, M., de Medeiros, B. and C. Mortimore, "OpenID Connect Core 1.0", November 2014. |
| [RFC7523] | Jones, M., Campbell, B. and C. Mortimore, "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 2015. |
| [RFC7591] | Richer, J., Jones, M., Bradley, J., Machulak, M. and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015. |
The authors would like to thank the following people for their contributions to the specification: Dirk Balfanz, Andrei Popov, and Nat Sakimura.
[[ to be removed by the RFC Editor before publication as an RFC ]]
-02
-01
-00