OAuth 2.0 client authentication

The Connect2id server supports all standard methods for authenticating clients at the token endpoint, specified in the core OAuth 2.0 spec and various extensions. Each method has its own security properties. This guide will help you choose the most appropriate one for your client application. But first some basics.

1. Confidential vs public OAuth 2.0 clients

Confidential clients are those that have the capability to store secrets which cannot be accessed by the end-user or other parties. Traditional web applications with a backend server fall into this category.

Public clients on the other hand do not have this capability, so they cannot be reasonably authenticated at the token endpoint. Examples are native applications running on a user's device or computer, and browser based (JavaScript) applications.

The two client types are defined in the OAuth 2.0 framework spec (RFC 6749).

2. Why authenticate an OAuth 2.0 client?

Client authentication ensures the tokens get issued to a legitimate client and not some other, potentially malicious, party.

Public clients, which don't get authenticated, may for this reason only get issued with tokens that have a restricted scope.

3. The two fundamental methods for client authentication: shared secret vs private key

The credential a client uses to authenticate falls into one of these two types:

  • Shared secret -- The Connect2id server issues the client with a secret (password) that is stored by the server as well as the client.

  • Private key -- The client generates a private RSA or EC key and stores it securely. The client then authenticates by signing an assertion (a JWT) with the private key, or by using the private key in a client X.509 certificate based authentication during the TLS handshake of the HTTPS connection.

4. Private key based authentication is more secure

Of the two methods the one based on a private key has stronger security properties.

  • A client can store the private key in a Hardware Security Module (HSM) or a Trusted Platform Module (TPM) where the signing is performed internally, within the module, and extraction of the stored keys is not possible. This can reduce the risk of client impersonation significantly.

  • The authorisation server doesn't keep any client-related credentials, limiting potential exposure.

  • The signed assertions (JWT) expire, limiting the time window for replay if they get accidentally leaked. Client certificates can also be made to expire quickly.

  • Finally, the issued tokens can be bound to the private key, enabling resource servers to require the client to prove its key possession when the token is submitted, thus upgrading the security of the OAuth 2.0 bearer tokens.

5. Supported client authentication methods

The Connect2id server supports the following standard methods for client authentication. Use their designations when you register a client to set the preferred method.

For an up-to-date list of the supported client authentication methods check the Connect2id server datasheet.

5.1 Shared secret based

5.1.1 client_secret_basic

This is essentially basic authentication, tweaked for OAuth 2.0 by applying additional "application/x-www-form-urlencoded" encoding to the client_id and client_secret. This is the simplest but also the least secure method.

The Connect2id server will automatically generate a secret for the client during registration. To let the client determine the secret use the custom preferred_client_secret registration parameter.

The client authentication is passed in the Authorization HTTP header.

POST /token HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

grant_type=authorization_code
&code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4

5.1.2 client_secret_post

Differs from client_secret_basic in that the credentials are passed in the request body as form parameters.

POST /token HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4
&client_id=s6BhdRkqt3
&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw

5.1.3 client_secret_jwt

Also uses a client secret, but this time the secret is used as a key to compute a hash-based message authentication code (HMAC) for a JWT assertion. Has stronger security properties than client_secret_basic and client_secret_post because the secret itself doesn't get transmitted to the server, reducing the damage if the token request gets accidentally sent over plain HTTP. The JWT expiration limits the time window for replay.

The JWT contains the following claims:

  • iss and sub set to the client_id.
  • aud set to the token endpoint URL.
  • jti set to a unique identifier for the JWT.
  • exp set the JWT expiration time.
  • iat set to the JWT issue time (optional).

Example JWT claims:

{
  "iss" : "oe7aiz60",
  "sub" : "oe7aiz60",
  "aud" : "https://demo.c2id.com/token",
  "exp" : 1453021544,
  "jti" : "Eefaevo0"
}

The client authenticates with client_secret_jwt by including the client_assertion_type parameter set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer and the client_assertion parameter set to the serialised JWT.

POST /token HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.eyJpc3Mi...

The Connect2id server supports the standard HS256, HS384 and HS512 JWS algorithms for JWTs secured with HMAC.

When registering for client_secret_jwt the preferred JWS algorithm should be set.

The client_secret_jwt method is specified in OpenID Connect Core 1.0, section 9 and in RFC 7523, section 2.2.

5.2 Private key based

5.2.1 private_key_jwt

Based on a private RSA or EC key belonging to the client to sign a JWT assertion. The matching public key must be registered in JSON Web Key (JWK) format with the Connect2id server, either by value or by URL. The registration by URL enables key-rollover without the need to update the client registration.

The JWT contains the following claims:

  • iss and sub set to the client_id.
  • aud set to the token endpoint URL.
  • jti set to a unique identifier for the JWT.
  • exp set the JWT expiration time.
  • iat set to the JWT issue time (optional).

Example JWT claims:

{
  "iss" : "oe7aiz60",
  "sub" : "oe7aiz60",
  "aud" : "https://demo.c2id.com/token",
  "exp" : 1453021544,
  "jti" : "Eefaevo0"
}

The client authenticates with private_key_jwt by including the client_assertion_type parameter set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer and the client_assertion parameter set to the serialised JWT.

POST /token HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.eyJpc3Mi...

The Connect2id server supports RSA and EC keys:

  • Use the RS256, RS384, RS512, PS256, PS384 or PS512 JWS algorithm to sign the JWT assertion with a private RSA key (minimum required key length is 2048 bits).

  • Use ES256, ES384 or ES512 JWS algorithm to sign the JWT assertion with a private EC key (requires matching curve).

When registering for private_key_jwt the preferred JWS algorithm should be set.

The private_key_jwt method is specified in OpenID Connect Core 1.0, section 9 and in RFC 7523, section 2.2.

5.2.2 tls_client_auth

The client authenticates with an X.509 certificate submitted to the Connect2id server during the TLS handshake. The client certificate must be issued by a trusted Certificate Authority (CA) and will typically be validated by a dedicated TLS termination proxy in front of the server.

When registering for tls_client_auth the expected subject DN of the certificate must be set.

Note, the client must include its client_id in the HTTP request body to identify itself.

POST /token HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4
&client_id=s6BhdRkqt3

A benefit of this method is that the issued access token is bound to the client certificate, which fixes the bearer weakness of regular OAuth 2.0 access tokens. This client authentication method and the binding are specified in the mTLS OAuth 2.0 extension (RFC 8705).

5.2.3 self_signed_tls_client_auth

Similarly to the tls_client_auth method the client authenticates with a X.509 certificate submitted to the Connect2id server during the TLS handshake, but the certificate can be self-signed (self-issued) and thus no CA and X.509 based public key infrastructure (PKIX) is required. The TLS termination proxy is configured to accept self-signed certificates.

The validity of the client certificate is established by the client having its public key of the certificate registered with the Connect2id server, in JWK format by value or URL, as with private_key_jwt.

The client must include its client_id in the HTTP request body to identify itself.

POST /token HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4
&client_id=s6BhdRkqt3

The issued access token will get bound to the client certificate, addressing the bearer weakness of regular OAuth 2.0 access tokens. This client authentication method and the binding are specified in the mTLS OAuth 2.0 extension (RFC 8705).

6. Limiting the accepted client authentication methods and JWS algorithms

To limit the client authentication methods accepted by a Connect2id server deployment edit the op.token.authMethods configuration setting.

For example, if your policy prohibits public OAuth 2.0 clients remove the none method from the list.

To limit the available JWS algorithms for the JWT assertions edit the op.token.authJWSAlgs configuration setting.

The available authentication methods and algorithms can also be limited in your developer portal which manages requests to the client registration endpoint.

7. Developer resources

The OAuth 2.0 / OpenID Connect SDK for Java that Connect2id maintains provides support for all standard client authentication methods.