This article explains “OAuth 2.0 client authentication”.
In addition to the client authentication methods described in RFC 6749, this article explains methods that utilize a client assertion and a client certificate.
1. Client Authentication Methods
1.1. Token Endpoint
There is an authorization server.
There is a client application that wants to get an access token from the authorization server.
In most cases, access tokens are issued from a token endpoint. Therefore, the authorization server prepares a token endpoint.
The client application sends a token request to the token endpoint to get an access token.
The authorization server returns a token response. The response contains an access token.
1.2. Client Type
The value of the attribute is either public or confidential.
If the client type is confidential,
when the client application accesses the token endpoint,
client authentication is required.
In traditional ways, to begin with, an authorization server generates a pair of client ID and client secret and gives the pair to a client application in advance.
When the client application sends a token request,
it includes the client ID and the client secret in the request. The authorization server checks whether the pair is valid.
The simplest way to include a client ID and a client secret in a token request is to use the
client_secret request parameters.
Another way to include a client ID and a client secret in a token request is to use Basic Authentication (RFC 7617).
To use this method, first, build a string by concatenating a client ID, a colon and a client secret.
Next, encode the string with BASE64 (RFC 4648).
Finally, embed the BASE64 string in the
Authorization header in a token request.
There is an indirect way to prove that a client application has a client secret without including the client secret directly in a token request.
First, prepare some data.
Next, generate a signature for the data using a client secret.
Then, include the data and the signature in a token request.
By verifying the signature, the authorization server can confirm that the client application which has sent the token request has the client secret, whereby the authorization server can authenticate the client.
Signing this JSON is conducted by the way defined in RFC 7515 (JSON Web Signature). As a result of the signing, a JWT (RFC 7519) is generated. In the context of client authentication, the JWT is called client assertion.
The client assertion is included in a token request as the value of the
client_assertion request parameter. At the same time, the
client_assertion_type request parameter needs to be included. The value of the request parameter is a fixed string,
In the client authentication method explained in the previous section, the signature of the client assertion is generated using a shared key (i.e. client secret). On the other hand, there is another way which uses an asymmetric key.
First, prepare a pair of a private key and a public key on the client side.
Then, make the public key accessible from the authorization server in some way or other (e.g. by
jwks_uri client metadata).
Sign the data with the private key.
Make a token request including the generated client assertion as the value of the
client_assertion request parameter.
The authorization server extracts the client assertion from the token request.
Then, it verifies the client assertion with the public key.
There is a specification titled “OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens” (hereinafter, MTLS). “2. Mutual TLS for OAuth Client Authentication” of the specification defines client authentication methods which utilize a client certificate.
To use the client authentication methods defined in MTLS, the connection between a client application and a token endpoint must be Mutual TLS.
In a normal TLS connection, only the server presents its certificate. On the other hand, in a mutual TLS connection, the client presents its certificate, too. As a result, the server receives a client certificate.
The authorization server uses the client certificate for client authentication.
To use a PKI certificate in this client authentication method, a client must register information which identifies the subject of the certificate into the authorization server in advance. Information to identify the subject is one of the following.
The authorization server confirms that the subject of the client certificate sent from a client matches the one registered in advance, whereby the authorization server can authenticate the client.
This client authentication method has a name,
tls_client_auth (MTLS, 2.1.1. PKI Method Metadata Value).
Because a client certificate does not include a client ID for the OAuth 2.0 context, the client cannot be identified only by the client certificate. Therefore, when a certificate-based client authentication method is used, a client ID needs to be included in the request. Basically, the
client_id request parameter is used for the purpose.
Instead of a PKI certificate, a self-signed certificate also can be used for certificate-based client authentication. To use a self-signed certificate, a client must register the certificate into the server in advance.
This client authentication method has a name,
self_signed_tls_client_auth (MTLS, 2.2.1. Self-Signed Method Metadata Value).
The following are metadata related to client authentication.
2.1. Server Metadata
Client authentication methods supported at the token endpoint. An array containing names of client authentication methods such as
Supported signature algorithms for client assertion for client authentication at the token endpoint. An array containing values listed in RFC 7518 (JSON Web Algorithms), 3.1. “alg” (Algorithm) Header Parameter Values for JWS, such as
Client authentication methods supported at the revocation endpoint (RFC 7009). The content is the same as that for
Supported signature algorithms for client assertion for client authentication at the revocation endpoint (RFC 7009). The content is the same as that for
Client authentication methods supported at the introspection endpoint (RFC 7662). The content is the same as that for
Supported signature algorithms for client assertion for client authentication at the introspection endpoint (RFC 7662). The content is the same as that for
2.1.7 Metadata related to Backchannel Authentication Endpoint
In RFC 8141 which lists metadata of an authorization server, metadata for supported client authentication methods (
*_endpoint_auth_methods_supported) and supported signature algorithms for client assertion (
*_endpoint_auth_signing_alg_values_supported) are defined for each endpoint such as a token endpoint, a revocation endpoint and an introspection endpoint. Therefore, during the discussion period to develop the CIBA Core specification, I suggested adding new metadata for the backchannel authentication endpoint ([Issue 102] CIBA: Metadata for client auth at backchannel endpoint).
However, the conclusion was that new metadata for the backchannel authentication endpoint should not be defined and the existing metadata for the token endpoint should be used for the backchannel authentication endpoint, too. The background opinion for this decision is that the old custom which has defined metadata for each endpoint is not good and should not be followed any longer. If you are interested in the discussion, please read “3.2. Client Authentication” in “CIBA, a new authentication/authorization technology in 2019, explained by an implementer”.
2.1.8. Metadata related to Device Authorization Endpoint
OAuth 2.0 Device Authorization Grant (a.k.a. Device Flow), which will become an RFC soon, defines a new endpoint, device authorization endpoint. When a confidential client accesses the endpoint, client authentication is required as required at other endpoints.
The specification does not mention metadata related to client authentication at the device authorization endpoint. So, I posted a question to the OAuth Working Group mailing list to ask whether the working group had a plan to define a rule as to which client authentication method should be used at the device authorization endpoint ([OAUTH-WG] Client Authentication Method at Device Authorization Endpoint).
However, no discussion has been observed so far. It seems there are few people who care about details of client authentication method at the device authorization endpoint. Therefore, the implementation of Authlete decided to use the metadata for the token endpoint as the CIBA specification does.
2.2. Client Metadata
Client authentication method that a client has declared it will use at the token endpoint. For example,
private_key_jwt. If the client type is public, client authentication is not required. In this case,
none should be set.
Signature algorithm of client assertion that a client has declared it will use for client authentication at the token endpoint. One of the algorithms listed in 3.1. “alg” (Algorithm) Header Parameter Values for JWS of RFC 7519 (JSON Web Algorithms), such as
When the client authentication method is
client_secret_jwt, the signature algorithm must be symmetric. To be concrete, it must be one of
HS512. Note that from a security perspective, it is meaningless to choose an algorithm whose entropy is bigger than the entropy of the client secret. The following is the description in “16.19. Symmetric Key Entropy” in OIDC Core.
In Section 10.1 and Section 10.2, keys are derived from the
client_secretvalue. Thus, when used with symmetric signing or encryption operations,
client_secretvalues MUST contain sufficient entropy to generate cryptographically strong keys. Also,
client_secretvalues MUST also contain at least the minimum of number of octets required for MAC keys for the particular algorithm used. So for instance, for
client_secretvalue MUST contain at least 32 octets (and almost certainly SHOULD contain more, since
client_secretvalues are likely to use a restricted alphabet).
On the other hand, when the client authentication method is
private_key_jwt, the signature algorithm must be asymmetric. For instance,
3. Financial-grade API Requirements
3.1. Client Authentication Method
Financial-grade API (FAPI) requires higher security than traditional OAuth 2.0 and OpenID Connect. The specification puts restrictions on client authentication methods.
First, the traditional client authentication methods written in RFC 6749 (
client_secret_post) are prohibited.
Client authentication methods permitted by FAPI Part 1, the security profile for Read-Only API, are the following four.
Client authentication methods permitted by FAPI Part 2 are as follows. Note that
client_secret_jwt is excluded.
The summary table is as follows.
3.2. Client Assertion Signature Algorithm
This requirement affects client authentication methods that utilize client assertion.
3.3. Key Size
The 5th clause in “5.2.2. Authorization Server” in FAPI Part 1 requires that the key size be 2048 bits or more when an RSA algorithm is used for client authentication. Likewise, the 6th clause requires that the key size be 160 bits or more when an elliptic curve algorithm is used for client authentication.
3.4. Other FAPI Requirements
If you are interested in technical details about FAPI, please read “Financial-grade API (FAPI), explained by an implementer”.
Authlete, an implementation of OAuth 2.0 and OpenID Connect,
- supports all the client authentication methods explained in this article,
- supports all the client assertion signature algorithms,
- and is the only implementation in the world (as of July 18, 2019) that is (not just a sandbox but) ready for commercial deployment and has been certified by FAPI certification in both the two categories which are respectively for certificate-based client authentication (MTLS) and assertion-based client authentication (Private Key).
Recently, a lot of services publish APIs, and thanks to them, the world is becoming more convenient. On the other hand, due to improper implementations, we observe security incidents more often than before.
If you put high priority on security in publishing APIs of your services, please consider using Authlete, a certified implementation of Financial-grade API OpenID Provider.
Thanks to its architecture, Authlete can be combined with any end-user authentication mechanism, any API management solution and other API-related technologies without need to replace them.
In addition, Authlete team is eager to implement promising new specifications such as FAPI, CIBA, MTLS, JARM, etc. and thus Authlete can keep your service up-to-date.
Please contact us via the contact form or firstname.lastname@example.org!