OpenID Connect
Token Bound Authentication 1.0 - draft 04Microsoftmbj@microsoft.comhttp://self-issued.info/Yubicove7jtb@ve7jtb.comhttp://www.thread-safe.com/Ping Identitybrian.d.campbell@gmail.comhttps://twitter.com/__b_cOpenID Extended Authentication Profile (EAP) Working GroupOpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0
protocol. It enables Clients to verify the identity of the End-User based
on the authentication performed by an Authorization Server, as well as to
obtain basic profile information about the End-User in an interoperable and
REST-like manner.
This specification enables OpenID Connect implementations to apply
Token Binding to the OpenID Connect ID Token.
This cryptographically binds the ID Token to the TLS connections
over which the authentication occurred.
This use of Token Binding protects the authentication flow
from man-in-the-middle and token export and replay attacks.
OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0
protocol. It enables Clients to verify the identity of the End-User based
on the authentication performed by an Authorization Server, as well as to
obtain basic profile information about the End-User in an interoperable and
REST-like manner.
This specification enables OpenID Connect implementations to apply
Token Binding
The Token Binding Protocol Version 1.0Token Binding over HTTP
to the OpenID Connect ID Token
defined by OpenID Connect Core 1.0.
This cryptographically binds the ID Token to the TLS connections
over which the authentication occurred.
Token Binding is applied to OpenID Connect in the manner described in
Section 5 (Federation Use Cases) of
Token Binding over HTTP.
As described in Section 7.4 (Securing Federated Sign-On Protocols) of
Token Binding over HTTP,
this use of Token Binding protects the authentication flow
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.
In the .txt version of this specification,
values are quoted to indicate that they are to be taken literally.
When using these values in protocol messages,
the quotes MUST NOT be used as part of the value.
In the HTML version of this specification,
values to be taken literally are indicated by
the use of this fixed-width font.
This specification uses the terms
"Authorization Endpoint", "Authorization Server",
"Client", "Response Type", and "Token Endpoint"
defined by OAuth 2.0,
the terms "Claim", "JSON Web Token (JWT)",
and "JWT Claims Set"
defined by JSON Web Token (JWT),
the term "User Agent" defined by RFC 7230,
the terms "Provided", "Referred", "Token Binding" and "Token Binding ID"
defined by Token Binding over HTTP,
and the terms defined by
OpenID Connect Core 1.0.
Section 5 (Federation Use Cases) of
Token Binding over HTTP
outlines how Token Binding is used with federation protocols in the abstract.
This section defines the concrete data structures for using Token Binding
with OpenID Connect.
Section 5.2 of
Token Binding over HTTP
suggests placing the Token Binding ID of the Token Binding
used to communicate with the Relying Party in the ID Token.
A representation of this key is communicated to the OpenID Provider
in its Referred Token Binding ID.
This specification utilizes a variant of this approach in which
a cryptographic hash of the Token Binding ID
using the SHA-256 hash function
is instead added to the ID Token.
This has the benefit of significantly reducing the size of the information
added to the ID Token from what it would otherwise have been were the
Token Binding ID to be included directly - particularly in the RSA key case.
The recipient MUST verify that the SHA-256 hash
of the Provided Token Binding ID
matches the SHA-256 hash contained in the ID Token.
This 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.
Base64url encoding is base64 encoding using the URL and filename safe alphabet
defined in Section 5 of RFC 4648, with all trailing '='
characters omitted and without the
inclusion of any line breaks, whitespace, or other additional
characters.
The following example demonstrates the JWT Claims Set of an ID 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:
If, in the future, the cryptographic hash of the Token Binding ID
needs to be computed using hash functions other than SHA-256, it is
suggested that additional related JWT confirmation methods members
be defined for that purpose.
For example, a new tbh#S512
(token binding hash using SHA-512) confirmation method member could
be defined by registering it in the the IANA "JWT Confirmation Methods"
registry for JWT
cnf member values established by
.
This specification maps the abstract Token Binding actions specified in
Section 5 (Federation Use Cases) of
Token Binding over HTTP
into concrete actions added to the authentication steps specified in
Section 3 (Authentication) of
OpenID Connect Core 1.0.
Mapping the terminologies used in the two specifications,
the Relying Party is the Token Consumer and
the OpenID Provider is the Token Provider.
For OpenID Connect flows returning the ID Token directly from the Authorization Endpoint --
the Implicit Flow defined in Section 3.2 of
OpenID Connect Core 1.0
and the Hybrid Flow defined in Section 3.3 of OpenID Connect Core 1.0 when using the
code id_token or
code id_token token Response Types --
the actions described in Section 5.5 of
Token Binding over HTTP
are performed as described.
The one difference, as previously described, is that
a cryptographic hash
using the SHA-256 hash function
of the Token Binding ID is instead added to the ID Token,
rather than the Token Binding ID itself.
For OpenID Connect flows returning the ID Token from the Token Endpoint --
the Authorization Code Flow defined in Section 3.1 of
OpenID Connect Core 1.0
and the Hybrid Flow defined in Section 3.3 of OpenID Connect Core 1.0 --
an additional step is necessary beyond those in the previous case.
That step is for the RP to record the Token Binding ID
used when communicating between the User Agent and the RP,
saving it for later use after the Token Response containing the ID Token
returned from the Token Endpoint is received.
This is needed because the ID Token will contain Token Binding information
from the TLS connection between the User Agent and the Relying Party --
not information from the TLS connection between the RP and the Token Endpoint.
In this case, even though the ID Token is returned from the Token Endpoint,
the Token Binding validation steps are performed using
the saved Token Binding ID,
rather than the Token Binding ID
used when communicating with the Token Endpoint.
See for examples demonstrating token bound OpenID
Connect authentication flows.
Many OpenID Connect implementations will be deployed in situations in which
not all participants support Token Binding.
Any of combination of the Relying Party, the OpenID Provider,
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
authentications to proceed in which Token Binding is not supported
or whether to treat the omission of Token Binding at any step as a fatal error.
In dynamic deployment environments in which End Users have choices
of Relying Parties, the OpenID Providers, and/or User Agents,
it is recommended that, for some reasonable period of time during which
Token Binding technology is being adopted, authentications 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.
In more controlled deployment environments where all the
participants in an OpenID Connect authentication
flow are known or expected to support Token
Binding and yet one or more of them does not use it, the
authentication SHOULD be aborted with an error.
For instance, if the RP knows that the OP and the User Agent both
support Token Binding and yet the ID Token received does not contain
Token Binding information, the ID Token should be rejected.
The OP and RP 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.
However, due to the possibility of mismatched support of Token Binding
key parameters across participants, there are potential cases
where all participant support Token Binding yet Token Binding information
is missing from a step in the authentication flow.
Relying Parties supporting Token Binding that also support
OpenID Connect Dynamic Client Registration 1.0
use this metadata parameter to register their support for Token Binding and indicate
the expected JWT Confirmation Method member name used to bind the ID Token:
OPTIONAL.
String value specifying the JWT Confirmation Method member name
(e.g. tbh) that the Relying Party expects when
receiving Token Bound ID Tokens. The presence of this parameter indicates that
the Relying Party supports Token Binding of ID Tokens. If omitted,
the default is that the Relying Party does not support Token Binding of ID Tokens.
OpenID Providers supporting Token Binding that also support
OpenID Connect Discovery 1.0
use this metadata parameter to indicate their support for Token Binding and
specify the JWT Confirmation Methods they support for binding the ID Token.
OPTIONAL.
JSON array containing a list of the JWT Confirmation Method member names
supported by the OP for Token Binding of ID Tokens. The presence of this parameter
indicates that the OpenID Provider supports Token Binding of ID Tokens.
If omitted, the default is that the OpenID Provider does not support Token
Binding of ID Tokens.
OpenID Connect implementations employing Token Binding benefit from the protections
described in Section 7 (Security Considerations) of
The Token Binding Protocol Version 1.0.
Obtaining these protections requires performing the proofs of possession
described in Section 7.4 (Securing Federated Sign-On Protocols) of
Token Binding over HTTP.
Because of the possibility of mismatched Token Binding key parameters type support
across the OP, RP, and User Agent, an indeterminate state can occur when the RP has
negotiated token binding and sends a referred Token Binging to an OP that supports
Token Binging but receives an unbound ID token. How to handle such a situation is
ultimately at the discretion of the RP, however,
Token Binding over HTTP recommends that
providers support all the Token Binding key parameters so the situation should be
uncommon and it is RECOMMENDED that an RP treat that indeterminate state as a fatal error.
ID Tokens are not the only security tokens used by OpenID Connect that can be token bound.
Browsers implementing token binding can transparently token bind browser cookies.
The OAuth 2.0 Token Binding specification
defines mechanisms for token binding of access tokens, refresh tokens, and authorization codes.
There are demonstrable security benefits to using token binding to transform
all of these tokens that were originally bearer tokens
into proof-of-possession tokens protected by token binding.
This specification registers the following confirmation method member
in the IANA "JWT Confirmation Methods" registry
for JWT cnf member values
established by :
Confirmation Method Value: tbh
Confirmation Method Description: Token Binding Hash
Change Controller: IESG
Specification Document(s): of [[ this specification ]]
This specification registers the following client metadata definition
in the IANA "OAuth Dynamic Client Registration Metadata" registry
established by :
Client Metadata Name: id_token_token_binding_cnf
Client Metadata Description:
String value specifying the JWT Confirmation Method member name
the Relying Party expects when receiving Token Bound ID Tokens
Change Controller: OpenID Foundation Extended Authentication Profile (EAP) Working Group
- openid-specs-eap@lists.openid.net
Specification Document(s): of [[ this specification ]]
This specification registers the following metadata definition
in the IANA "OAuth Authorization Server Metadata" registry
TBD Uncomment once registry has been established
established by :
Metadata Name: id_token_token_binding_cnf_values_supported
Metadata Description:
JSON array listing the JWT Confirmation Method member names
supported by the OP for Token Binding of ID Tokens
Change Controller: OpenID Foundation Extended Authentication Profile (EAP) Working Group
- openid-specs-eap@lists.openid.net
Specification Document(s): of [[ this specification ]]
JSON Web Token (JWT)MicrosoftPing IdentityNomura Research Institute, Ltd.Secure Hash Standard (SHS)National Institute of Standards and
TechnologyOAuth 2.0 Form Post Response ModeMicrosoftPing IdentityJSON Web Token ClaimsIANAOAuth ParametersIANA
Examples of token bound OpenID Connect authentication flows are provided in this
section.
Extra line breaks and whitespace has been added to the example figures for
display and formatting purposes.
The End-User using a User Agent makes an unauthenticated request to the Relying Party.
The HTTP request is made over a TLS connection where Token Binding has been negotiated
so the Sec-Token-Binding header is present in the request,
which contains an encoded Token Binding message that has the Token Binding the
User Agent uses with the Relying Party.
The Relying Party redirects the user to the OpenID Provider for
authentication, which is a normal OpenID Connect Authentication Request
asking for an ID Token to be sent using the
Form Post Response Mode. Note, however,
that the response includes the
Include-Referred-Token-Binding-ID
header, which signals to the User Agent that
it should reveal the Token Binding ID used on the TLS connection between
itself and the Relying Party to the OpenID Provider.
The User Agent follows the redirect and delivers the Authentication Request
to the OpenID Provider. The HTTP request is made over a TLS connection where
Token Binding has been negotiated so the "Sec-Token-Binding" header is present
in the request, which contains an encoded Token Binding message. Because
of the Include-Referred-Token-Binding-ID header in
the response that resulted in this request, the Token Binding message
contains two Token Bindings: (1) the provided Token Binding used with the
OpenID Provider, and (2) the referred Token Binding used with the Relying
Party.
After the OpenID Provider authenticates the End-User it issues an
Authorization Response using the From Post Response Mode
where the parameters are encoded as HTML form values that will be
auto-submitted by the User Agent.
The OpenID Provider binds the ID Token to the referred Token Binding
from the header of the Authentication Request using the token binding hash
confirmation method (see the ID Token claims in ).
This binds the ID Token to the TLS connection the
User Agent has with the Relying Party.
Submit This Form