OAuth 2.0 Token BindingMicrosoftmbj@microsoft.comhttp://self-issued.info/Ping Identityve7jtb@ve7jtb.comhttp://www.thread-safe.com/Ping Identitybrian.d.campbell@gmail.comhttps://twitter.com/__b_cSecurity
OAuth Working GroupOAuthToken BindingProof-of-PossessionPoP
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.0Token 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 Endpoint", "Authorization Server",
"Client", "Protected Resource", "Refresh Token",
and "Token Endpoint"
defined by OAuth 2.0,
the terms "Claim" 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 4 (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.
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 )
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 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.
It 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 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.
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 , the Referred Token Binding ID
used to bind the access token is sent with the authorization request.
Upon receiving the Referred Token Binding ID
in an authorization request,
the authorization server then records it
(or a cryptographic hash of it)
in the issued access token.
Alternatively, in some implementations, the resource's Token Binding ID information
might be communicated to the protected resource by other means,
such as by introspecting the access token.
For access tokens returned from the token endpoint,
the Referred Token Binding ID used to bind the access token
is sent with the token request.
This applies to all the conventional grant types from OAuth 2.0 ,
including but not limited to refresh and authorization code token requests,
as well as extension grants, such as JWT assertion authorization grants .
In this case, the Token Binding ID
of the TLS connection between the client and the protected resource
is sent to the authorization server at the token endpoint as the
Referred Token Binding ID.
The authorization server then records it
(or a cryptographic hash of it)
in the issued access token
or communicates it to the protected resource by other means,
just as in the previous case.
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.
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 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
use these metadata values to declare 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 declare 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.
Protected resources supporting Token Binding that also support
the OAuth 2.0 Protected Resource Metadata
use this metadata value to declare their support for Token Binding
of access tokens:
OPTIONAL.
Boolean value specifying whether the protected resource supports Token Binding of access tokens.
If omitted, the default value is false.
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
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 metadata definitions
in the IANA "OAuth Authorization Server Metadata" registry
established by :
Metadata Name: as_access_token_token_binding_supported
Metadata Description:
Boolean value specifying whether the authorization server supports Token Binding of access tokens
Change Controller: IESG
Specification Document(s): of [[ this specification ]]
Metadata Name: as_refresh_token_token_binding_supported
Metadata Description:
Boolean value specifying whether the authorization server supports Token Binding of refresh tokens
Change Controller: IESG
Specification Document(s): of [[ this specification ]]
This specification registers the following client metadata definition
in the IANA "OAuth Protected Resource Metadata" registry
established by :
Resource Metadata Name: resource_access_token_token_binding_supported
Resource Metadata Description:
Boolean value specifying whether the protected resource supports Token Binding of access tokens
Change Controller: IESG
Specification Document(s): of [[ this specification ]]
OpenID Connect Token Bound Authentication 1.0MicrosoftPing IdentityPing IdentityOAuth 2.0 Authorization Server MetadataMicrosoftmbj@microsoft.comhttp://self-issued.info/Nomura Research Institute, Ltd.n-sakimura@nri.co.jphttp://nat.sakimura.org/Ping Identityve7jtb@ve7jtb.comhttp://www.thread-safe.com/OAuth 2.0 Protected Resource MetadataMicrosoftmbj@microsoft.comhttp://self-issued.info/Oraclephil.hunt@yahoo.comJSON Web Token (JWT)MicrosoftPing IdentityNomura Research Institute, Ltd.Secure Hash Standard (SHS)National Institute of Standards and
TechnologyOAuth ParametersIANAOpenID Connect Core 1.0Nomura Research Institute, Ltd.Ping IdentityMicrosoftGoogleSalesforce
The authors would like to thank the following people for their contributions to the specification:
Dirk Balfanz,
William Denniss,
Andrei Popov,
and
Nat Sakimura.
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?
[[ to be removed by the RFC Editor before publication as an RFC ]]
-01
Changed Token Binding for access tokens to use the Referred Token Binding ID,
now that the Implementation Considerations in the Token Binding HTTPS specification
make it clear that implementations will enable using the Referred Token Binding ID.
Defined Protected Resource Metadata value.
Changed to use the more specific term "protected resource" instead of "resource server".
-00
Created the initial working group version from draft-jones-oauth-token-binding-00.