Mutual TLS Profiles for OAuth Clients
draft-ietf-oauth-mtls-01

Abstract

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.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on November 27, 2017.

Copyright Notice

Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

• 1. Introduction
• 1.1. Requirements Notation and Conventions
• 1.2. Terminology
• 2. Mutual TLS for Client Authentication
• 2.1. Mutual TLS Client Authentication to the Token Endpoint
• 2.2. Authorization Server Metadata
• 2.3. Dynamic Client Registration
• 3. Mutual TLS Sender Constrained Resources Access
• 3.1. X.509 Certificate SHA-256 Thumbprint Confirmation Method for JWT
• 3.2. Confirmation Method for Token Introspection
• 4. IANA Considerations
• 4.1. JWT Confirmation Methods Registration
• 4.1.1. Registry Contents
• 4.2. Token Endpoint Authentication Method Registration
• 4.2.1. Registry Contents
• 4.3. OAuth Token Introspection Response Registration
• 4.3.1. Registry Contents
• 4.4. OAuth Dynamic Client Registration Metadata Registration
• 4.4.1. Registry Contents
• 5. Security Considerations
• 5.1. TLS Versions and Best Practices
• 5.2. Client Identity Binding by the Authorization Server
• 6. References
• 6.1. Normative References
• 6.2. Informative References
• Appendix A. Acknowledgements
• Appendix B. Document(s) History
• Authors' Addresses

1. Introduction

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 [RFC6749] 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 [RFC5246] 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 [RFC6750], 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.

1.1. Requirements Notation and Conventions

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 [RFC2119].

1.2. Terminology

This specification uses the following phrases interchangeably: TLS 1.2 [RFC5246] this requires the client to send Client Certificate and Certificate Verify messages during the TLS handshake and for the server to verify these messages.

Transport Layer Security (TLS) Mutual Authentication

Mutual 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

2. Mutual TLS for Client Authentication

2.1. Mutual TLS Client Authentication to the Token Endpoint

The following section defines, as an extension of OAuth 2.0, Section 2.3 [RFC6749], 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 [RFC5246]).

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 [RFC6749]. 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 Section 5.2, the authorization server MUST enforce some method of binding a certificate to a client.

2.2. Authorization Server Metadata

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 [OpenID.Discovery] and [I-D.ietf-oauth-discovery].

2.3. Dynamic Client Registration

This draft adds the following values and metadata parameters to OAuth 2.0 Dynamic Client Registration [RFC7591].

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:

tls_client_auth_subject_dn

An [RFC4514] string representation of the expected subject distinguished name of the certificate the OAuth client will use in mutual TLS authentication.

tls_client_auth_root_dn

An [RFC4514] 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 [RFC7591] should be used.

3. Mutual TLS Sender Constrained Resources Access

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 Section 3.1, or through token introspection as described in Section 3.2. 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 [RFC6750], 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.

3.1. X.509 Certificate SHA-256 Thumbprint Confirmation Method for JWT

When access tokens are represented as a JSON Web Tokens (JWT)[RFC7519], 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 [RFC7800] member x5t#S256 for the X.509 Certificate SHA-256 Thumbprint. The value of the x5t#S256 member is a base64url-encoded SHA-256[SHS] hash (a.k.a. thumbprint or digest) of the DER encoding of the X.509 certificate[RFC5280] (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.

  {
    "iss": "https://server.example.com",
    "sub": "ty.webb@example.com",
    "exp": 1493726400,
    "nbf": 1493722800,
    "cnf":{
      "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
    }
  }
    

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "active": true,
    "iss": "https://server.example.com",
    "sub": "ty.webb@example.com",
    "exp": 1493726400,
    "nbf": 1493722800,
    "cnf":{
      "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
    }
  }