OAuth 2.0 client authentication

The Connect2id server supports an array of methods for letting clients authenticate at the token endpoint. Each method has its own security properties. This guide will help you choose the most appropriate method 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 limited 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) which is stored by the server as well as the client.

  • Private key -- The client generates a private key and registers its public part with the Connect2id server. The client then authenticates by signing an assertion (a JWT) or a X.509 client certificate with the private key. The server verifies the assertion by checking its digital signature with the registered public key of the client.

4. Private key authentication is more secure

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

With a private key clients can use a Hardware Security Module (HSM) or a Trusted Platform Module (TPM) to store the key in way that prevents its extraction and thus reduces the risk of client impersonation by a wide margin.

The signed assertions (JWT) also expire, which limits the time window for replay if they get accidentally leaked.

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 serer 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 method and all OAuth 2.0 servers should support it.

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 parameter when registering the client.

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=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

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=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
&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 an HMAC key to secure a JWT assertion. Has stronger security properties than client_secret_basic and client_secret_post because the secret doesn't get passed to the server in plain text, reducing the damage if the token request get accidentally sent over plain HTTP. The JWT expiration limits the time window for replay.

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 algorithms to secure the JWT with HMAC.

5.2 Private key based

5.2.1 private_key_jwt

Based on a private key belonging to the client. 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.

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 RS256, RS384, RS512, PS256, PS384 or PS512 to sign the JWT assertion with a private RSA key (minimum required key length is 2048 bits).

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

5.2.2 self_signed_tls_client_auth

The client authenticates with a X.509 certificate which is submitted to the Connect2id server during the TLS handshake.

The public key of the certificate must be registered with the Connect2id server, in JWK format by value or URL, as with private_key_jwt.

The client certificate can be self-signed (with the private key that matches the registered), or with signed with another key, typically the key of a Certificate Authority (CA).

Note that for a CA-signed certificate no PKI-based validation is done by the Connect2id server, only its public key must match the registered one. Prior PKI-based validation can still be performed in a TLS terminator set up in front of the server.

A benefit of this method is that the issued access token will get 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.

6. Limiting the client authentication methods and JWS algorithms

To limit the client authentication methods that your Connect2id server is going to provide 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.