OAuth 2.0 client authentication

The Connect2id server supports a number of methods for letting confidential clients authenticate at the token endpoint. Each method has its own security properties. This guide can 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. Traditional web applications with a backend server fall into this category.

Public clients on the other hand do not have this capability, so they don't authenticate at the token endpoint. That's typically native applications running on a user's device or computer, or browser based (JavaScript) applications.

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

2. Why do OAuth 2.0 clients authenticate?

Clients get authenticated by the Connect2id server in order to ensure the requested tokens get issued to a legitimate client and not some other, potentially malicious, party. Also, for audit purposes.

Public clients that don't get authenticated may for this reason only get issued with tokens that have limited scopes, subject to Authorisation Server / OpenID Provider policy.

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

The credential a client uses to authenticate is essentially one of these two types:

  • Shared secret -- The Connect2id server issues the client with a secret (password) that is stored on the server side and must also be stored in the client.

  • Private key -- The client generates a private key and registers its matching public counterpart with the Connect2id server. The client then authenticates by signing an assertion (typically a JSON Web Token, or JWT) with the private key. The server verifies the assertion by checking its digital signature with the public key the client has registered.

4. Private key authentication is more secure

Of the two methods the private key based is the one which has stronger security properties.

With a private key clients may employ a Hardware Security Module](https://en.wikipedia.org/wiki/Hardware_security_module) (HSM) or a Trusted Platform Module (TPM) to store the key in way that prevents its extraction and thus the risk of impersonation.

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 a bit in 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 must 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 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, which reduces potential damage if the token request is sent out over plain HTTP. Also, 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 which is generated on the client side. 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 allows for 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 stock 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

The 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 doesn't allow 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 of course also be limited in your developer portal.

7. Developer resources

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