Authorization Basics

OAuth 2.0 Mutual TLS Client Authentication (mTLS)

Description of the Cloudentity mTLS-based OAuth client authentication flow

mTLS OAuth Client Authentication in a Nutshell

Transport Security Layer (TLS) is a cryptographic protocol that provides security for communication over a network.

Websites or applications that want to utilize TLS must have a TLS certificate installed on the server. Mutual-TLS (mTLS) means that not only the server (in our case, the authorization server, Cloudentity) must have its certificate, but also any client that wants to be authenticated must possess its own certificate.

Using mTLS gives also a possibility to use certificate-bound access tokens. In this case, mTLS ensures that protected resources access is only possible by a legitmate client that uses certificate-bound JSON Web Token and holds a private key that corresponds to the certificate.

Constraints provided by the use of certificate-bound access tokens are sometimes called key confirmation, proof-of-possession, or holder-of-key. It is different to the possession of the bearer token (like in the case of the private_key_jwt client authentication method), where any party that possesses an access token can access associated resources. Having certificate-bound access tokens ensures that only a client that has the private key corresponding to the client’s certificate can access the resources. The binding of an access token to the client’s certificate prevents the resources from being accessed with the use of stolen tokens.

There are two mTLS-based methods that you can use to authenticate your OAuth client with the Cloudentity:

  • tls_auth

  • self_signed_tls_auth

To get to know how to enable mTLS-based client authentication methods, see the configuring mTLS documentation.

tls_auth

This section details prerequisites for the tls_auth client authentication and the tls_auth client authentication process itself.

Client certificates can be issued by Certificate Authorities. CA is a public key infrastructure (PKI) that both the client and the server trust. Clients can use different certificates as long as the client name and issuing certificate authority stay the same. When the client’s certificate is issued by a Certificate Authority, the tls_auth client authentication method is used.

Prerequisites

  • The client was authorized using the authorize endpoint and had received an authorization code.

  • A X.509 certificate was registered and configured for the client in Cloudentity. To know more, see the configuring mTLS documentation.

  • Client registration metadata is configured for the client’s certificate. To know more, see the client registration metadata section.) section.

Procedure

  1. TLS connection between the client and the authorization server is established or reestablished with mutual TLS X.509 certificate authentication (for example, the Client Certificate and Certificate Verify messages are sent during the TLS Handshake).

    1. The client verifies the digital signature of the server’s certificate using the Certificate Authority public key. If the verification is successful, the client sends its certificate to the server.

    2. The server verifies the digital signature of the client’s certificate using the Certificate Authority public key.

  2. The client makes a request for an access token to the token endpoint.

  3. Cloudentity generates an access token and provides it to the client after a successful request validation.

    Result

    Client is authenticated using the tls_auth method.

Self-signed TLS Client Authentication

For the self_singed_tls_auth client authentication to happen, the following procedure must take place.

If there is no Public Key Infrastructure to trust, client certificates can still be used. A client may register a single certificate with the authorization server. During authentication, the authorization server checks if the client’s certificate is valid and if it is still the same certificate that is issued for the client. In this case, the self_signed_tls_auth client authentication method is used.

Prerequisites

  • The client was authorized using the authorize endpoint and had received an authorization code.

  • The client’s X.509 certificates are registered (using the JSON Web Key Sets) or a reference to a trusted source for its X.509 certificates (using jwks_uri) was added to Cloudentity client’s configuration. To know more, see the configuring mTLS documentation.

  • Client registration metadata is configured for the client’s certificate. To know more, see the client registration metadata section.

Procedure

  1. TLS connection between the client and the authorization server is established or reestablished with mutual TLS X.509 certificate authentication (i.e. the Client Certificate and Certificate Verify messages are sent during the TLS Handshake).

    1. The client verifies the digital signature of the Cloudentity certificate. If the verification is successful, the client sends its certificate to the server.

    2. Cloudentity verifies the digital signature of the client’s certificate if it is valid and if it is the certificate that was issued for the client.

  2. The client makes a request for an access token to the token endpoint.

  3. Cloudentity generates an access token and provides it to the client after a successful request validation.

    Result

    Client is authenticated using the self_singed_tls_auth method.

Client Registration Metadata

Client registration metadata is used to convey the subject of the certificate.

For the tls_auth client authentication method, the client must use exactly one of below parameters to convey the subject of the certificate that Cloudentity expects when authenticating the client.

Parameter Description
tls_client_auth_subject_dn String representation of the expected subject distinguished name of the certificate that the OAuth client uses in mTLS authentication.
tls_client_auth_san_dns String that contains the value of an expected dNSName SAN entry in the certificate that the OAuth client uses in mTLS authentication.
tls_client_auth_san_uri String that contains the value of an expected uniformResourceIdentifier SAN entry in the certificate that the OAuth client uses in mTLS authentication.
tls_client_auth_san_ip String representation of an IP address in either dotted decimal notation (for IPv4) or colon-delimited hexadecimal (for IPv6) that is expected to be present as an IP Address SAN entry in the certificate that the OAuth client uses in mTLS authentication.
tls_client_auth_san_email String containing the value of an expected rfc822Name SAN entry in the certificate that the OAuth client will use in mTLS authentication.

For the self_signed_tls_auth client authentication method, the client can use the following method metadata:

Parameter Description
self_signed_tls_client_auth Indicates that client authentication to Cloudentity occurs using mTLS with the client utilizing a self-signed certificate.

When To Use

In general, you should use TLS while transporting any non-public, sensitive user data. It includes authentication data like, for example, passwords or client secrets. TLS prevents this data from being modified or hijacked on its way from the client to the server.

It is recommended to use either the tls_auth or the self_singed_tls_auth method as an additional layer of security built on top of other client authentication methods to achieve the best security for your applications and resources.