--- 1/draft-ietf-oauth-token-binding-03.txt 2017-07-03 06:13:28.471220668 -0700 +++ 2/draft-ietf-oauth-token-binding-04.txt 2017-07-03 06:13:28.531222093 -0700 @@ -1,22 +1,22 @@ OAuth Working Group M. Jones Internet-Draft Microsoft Intended status: Standards Track J. Bradley -Expires: September 28, 2017 B. Campbell +Expires: January 4, 2018 B. Campbell Ping Identity W. Denniss Google - March 27, 2017 + July 3, 2017 OAuth 2.0 Token Binding - draft-ietf-oauth-token-binding-03 + draft-ietf-oauth-token-binding-04 Abstract 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. @@ -29,21 +29,21 @@ 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 28, 2017. + This Internet-Draft will expire on January 4, 2018. Copyright Notice 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 @@ -62,53 +62,55 @@ 2.1. Example Token Binding for Refresh Tokens . . . . . . . . 4 3. Token Binding for Access Tokens . . . . . . . . . . . . . . . 6 3.1. Access Tokens Issued from the Authorization Endpoint . . 7 3.1.1. Example Access Token Issued from the Authorization Endpoint . . . . . . . . . . . . . . . . . . . . . . 8 3.2. Access Tokens Issued from the Token Endpoint . . . . . . 9 3.2.1. Example Access Token Issued from the Token Endpoint . 9 3.3. Protected Resource Token Binding Validation . . . . . . . 11 3.3.1. Example Protected Resource Request . . . . . . . . . 11 3.4. Representing Token Binding in JWT Access Tokens . . . . . 11 - 4. Token Binding for Authorization Codes . . . . . . . . . . . . 12 - 4.1. Native Application Clients . . . . . . . . . . . . . . . 12 - 4.1.1. Code Challenge . . . . . . . . . . . . . . . . . . . 13 - 4.1.1.1. Example Code Challenge . . . . . . . . . . . . . 13 + 3.5. Representing Token Binding in Introspection Responses . . 12 + 4. Token Binding for Authorization Codes . . . . . . . . . . . . 13 + 4.1. Native Application Clients . . . . . . . . . . . . . . . 13 + 4.1.1. Code Challenge . . . . . . . . . . . . . . . . . . . 14 + 4.1.1.1. Example Code Challenge . . . . . . . . . . . . . 14 4.1.2. Code Verifier . . . . . . . . . . . . . . . . . . . . 14 - 4.1.2.1. Example Code Verifier . . . . . . . . . . . . . . 14 + 4.1.2.1. Example Code Verifier . . . . . . . . . . . . . . 15 4.2. Web Server Clients . . . . . . . . . . . . . . . . . . . 15 - 4.2.1. Code Challenge . . . . . . . . . . . . . . . . . . . 15 + 4.2.1. Code Challenge . . . . . . . . . . . . . . . . . . . 16 4.2.1.1. Example Code Challenge . . . . . . . . . . . . . 16 - 4.2.2. Code Verifier . . . . . . . . . . . . . . . . . . . . 16 - 4.2.2.1. Example Code Verifier . . . . . . . . . . . . . . 17 + 4.2.2. Code Verifier . . . . . . . . . . . . . . . . . . . . 17 + 4.2.2.1. Example Code Verifier . . . . . . . . . . . . . . 18 5. Phasing in Token Binding and Preventing Downgrade Attacks . . 18 - 6. Token Binding Metadata . . . . . . . . . . . . . . . . . . . 18 - 6.1. Token Binding Client Metadata . . . . . . . . . . . . . . 18 - 6.2. Token Binding Authorization Server Metadata . . . . . . . 19 - 6.3. Token Binding Protected Resource Metadata . . . . . . . . 19 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 19 + 6. Token Binding Metadata . . . . . . . . . . . . . . . . . . . 19 + 6.1. Token Binding Client Metadata . . . . . . . . . . . . . . 19 + 6.2. Token Binding Authorization Server Metadata . . . . . . . 20 + 6.3. Token Binding Protected Resource Metadata . . . . . . . . 20 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 20 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 8.1. OAuth Dynamic Client Registration Metadata Registration . 20 - 8.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 20 - 8.2. OAuth Authorization Server Metadata Registration . . . . 20 - 8.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 20 + 8.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 + 8.2. OAuth Authorization Server Metadata Registration . . . . 21 + 8.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 8.3. OAuth Protected Resource Metadata Registration . . . . . 21 8.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 - 8.4. PKCE Code Challenge Method Registration . . . . . . . . . 21 - 8.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 - 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 - 9.1. Normative References . . . . . . . . . . . . . . . . . . 21 - 9.2. Informative References . . . . . . . . . . . . . . . . . 23 + + 8.4. PKCE Code Challenge Method Registration . . . . . . . . . 22 + 8.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 + 9.1. Normative References . . . . . . . . . . . . . . . . . . 22 + 9.2. Informative References . . . . . . . . . . . . . . . . . 24 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 24 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 24 - Appendix C. Document History . . . . . . . . . . . . . . . . . . 24 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 + Appendix C. Document History . . . . . . . . . . . . . . . . . . 25 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 1. Introduction 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 @@ -177,25 +179,25 @@ 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. + 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 @@ -317,25 +319,25 @@ [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. + possibly using the syntax described in Section 3.4, or through token + introspection as described in Section 3.5. 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. 3.1.1. Example Access Token Issued from the Authorization Endpoint 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 @@ -396,25 +398,25 @@ 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. + using the syntax described in Section 3.4, or through token + introspection as described in Section 3.5. 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. 3.2.1. Example Access Token Issued from the Token Endpoint 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 @@ -528,20 +530,58 @@ "sub": "brian@example.com" "iat": 1467324320, "exp": 1467324920, "cnf":{ "tbh": "7NRBu9iDdJlYCTOqyeYuLxXv0blEA-yTpmGIrAwKAws" } } Figure 12: JWT with Token Binding Hash Confirmation Claim +3.5. Representing Token Binding in Introspection Responses + + OAuth 2.0 Token Introspection [RFC7662] defines a method for a + protected resource to query an authorization server about the active + state of an access token as well as to determine meta-information + about the token. + + For a token bound access token, the hash of the Token Binding ID to + which the token is bound is conveyed to the protected resource as + meta-information in a token introspection response. The hash is + conveyed using same structure as the token binding hash confirmation + method, described in Section 3.4, as a top-level member of the + introspection response JSON. The protected resource compares that + token binding hash to a hash of the provided Token Binding ID and + rejects the request, if they do not match. + + The following is an example of an introspection response for an + active token bound access token with an "tbh" token binding hash + confirmation method. + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "active": true, + "iss": "https://server.example.com", + "aud": "https://resource.example.org", + "sub": "brian@example.com" + "iat": 1467324320, + "exp": 1467324920, + "cnf":{ + "tbh": "7NRBu9iDdJlYCTOqyeYuLxXv0blEA-yTpmGIrAwKAws" + } + } + + Figure 13: Example Introspection Response for a Token Bound Access + Token + 4. Token Binding for Authorization Codes 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 @@ -597,30 +637,31 @@ 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 with PKCE Challenge + Figure 14: Authorization Request with PKCE Challenge 4.1.2. Code Verifier 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 @@ -643,21 +684,21 @@ 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: Token Request with PKCE Verifier + Figure 15: Token Request with PKCE Verifier 4.2. Web Server Clients 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 @@ -704,21 +745,21 @@ 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 + Figure 16: 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". @@ -728,21 +769,21 @@ &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 + Figure 17: Authorization Request 4.2.2. Code Verifier 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 @@ -764,40 +805,40 @@ 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 + Figure 18: 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 + Figure 19: Exchange Authorization Code 5. Phasing in Token Binding and Preventing Downgrade Attacks 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 @@ -1065,51 +1107,88 @@ 2015, . [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015, . Appendix A. Acknowledgements The authors would like to thank the following people for their - contributions to the specification: Dirk Balfanz, Andrei Popov, and - Nat Sakimura. + contributions to the specification: Dirk Balfanz, Andrei Popov, + Justin Richer, and Nat Sakimura. Appendix B. Open Issues o What should we do in the case that a refresh request for a token bound access token is received when the refresh token used in the request is not token bound? - o Should the scope of this document include standardizing or - recommending how to convey token binding information of an access - token via RFC 7662 OAuth 2.0 Token Introspection? + o Currently the only way to request a token bound access token is + via the referred token binding. By definition the referred token + binding also comes with the provided token binding and the + provided token binding is what is used to bind the refresh token. + However, web server clients will typically be distributed/ + clustered and very likely will not want to, or be capable of, + dealing with token bound refresh tokens. Such clients will have + credentials established with the AS for authenticating to the + token endpoint and refresh tokens are already bound to the client. + So token binding the refresh tokens doesn't add much, if anything, + in this case. But accessing private token binding keys in a + distributed system will be cumbersome or even impossible. + Tracking and properly utilizing the association of a token binding + key with each individual refresh token would also be exceptionally + cumbersome (whereas client credentials are for the client and + decoupled from individual refresh tokens) but without some such + mechanism the token binding key cannot be changed without + implicitly invalidating all the bound refresh tokens the web + server client has stored for that AS. It seems necessary to + provide some mechanism for a client to opt-out of having refresh + tokens token bound while still allowing for token binding of + access tokens. o Should the scope of this document include standardization or guidance on token binding of JWT Client Authentication and/or Authorization Grants from RFC 7523? o The Metadata (Section 6) and what can and cannot be reliably inferred from it (Section 5) need additional evaluation and work. OAuth 2.0 Protected Resource Metadata [OAuth.ResourceMetadata] is no longer a going concern, but is currently referenced herein. Boolean values do not adequately convey Token Binding support, as different components may support different key parameters types. And successful negotiation likely doesn't provide the application layer info about all the supported key parameters types but rather just the one that was negotiated. Appendix C. Document History [[ to be removed by the RFC Editor before publication as an RFC ]] + -04 + + o Define how to convey token binding information of an access token + via RFC 7662 OAuth 2.0 Token Introspection (note that the + Introspection Response Registration request for cnf/Confirmation + is in https://tools.ietf.org/html/draft-ietf-oauth-mtls- + 02#section-4.3 which will likely be published and registered prior + to this document). + + o Minor editorial fixes. + + o Added an open issue about needing to allow for web server clients + to opt-out of having refresh tokens bound while still allowing for + binding of access tokens (following from mention of the problem on + slide 16 of the presentation from Chicago + https://www.ietf.org/proceedings/98/slides/slides-98-oauth-sessb- + token-binding-00.pdf). + -03 o Fix a few mistakes in and around the examples that were noticed preparing the slides for IETF 98 Chicago. -02 o Added a section on Token Binding for authorization codes with one variation for native clients and one for web server clients.