Part I: OAuth 2.0 Mutual-TLS Client Authentication and Certificate Bound Access Tokens

Gangani Chamika
3 min readApr 21, 2020

--

More recently I worked on implementing a feature to support OAuth 2.0 Mutual-TLS Client Authentication and Certificate Bound Access Tokens for WSO2 Identity Server. So I got the chance to dive into the significance of the MTLS.

It was a cool learning experience, and I’d like to recap and expand on some of the learning I had. First, let me start with the basics.

Mutual TLS is…

Mutual Transport Layer Security is one of the most significant practices which uses client TLS certificate to cryptographically ensure the client information while providing an additional layer of security.

Mutual TLS for OAuth Client Authentication

The requirement of mutual TLS for client authentication is determined by the authorization server based on policy or configuration for the given client. In order to utilize TLS for OAuth client authentication, the TLS connection between the client and the authorization server have been established with mutual-TLS X.509 certificate authentication. That means the client Certificate and Certificate Verify messages are sent during the TLS handshake.

The client includes the client_id parameter for all requests to the authorization server utilizing mutual-TLS client authentication. The presence of the client_id parameter enables the authorization server to easily identify the client independently from the content of the certificate. The authorization server can locate the client configuration using the client identifier and check the certificate presented in the TLS handshake against the expected credentials for that client. The authorization server enforces the binding between the client and the certificate.

If no certificate is presented, or the presented certificate doesn’t match with the expected certificate for the given client_id, the authorization server returns a normal OAuth 2.0 error response per with the invalid_client error code to indicate failed client authentication.

OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens

The connection between a client application and a token endpoint must be Mutual TLS, in order to use the client authentication methods defined in Mutual TLS. Even though only the server presents its certificate, in a normal TLS connection, in a mutual TLS connection, the client presents its certificate. Therefore the server receives a client certificate.

For the OAuth 2.0 context, a client certificate does not include a client ID. Since the authorization server uses the client certificate for client authentication, the client cannot be identified only by the client certificate. Therefore, the client ID is included in the request, when a certificate-based client authentication method is used.

The authorization server is binding the issued access token to the client certificate when mutual TLS is used by the client on connecting to the token endpoint. That binding is done by associating the certificate with the token by embedding the certificate hash in the issued access token directly or through token introspection. This access token binding helps to decouple that binding from the client’s authentication with the authorization server, which enables mutual TLS during protected resource access to serve.

The client makes secured resource requests over a mutually authenticated TLS connection using the same certificate that was used for mutual TLS at the token endpoint, within the scope of a mutual TLS secured resource access flow.

The client certificate that has been used for Mutual TLS by the protected resource is matched with the certificate associated with the access token. If they mismatch, the attempt for accessing the resource be rejected with HTTP 401 error code and the invalid_token error code.

Token Introspection

OAuth 2.0 Token Introspection used a method for a secured resource to query an authorization server about the active condition of an access token and to define meta-data about the token.

The following is an example of an introspection response for an active token with an x5t#SHA256 certificate thumbprint confirmation method. The new introspection response content introduced by the specification is the cnf confirmation method containing the value that is the hash of the client certificate to which the access token is bound.

{
"nbf": 1587292013,
"scope": "openid",
"active": true,
"cnf": {
"x5t#SHA256": "mt3KDY1hofQurloTbphKHCSrTlAGl5MlgXX6Xxj9c_E"
},
"token_type": "Bearer",
"exp": 1587295613,
"iat": 1587292013,
"client_id": "ri_KSgRBZpOdVVYkV1cGEtXEEf8a",
"username": "admin@carbon.super"
}

You can also refer Specification of OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens to have more details on this.

Here we come to the end. I hope you have got something from my Blog. Let’s meet in Part II. Cheers!!!

--

--

Responses (1)