Microsoft

mbj@microsoft.com http://self-issued.info/

Ping Identity

ve7jtb@ve7jtb.com http://www.thread-safe.com/

Ping Identity

brian.d.campbell@gmail.com https://twitter.com/__b_c

Security OAuth Working Group OAuth Token Binding Proof-of-Possession PoP This specification enables OAuth 2.0 implementations to apply Token Binding to Access Tokens and Refresh Tokens. This cryptographically binds these tokens to the TLS connections over which they 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 specification enables OAuth 2.0 implementations to apply Token Binding The Token Binding Protocol Version 1.0 Token Binding over HTTP to Access Tokens and Refresh Tokens. This cryptographically binds these tokens to the TLS connections over which they 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.

This specification uses the terms "Access Token", "Authorization Code", "Authorization Endpoint", "Authorization Grant", "Authorization Server", "Client", "Client Authentication", "Client Identifier", "Client Secret", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Owner", "Resource Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0, the terms "Claim", "Claim Name", "Claim Value", and "JSON Web Token (JWT)" defined by JSON Web Token (JWT), the term "User Agent" defined by RFC 7230, and the terms "Provided", "Referred", "Token Binding" and "Token Binding ID" defined by Token Binding over HTTP.

Token Binding of refresh tokens is a straightforward first-party scenario, applying term "first-party" as used in Token Binding over HTTP. It cryptographically binds the refresh token to the TLS connection 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 3 (Federation Use Cases) of Token Binding over HTTP 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. The means by which 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 ) in the refresh token itself, 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.

Token Binding for access tokens cryptographically binds the access token to the TLS connection between the client and the resource server. Token Binding is applied to access tokens in a similar manner to that described in Section 3 (Federation Use Cases) of Token Binding over HTTP. It is also builds upon the mechanisms for Token Binding of ID Tokens defined in OpenID Connect Token Bound Authentication 1.0. In the OpenID Connect 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 resource server in the access token case; therefore, information about the Token Binding ID for the TLS connection between the client and the resource server 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 this request parameter: Base64url encoding of the SHA-256 hash of the Token Binding ID for the TLS connection between the client and the resource server. Note that to obtain this Token Binding ID, the client needs to establish a TLS connection between itself and the resource server prior to making the authorization request so that the Provided Token Binding ID for the TLS connection to the resource server can be obtained. The means by which 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 resource server, use the Token Binding ID for that key, and then later use that key when the TLS connection to the resource server is established. The authorization server MUST ignore the resource_tbh parameter if it does not support Token Binding for the access token.

Upon receiving the hash of the Token Binding ID in an authorization request containing the resource_tbh (resource token binding hash) authorization request parameter, the authorization server then records it in the issued access token. Alternatively, in some implementations, the resource's Token Binding ID hash might be communicated to the resource server by other means, such as by introspecting the access token.

Access tokens obtained from refresh requests can also be token bound. In this case, the hash of the Token Binding ID of the TLS connection between the client and the resource server is sent to the authorization server at the token endpoint using the resource_tbh (resource token binding hash) token request parameter; its syntax is exactly the same as the corresponding authorization request parameter. The authorization server then records it in the issued access token or communicates it to the resource server by other means, just as in the previous case.

Upon receiving a token bound access token, the resource server validates the binding by computing a SHA-256 hash of the Provided Token Binding ID and comparing it to the token binding hash value for the access token. If these values do not match, the resource access attempt MUST be rejected with an error.

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 . That specification defines the new JWT Confirmation Method RFC 7800 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:

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 resource server, 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, resource servers, 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 resource server 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 and client can determine whether the other supports 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. At present, there is no defined mechanism for determining whether the resource server supports Token Binding or not. However, it always safe to proceed as if it does; at worst, the resource server simply won't verify the Token Binding.

Clients supporting Token Binding that also support the OAuth 2.0 Dynamic Client Registration Protocol use these metadata values to register their support for Token Binding of Access Tokens and Refresh Tokens: OPTIONAL. Boolean value specifying whether the Client supports Token Binding of Access Tokens. If omitted, the default value is false. OPTIONAL. Boolean value specifying whether the Client supports Token Binding of Refresh Tokens. If omitted, the default value is false.

Authorization Servers supporting Token Binding that also support OAuth 2.0 Authorization Server Metadata use these metadata values to register their support for Token Binding of Access Tokens and Refresh Tokens: OPTIONAL. Boolean value specifying whether the Authorization Server supports Token Binding of Access Tokens. If omitted, the default value is false. OPTIONAL. Boolean value specifying whether the Authorization Server supports Token Binding of Refresh Tokens. If omitted, the default value is false.

If a refresh request is received by the authorization server containing a resource_tbh (resource token binding hash) value requesting a token bound access token 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 parameter in the IANA "OAuth Parameters" registry established by RFC 6749:

Parameter name: resource_tbh Parameter usage location: Authorization Request, Token Request Change controller: IESG Specification document(s): of this document Related information: None

This specification registers the following client metadata definitions in the IANA "OAuth Dynamic Client Registration Metadata" registry established by :

Client Metadata Name: client_access_token_token_binding_supported Client Metadata Description: Boolean value specifying whether the Client supports Token Binding of Access Tokens Change Controller: IESG Specification Document(s): of [[ this specification ]] Client Metadata Name: client_refresh_token_token_binding_supported Client Metadata Description: Boolean value specifying whether the Client supports Token Binding of Refresh Tokens Change Controller: IESG Specification Document(s): of [[ this specification ]]

This specification registers the following discovery metadata definitions in the IANA "OAuth Authorization Server Discovery Metadata" registry established by :

Discovery Metadata Name: as_access_token_token_binding_supported Discovery Metadata Description: Boolean value specifying whether the Authorization Server supports Token Binding of Access Tokens Change Controller: IESG Specification Document(s): of [[ this specification ]] Discovery Metadata Name: as_refresh_token_token_binding_supported Discovery Metadata Description: Boolean value specifying whether the Authorization Server supports Token Binding of Refresh Tokens Change Controller: IESG Specification Document(s): of [[ this specification ]]

Microsoft Ping Identity Ping Identity Microsoft Ping Identity Nomura Research Institute, Ltd. National Institute of Standards and Technology IANA Microsoft

mbj@microsoft.com http://self-issued.info/

Nomura Research Institute, Ltd.

n-sakimura@nri.co.jp http://nat.sakimura.org/

Ping Identity

ve7jtb@ve7jtb.com http://www.thread-safe.com/

Nomura Research Institute, Ltd. Ping Identity Microsoft Google Salesforce

The authors would like to thank the following people for their contributions to the specification: Dirk Balfanz, William Denniss, Andrei Popov, and Nat Sakimura.

Some token binding implementations apparently provide APIs that enable native applications to provide Referred Token Bindings, just as the federation support in the HTTPS Token Binding spec does. Can we count on these APIs being supported on all platforms, and if so, does this enable us to somehow do without the resource_tbh parameter by mandating that the client send both a Provided and a Referred Token Binding to the authorization server? If this isn't the case, is resource_tbh actually secure or does this open a cross-channel validation hole? This area probably needs more attention from both the Token Binding and OAuth working groups. How should we support crypto agility for the hash function?

[[ to be removed by the RFC Editor before publication as an RFC ]] -00 Created the initial working group version from draft-jones-oauth-token-binding-00.