Mutual TLS Profiles for OAuth ClientsPing Identitybrian.d.campbell@gmail.comPing Identityve7jtb@ve7jtb.comhttp://www.thread-safe.com/Nomura Research Instituten-sakimura@nri.co.jphttps://nat.sakimura.org/YES Europe AGtorsten@lodderstedt.net
Security
OAuth Working GroupOAuth
This document describes Transport Layer Security (TLS) mutual authentication
using X.509 certificates as a mechanism for both OAuth client authentication
to the token endpoint as well as for sender constrained access to
OAuth protected resources.
This document describes Transport Layer Security (TLS) mutual authentication
using X.509 certificates as a mechanism for both OAuth client authentication
to the token endpoint as well as for sender constrained access to
OAuth protected resources.
The OAuth 2.0 Authorization Framework
defines a shared secret method of client authentication but also
allows for the definition and use of additional client authentication mechanisms
when interacting with the authorization server's token endpoint.
This document describes an additional mechanism of client authentication utilizing
mutual TLS certificate-based authentication, which provides
better security characteristics than shared secrets.
Mutual TLS sender constrained access to protected resources ensures that
only the party in possession of the
private key corresponding to the certificate can utilize the access token to get
access to the associated resources. Such a constraint is unlike the case of the
basic bearer token described in , where any party in
possession of the access token can use it to access the associated resources.
Mutual TLS sender constrained access binds the access token to the client's certificate
thus preventing the use of stolen access tokens or replay of access tokens
by unauthorized parties.
Mutual TLS sender constrained access tokens and mutual TLS client authentication
are distinct mechanisms that don't necessarily need to be deployed together.
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 following phrases interchangeably:
Transport Layer Security (TLS) Mutual AuthenticationMutual TLS
These phrases all refer to the process whereby a client uses it's X.509 certificate
to authenticate itself with a server when negotiating a TLS session.
In TLS 1.2 this requires the client to send
Client Certificate and Certificate Verify messages during the TLS handshake and
for the server to verify these messages.
The following section defines, as an extension of
OAuth 2.0, Section 2.3, the use of mutual TLS X.509 client certificates as client credentials.
The requirement of mutual TLS for client authentications is determined by the authorization server
based on policy or configuration for the given client (regardless of whether the client was dynamically
registered or statically configured or otherwise established).
OAuth 2.0 requires that access token requests by the client
to the token endpoint use TLS. In order to utilize TLS for client authentication, the TLS
connection MUST have been established or reestablished with mutual X.509 certificate authentication
(i.e. the Client Certificate and Certificate Verify messages are sent during the TLS Handshake
).
For all access token requests to the token endpoint, regardless of the grant type used,
the client MUST include the
client_id parameter,
described in OAuth 2.0, Section 2.2.
The presence of the client_id
parameter enables the authorization server to easily identify the
client independently from the content of the certificate and allows for trust
models to vary as appropriate for a given deployment. The authorization server
can locate the client configuration by the client identifier and check the certificate
presented in the TLS Handshake against the expected credentials for that client.
As described in , the authorization server MUST enforce some
method of binding a certificate to a client.
tls_client_auth is used as a new value of the
token_endpoint_auth_methods_supported metadata parameter
to indicate server support for mutual TLS as a client authentication method
in authorization server metadata such as
and .
This draft adds the following values and metadata parameters
to OAuth 2.0 Dynamic Client Registration.
The value tls_client_auth is used to indicate the client's
intention to use mutual TLS as an authentication method to the
token endpoint for the token_endpoint_auth_method
client metadata field.
For authorization servers that associate certificates with clients using subject
information in the certificate, the following two new metadata parameters
can be used:
An string representation of the expected subject distinguished
name of the certificate the OAuth client will use in mutual TLS authentication.
An string representation of a distinguished name that can
optionally be used to constrain, for the given client, the expected distinguished name
of the root issuer of the client certificate.
For authorization servers that use the key or
full certificate to associate clients with certificates, the existing
jwks_uri or jwks
metadata parameters from should be used.
When mutual TLS is used at the token endpoint,
the authorization server is able to bind the issued access token to the client certificate.
Such a binding is accomplished by associating the certificate with the token in
a way that can be accessed by the protected resource, such as embedding the certificate
hash in the issued access token directly, using the syntax described in ,
or through token introspection as described in .
Other methods of associating a certificate with an access token are possible,
per agreement by the authorization server and the protected resource, but are
beyond the scope of this specification.
The client makes protected resource requests as described in ,
however, those requests MUST be made over a mutually authenticated TLS connection
using the same certificate that was used for mutual TLS at the token endpoint.
The protected resource MUST obtain the client certificate
used for mutual TLS authentication
and MUST verify that the that certificate matches the
certificate associated with the access token. If they do not match,
the resource access attempt MUST be rejected with an error.
When access tokens are represented as a JSON Web Tokens (JWT),
the certificate hash information SHOULD be represented using
the x5t#S256 confirmation method member defined herein.
To represent the hash of a certificate in a JWT,
this specification defines the new JWT Confirmation Method
RFC 7800
member x5t#S256 for the X.509 Certificate SHA-256 Thumbprint.
The value of the x5t#S256 member is
a base64url-encoded SHA-256 hash (a.k.a. thumbprint or digest)
of the DER encoding of the X.509 certificate
(note that certificate
thumbprints are also sometimes also known as certificate fingerprints).
The following is an example of a JWT payload containing an x5t#S256 certificate thumbprint
confirmation method.
OAuth 2.0 Token Introspection 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 mutual TLS sender constrained access token, the hash of the
certificate 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
certificate SHA-256 thumbprint confirmation method, described in
, as a top-level member of the introspection response JSON.
The protected resource compares
that certificate hash to a hash of the client certificate used for
mutual TLS authentication
and rejects the request, if they do not match.
Proof-of-Possession Key Semantics for JSON Web Tokens defined the
cnf (confirmation) claim, which enables
confirmation key information to be carried in a JWT.
However, the same proof-of-possession semantics are also useful for introspected access tokens
whereby the protected resource obtains the confirmation key data as meta-information
of a token introspection response and uses that information in verifying proof-of-possession.
Therefore this specification defines and registers proof-of-possession semantics for
OAuth 2.0 Token Introspection using the cnf
structure.
When included as a top-level member of an OAuth token introspection response, cnf
has the same semantics and format as the the claim of the same name defined in .
While this specification only explicitly uses the x5t#S256
confirmation method member, it needed to define and register the higher level cnf
structure as an introspection response member in order to define and use its more specific
x5t#S256 confirmation method.
The following is an example of an introspection response for an active token with
an x5t#S256 certificate thumbprint
confirmation method.
This specification requests registration of the following value
in the IANA "JWT Confirmation Methods" registry
for JWT cnf member values
established by .
Confirmation Method Value: x5t#S256Confirmation Method Description: X.509 Certificate SHA-256 ThumbprintChange Controller: IESGSpecification Document(s): of [[ this specification ]]
This specification requests registration of the following value
in the IANA "OAuth Token Endpoint Authentication Methods" registry
established by .
Token Endpoint Authentication Method Name: tls_client_authChange Controller: IESGSpecification Document(s): of [[ this specification ]]
This specification requests registration of the following value
in the IANA "OAuth Token Introspection Response" registry
established by .
Claim Name: cnfClaim Description: ConfirmationChange Controller: IESGSpecification Document(s): of [[ this specification ]]
This specification requests registration of the following client metadata definitions
in the IANA "OAuth Dynamic Client Registration Metadata" registry
established by :
Client Metadata Name: tls_client_auth_subject_dn
Client Metadata Description:
String value specifying the expected subject distinguished name of the
client certificate.
Change Controller: IESG
Specification Document(s): of [[ this specification ]]
Client Metadata Name: tls_client_auth_root_dn
Client Metadata Description:
String value specifying the expected distinguished name of the root
issuer of the client certificate
Change Controller: IESG
Specification Document(s): of [[ this specification ]]
TLS 1.2 is cited in this document because,
at the time of writing, it is latest version that is widely deployed.
However, this document is applicable with other TLS versions supporting
certificate-based client authentication.
Implementation security considerations for TLS, including version recommendations,
can be found in
Recommendations for Secure Use of Transport Layer Security (TLS)
and Datagram Transport Layer Security (DTLS).
No specific method of binding a certificate to a client identifier
at the token endpoint is prescribed by
this document. However, some method MUST be employed so that, in addition to
proving possession of the private key corresponding to the certificate, the client
identity is also bound to the certificate. One such binding would be to configure for the
client a value that the certificate must contain in the subject field
and possibly the expected trust anchor.
An alternative method would be to configure a public key for the client directly that
would have to match the subject public key info of the certificate.
Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) are widely used to protect data exchanged over application protocols such as HTTP, SMTP, IMAP, POP, SIP, and XMPP. Over the last
few years, several serious attacks on TLS have emerged, including attacks on its most commonly used cipher suites and their modes of operation. This document provides recommendations for improving the
security of deployed services that use TLS and DTLS. The recommendations are applicable to the majority of use cases.
Secure Hash Standard (SHS)National Institute of Standards and
TechnologyOAuth ParametersIANAJSON Web Token ClaimsIANAOpenID Connect Discovery 1.0Nomura Research Institute, Ltd.Ping IdentityMicrosoftIllumila
Scott "not Tomlinson" Tomilson and Matt Peterson were involved in
design and development work on a mutual TLS OAuth client authentication
implementation that informed some of the content of this document.
Additionally, the authors would like to thank the following people for
their input and contributions to the specification:
Sergey Beryozkin,
Vladimir Dzhuvinov,
Samuel Erdtman,
Phil Hunt,
Sean Leonard,
Kepeng Li,
James Manger,
Jim Manico,
Nov Matake,
Sascha Preibisch,
Justin Richer,
Dave Tonge,
and
Hannes Tschofenig.
[[ to be removed by the RFC Editor before publication as an RFC ]]
draft-ietf-oauth-mtls-01
Added more explicit details of using RFC 7662 token introspection with mutual TLS sender constrained access tokens.Added an IANA OAuth Token Introspection Response Registration request for "cnf".Specify that tls_client_auth_subject_dn and tls_client_auth_root_dn are RFC 4514 String Representation of Distinguished Names.Changed tls_client_auth_issuer_dn to tls_client_auth_root_dn.Changed the text in the to not be specific about using a hash of the cert.Changed the abbreviated title to 'OAuth Mutual TLS' (previously was the acronym MTLSPOC).
draft-ietf-oauth-mtls-00
Created the initial working group version from draft-campbell-oauth-mtls
draft-campbell-oauth-mtls-01
Fix some typos.Add to the acknowledgements list.
draft-campbell-oauth-mtls-00
Add a Mutual TLS sender constrained protected resource access method
and a x5t#S256 cnf method for JWT access tokens
(concepts taken in part from draft-sakimura-oauth-jpop-04).
Fixed "token_endpoint_auth_methods_supported" to "token_endpoint_auth_method" for client metadata.
Add "tls_client_auth_subject_dn" and "tls_client_auth_issuer_dn" client metadata parameters and
mention using "jwks_uri" or "jwks".
Say that the authentication method is determined by client policy regardless of whether the client
was dynamically registered or statically configured.
Expand acknowledgements to those that participated in discussions around
draft-campbell-oauth-tls-client-auth-00
Add Nat Sakimura and Torsten Lodderstedt to the author list.
draft-campbell-oauth-tls-client-auth-00
Initial draft.