draft-ietf-oauth-token-binding-06.txt   draft-ietf-oauth-token-binding-07.txt 
OAuth Working Group M. Jones OAuth Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track B. Campbell Intended status: Standards Track B. Campbell
Expires: September 2, 2018 Ping Identity Expires: December 23, 2018 Ping Identity
J. Bradley J. Bradley
Yubico Yubico
W. Denniss W. Denniss
Google Google
March 1, 2018 June 21, 2018
OAuth 2.0 Token Binding OAuth 2.0 Token Binding
draft-ietf-oauth-token-binding-06 draft-ietf-oauth-token-binding-07
Abstract Abstract
This specification enables OAuth 2.0 implementations to apply Token This specification enables OAuth 2.0 implementations to apply Token
Binding to Access Tokens, Authorization Codes, Refresh Tokens, JWT Binding to Access Tokens, Authorization Codes, Refresh Tokens, JWT
Authorization Grants, and JWT Client Authentication. This Authorization Grants, and JWT Client Authentication. This
cryptographically binds these tokens to a client's Token Binding key cryptographically binds these tokens to a client's Token Binding key
pair, possession of which is proven on the TLS connections over which pair, possession of which is proven on the TLS connections over which
the tokens are intended to be used. This use of Token Binding the tokens are intended to be used. This use of Token Binding
protects these tokens from man-in-the-middle and token export and protects these tokens from man-in-the-middle and token export and
skipping to change at page 1, line 42 skipping to change at page 1, line 42
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 2, 2018. This Internet-Draft will expire on December 23, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 4, line 17 skipping to change at page 4, line 17
2. Token Binding for Refresh Tokens 2. Token Binding for Refresh Tokens
Token Binding of refresh tokens is a straightforward first-party Token Binding of refresh tokens is a straightforward first-party
scenario, applying term "first-party" as used in Token Binding over scenario, applying term "first-party" as used in Token Binding over
HTTP [I-D.ietf-tokbind-https]. It cryptographically binds the HTTP [I-D.ietf-tokbind-https]. It cryptographically binds the
refresh token to the client's Token Binding key pair, possession of refresh token to the client's Token Binding key pair, possession of
which is proven on the TLS connections between the client and the which is proven on the TLS connections between the client and the
token endpoint. This case is straightforward because the refresh token endpoint. This case is straightforward because the refresh
token is both retrieved by the client from the token endpoint and token is both retrieved by the client from the token endpoint and
sent by the client to the token endpoint. Unlike the federated sent by the client to the token endpoint. Unlike the federation use
scenarios described in Section 4 (Federation Use Cases) of Token cases described in Token Binding over HTTP [I-D.ietf-tokbind-https],
Binding over HTTP [I-D.ietf-tokbind-https] and the access token case Section 4, and the access token case described in the next section,
described in the next section, only a single TLS connection is only a single TLS connection is involved in the refresh token case.
involved in the refresh token case.
Token Binding a refresh token requires that the authorization server Token Binding a refresh token requires that the authorization server
do two things. First, when refresh token is sent to the client, the do two things. First, when refresh token is sent to the client, the
authorization server needs to remember the Provided Token Binding ID authorization server needs to remember the Provided Token Binding ID
and remember its association with the issued refresh token. Second, and remember its association with the issued refresh token. Second,
when a token request containing a refresh token is received at the when a token request containing a refresh token is received at the
token endpoint, the authorization server needs to verify that the token endpoint, the authorization server needs to verify that the
Provided Token Binding ID for the request matches the remembered Provided Token Binding ID for the request matches the remembered
Token Binding ID associated with the refresh token. If the Token Token Binding ID associated with the refresh token. If the Token
Binding IDs do not match, the authorization server should return an Binding IDs do not match, the authorization server should return an
skipping to change at page 7, line 23 skipping to change at page 7, line 23
} }
Figure 4: Successful Response Figure 4: Successful Response
3. Token Binding for Access Tokens 3. Token Binding for Access Tokens
Token Binding for access tokens cryptographically binds the access Token Binding for access tokens cryptographically binds the access
token to the client's Token Binding key pair, possession of which is token to the client's Token Binding key pair, possession of which is
proven on the TLS connections between the client and the protected proven on the TLS connections between the client and the protected
resource. Token Binding is applied to access tokens in a similar resource. Token Binding is applied to access tokens in a similar
manner to that described in Section 4 (Federation Use Cases) of Token manner to that described in Token Binding over HTTP
Binding over HTTP [I-D.ietf-tokbind-https]. It also builds upon the [I-D.ietf-tokbind-https], Section 4 (Federation Use Cases). It also
mechanisms for Token Binding of ID Tokens defined in OpenID Connect builds upon the mechanisms for Token Binding of ID Tokens defined in
Token Bound Authentication 1.0 [OpenID.TokenBinding]. OpenID Connect Token Bound Authentication 1.0 [OpenID.TokenBinding].
In the OpenID Connect [OpenID.Core] use case, HTTP redirects are used In the OpenID Connect [OpenID.Core] use case, HTTP redirects are used
to pass information between the identity provider and the relying to pass information between the identity provider and the relying
party; this HTTP redirect makes the Token Binding ID of the relying party; this HTTP redirect makes the Token Binding ID of the relying
party available to the identity provider as the Referred Token party available to the identity provider as the Referred Token
Binding ID, information about which is then added to the ID Token. Binding ID, information about which is then added to the ID Token.
No such redirect occurs between the authorization server and the No such redirect occurs between the authorization server and the
protected resource in the access token case; therefore, information protected resource in the access token case; therefore, information
about the Token Binding ID for the TLS connection between the client about the Token Binding ID for the TLS connection between the client
and the protected resource needs to be explicitly communicated by the and the protected resource needs to be explicitly communicated by the
client to the authorization server to achieve Token Binding of the client to the authorization server to achieve Token Binding of the
access token. access token.
This information is passed to the authorization server using the This information is passed to the authorization server using the
Referred Token Binding ID, just as in the ID Token case. The only Referred Token Binding ID, just as in the ID Token case. The only
difference is that the client needs to explicitly communicate the difference is that the client needs to explicitly communicate the
Token Binding ID of the TLS connection between the client and the Token Binding ID of the TLS connection between the client and the
protected resource to the Token Binding implementation so that it is protected resource to the Token Binding implementation so that it is
sent as the Referred Token Binding ID in the request to the sent as the Referred Token Binding ID in the request to the
authorization server. This functionality provided by Token Binding authorization server. This functionality provided by Token Binding
implementations is described in Section 5 (Implementation implementations is described in Implementation Considerations of
Considerations) of Token Binding over HTTP [I-D.ietf-tokbind-https]. Token Binding over HTTP [I-D.ietf-tokbind-https], Section 6.
Note that to obtain this Token Binding ID, the client may need to Note that to obtain this Token Binding ID, the client may need to
establish a TLS connection between itself and the protected resource establish a TLS connection between itself and the protected resource
prior to making the request to the authorization server so that the prior to making the request to the authorization server so that the
Provided Token Binding ID for the TLS connection to the protected Provided Token Binding ID for the TLS connection to the protected
resource can be obtained. How the client retrieves this Token resource can be obtained. How the client retrieves this Token
Binding ID from the underlying Token Binding API is implementation Binding ID from the underlying Token Binding API is implementation
and operating system specific. An alternative, if supported, is for and operating system specific. An alternative, if supported, is for
the client to generate a Token Binding key to use for the protected 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 resource, use the Token Binding ID for that key, and then later use
that key when the TLS connection to the protected resource is that key when the TLS connection to the protected resource is
established. established.
3.1. Access Tokens Issued from the Authorization Endpoint 3.1. Access Tokens Issued from the Authorization Endpoint
For access tokens returned directly from the authorization endpoint, For access tokens returned directly from the authorization endpoint,
such as with the implicit grant defined in Section 4.2 of OAuth 2.0 such as with the implicit grant defined in OAuth 2.0 [RFC6749],
[RFC6749], the Token Binding ID of the client's TLS channel to the Section 4.2, the Token Binding ID of the client's TLS channel to the
protected resource is sent with the authorization request as the protected resource is sent with the authorization request as the
Referred Token Binding ID in the "Sec-Token-Binding" header, and is Referred Token Binding ID in the "Sec-Token-Binding" header, and is
used to Token Bind the access token. used to Token Bind the access token.
Upon receiving the Referred Token Binding ID in an authorization Upon receiving the Referred Token Binding ID in an authorization
request, the authorization server associates (Token Binds) the ID request, the authorization server associates (Token Binds) the ID
with the access token in a way that can be accessed by the protected with the access token in a way that can be accessed by the protected
resource. Such methods include embedding the Referred Token Binding resource. Such methods include embedding the Referred Token Binding
ID (or a cryptographic hash of it) in the issued access token itself, ID (or a cryptographic hash of it) in the issued access token itself,
possibly using the syntax described in Section 3.4, or through token possibly using the syntax described in Section 3.4, or through token
skipping to change at page 12, line 44 skipping to change at page 12, line 44
3.4. Representing Token Binding in JWT Access Tokens 3.4. Representing Token Binding in JWT Access Tokens
If the access token is represented as a JWT, the token binding 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 information SHOULD be represented in the same way that it is in token
bound OpenID Connect ID Tokens [OpenID.TokenBinding]. That bound OpenID Connect ID Tokens [OpenID.TokenBinding]. That
specification defines the new JWT Confirmation Method RFC 7800 specification defines the new JWT Confirmation Method RFC 7800
[RFC7800] member "tbh" (token binding hash) to represent the SHA-256 [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" 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 member is the base64url encoding of the SHA-256 hash of the Token
Binding ID. Binding ID. All all trailing pad '=' characters are omitted from the
encoded value and no line breaks, whitespace, or other additional
characters are included.
The following example demonstrates the JWT Claims Set of an access The following example demonstrates the JWT Claims Set of an access
token containing the base64url encoding of the SHA-256 hash of a token containing the base64url encoding of the SHA-256 hash of a
Token Binding ID as the value of the "tbh" (token binding hash) Token Binding ID as the value of the "tbh" (token binding hash)
element in the "cnf" (confirmation) claim: element in the "cnf" (confirmation) claim:
{ {
"iss": "https://server.example.com", "iss": "https://server.example.com",
"aud": "https://resource.example.org", "aud": "https://resource.example.org",
"sub": "brian@example.com" "sub": "brian@example.com"
skipping to change at page 18, line 17 skipping to change at page 18, line 17
As defined in Proof Key for Code Exchange [RFC7636], the client sends As defined in Proof Key for Code Exchange [RFC7636], the client sends
the code challenge as part of the OAuth 2.0 Authorization Request the code challenge as part of the OAuth 2.0 Authorization Request
with the two additional parameters: "code_challenge" and with the two additional parameters: "code_challenge" and
"code_challenge_method". "code_challenge_method".
The client must send the authorization request through the browser The client must send the authorization request through the browser
such that the Token Binding ID established between the browser and such that the Token Binding ID established between the browser and
itself is revealed to the authorization server's authorization itself is revealed to the authorization server's authorization
endpoint as the Referred Token Binding ID. Typically, this is done endpoint as the Referred Token Binding ID. Typically, this is done
with an HTTP redirection response and the "Include-Referred-Token- with an HTTP redirection response and the "Include-Referred-Token-
Binding-ID" header, as defined in Section 5.3 of Token Binding over Binding-ID" header, as defined in Token Binding over HTTP
HTTP [I-D.ietf-tokbind-https]. [I-D.ietf-tokbind-https], Section 5.3.
For this Token Binding method of PKCE, "referred_tb" is used for the For this Token Binding method of PKCE, "referred_tb" is used for the
value of the "code_challenge_method" parameter. value of the "code_challenge_method" parameter.
The value of the "code_challenge" parameter is "referred_tb". The The value of the "code_challenge" parameter is "referred_tb". The
static value for the required PKCE parameter indicates that the static value for the required PKCE parameter indicates that the
authorization code is to be bound to the Referred Token Binding ID authorization code is to be bound to the Referred Token Binding ID
from the Token Binding Message sent in the "Sec-Token-Binding" header from the Token Binding Message sent in the "Sec-Token-Binding" header
of the authorization request. of the authorization request.
skipping to change at page 25, line 42 skipping to change at page 25, line 42
o Change controller: IESG o Change controller: IESG
o Specification Document: Section 6 of [[ this specification ]] o Specification Document: Section 6 of [[ this specification ]]
11. References 11. References
11.1. Normative References 11.1. Normative References
[I-D.ietf-tokbind-https] [I-D.ietf-tokbind-https]
Popov, A., Nystrom, M., Balfanz, D., Langley, A., Harper, Popov, A., Nystrom, M., Balfanz, D., Langley, A., Harper,
N., and J. Hodges, "Token Binding over HTTP", draft-ietf- N., and J. Hodges, "Token Binding over HTTP", draft-ietf-
tokbind-https-12 (work in progress), January 2018. tokbind-https-17 (work in progress), June 2018.
[I-D.ietf-tokbind-negotiation] [I-D.ietf-tokbind-negotiation]
Popov, A., Nystrom, M., Balfanz, D., and A. Langley, Popov, A., Nystrom, M., Balfanz, D., and A. Langley,
"Transport Layer Security (TLS) Extension for Token "Transport Layer Security (TLS) Extension for Token
Binding Protocol Negotiation", draft-ietf-tokbind- Binding Protocol Negotiation", draft-ietf-tokbind-
negotiation-10 (work in progress), October 2017. negotiation-14 (work in progress), May 2018.
[I-D.ietf-tokbind-protocol] [I-D.ietf-tokbind-protocol]
Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J. Popov, A., Nystrom, M., Balfanz, D., Langley, A., and J.
Hodges, "The Token Binding Protocol Version 1.0", draft- Hodges, "The Token Binding Protocol Version 1.0", draft-
ietf-tokbind-protocol-16 (work in progress), October 2017. ietf-tokbind-protocol-19 (work in progress), May 2018.
[IANA.OAuth.Parameters] [IANA.OAuth.Parameters]
IANA, "OAuth Parameters", IANA, "OAuth Parameters",
<http://www.iana.org/assignments/oauth-parameters>. <http://www.iana.org/assignments/oauth-parameters>.
[JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<http://tools.ietf.org/html/rfc7519>. <http://tools.ietf.org/html/rfc7519>.
[OAuth.AuthorizationMetadata] [OAuth.AuthorizationMetadata]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", draft-ietf-oauth- Authorization Server Metadata", draft-ietf-oauth-
discovery-09 (work in progress), March 2017, discovery-10 (work in progress), March 2017,
<http://tools.ietf.org/html/ <http://tools.ietf.org/html/
draft-ietf-oauth-discovery-09>. draft-ietf-oauth-discovery-10>.
[OpenID.TokenBinding] [OpenID.TokenBinding]
Jones, M., Bradley, J., and B. Campbell, "OpenID Connect Jones, M., Bradley, J., and B. Campbell, "OpenID Connect
Token Bound Authentication 1.0", October 2017, Token Bound Authentication 1.0", October 2017,
<http://openid.net/specs/ <http://openid.net/specs/
openid-connect-token-bound-authentication-1_0-02.html>. openid-connect-token-bound-authentication-1_0-02.html>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
skipping to change at page 28, line 19 skipping to change at page 28, line 19
Appendix A. Acknowledgements Appendix A. Acknowledgements
The authors would like to thank the following people for their The authors would like to thank the following people for their
contributions to the specification: Dirk Balfanz, Andrei Popov, contributions to the specification: Dirk Balfanz, Andrei Popov,
Justin Richer, and Nat Sakimura. Justin Richer, and Nat Sakimura.
Appendix B. Document History Appendix B. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
-07
o Explicitly state that the base64url encoding of the tbh value
doesn't include any trailing pad characters, line breaks,
whitespace, etc.
o Update to latest references for tokbind drafts and draft-ietf-
oauth-discovery.
o Update reference to Implementation Considerations in draft-ietf-
tokbind-https, which is section 6 rather than 5.
o Try to tweak text that references specific sections in other
documents so that the HTML generated by the ietf tools doesn't
link to the current document (based on old suggestion from Barry
https://www.ietf.org/mail-archive/web/jose/current/msg04571.html).
-06 -06
o Use the boilerplate from RFC 8174. o Use the boilerplate from RFC 8174.
o Update reference for draft-ietf-tokbind-https to -12 and draft- o Update reference for draft-ietf-tokbind-https to -12 and draft-
ietf-oauth-discovery to -09. ietf-oauth-discovery to -09.
o Minor editorial fixes. o Minor editorial fixes.
-05 -05
 End of changes. 16 change blocks. 
25 lines changed or deleted 43 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/