Authenticating Clients Using Mutual TLS

Clients can authenticate to AM by using mutual TLS (or mTLS) and X.509 certificates that are either self-signed, or that use public key infrastructure (PKI), as per version 12 of the draft OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens specification.

Tip

AM also supports the Certificate Bound Access Tokens part of the specification. For more information, see "Certificate-Bound Proof-of-Possession".

Mutual TLS Using Public Key Infrastructure

This method of authenticating OAuth 2.0 clients requires that the certificate presented by the client contains a subject distinguished name that matches exactly a value specified in the client profile in AM.

The Certificate Authority specified in the chain must also be trusted by AM. You can configure secret mappings with secret ID am.services.oauth2.tls.client.cert.authentication to specify which certificate authorities AM trusts.

To Configure AM for Mutual TLS Using Public Key Infrastructure

Follow the steps in this procedure to configure AM to support mutual TLS using PKI.

If you have not already done so, create an OAuth 2.0 client profile in AM.
For more information, see Client Registration.
Setup a secret store in the same realm as the OAuth 2.0 client. AM maintains the details of trusted certificate authorities in this secret store.
You can use an existing secret store, or create a new store, as follows:
1. In the AM console, go to Realms > Realm Name > Secret Stores, and then click Add Secret Store.
2. Enter an ID for the secret store (for example, TrustStore), select the store type, complete the required fields, and then click Create.
  Note
  You may need to configure the credentials for accessing the new store in one of the other configured secret stores.
  For more information on configuring secret stores, see Configuring Secrets, Certificates, and Keys.
Import the certificates belonging to the certificate authorities you want the instance of AM to trust.
Map the aliases of the imported certificates to the am.services.oauth2.tls.client.cert.authentication secret ID:
1. In the AM console, go to Realms > Realm Name > Secret Stores > Store Name > Mappings, and then click Add Mapping.
2. In the Secret ID field, select am.services.oauth2.tls.client.cert.authentication.
3. In the Aliases field, enter the aliases of the imported CA certificate to trust, and then click the Add Alias () button.
4. Repeat the previous step to add the aliases of all the CA certificates to trust, and then click Create.
Add the subject distinguished name that must appear in the client certificate to be able to authenticate:
1. In the AM console, go to Realms > Realm Name > Applications > OAuth 2.0 > Agent Name > Signing and Encryption.
2. In the mTLS Subject DN field, enter the distinguished name that must exactly match the subject field in the client certificate. For example, CN=myOauth2Client.
  Note
  If this field is left empty, the default value that must be found in a CA-signed client certificate is CN=Client ID. For example, CN=myMTLSClient.
3. Save your changes.
(Optional) Configure the OAuth 2.0 provider to check whether the certificates presented by the authenticating clients have been revoked:
1. In the AM console, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced.
2. Enable Check TLS Certificate Revocation Status.
3. (Optional) In the OCSP Responder URI field, enter the URI of the online certificate status protocol responder service. AM will use this service to check the certificates.
  If not specified, AM determines the appropriate URI from the certificate.
4. (Optional) In the OCSP Responder Certificate field, enter the PEM-encoded certificate that AM will use to verify all OCSP responses.
  If not specified, AM determines the appropriate certificate from the trusted CA certificates configured in the am.services.oauth2.tls.client.cert.authentication secret ID.

AM is now configured to accept CA-signed client certificate for authentication. For information on how to present the certificates when authenticating, see "Providing Client Certificates to AM".

Mutual TLS Using Self-Signed X.509 Certificates

This method of authenticating OAuth 2.0 clients requires that the self-signed X.509 certificate presented by the client matches exactly a certificate specified in the client profile in AM.

You can specify the expected self-signed X.509 certificate in the client profile using one of the following methods:

JSON Web Key Set (JWKS)
Specify the X.509 certificates in the X.509 Certificate Chain (x5c) attribute of the one or more JSON Web Keys specified in the set.
JSON Web Key Set URI (JWKS_uri)
AM periodically retrieves the JWKS from the specified URI, and uses the certificates provided in the X.509 Certificate Chain (x5c) attribute to verify the client certificate.
X.509
Add content of the X.509 certificate as-is into the client profile.
Unlike the other methods, only a single certificate can be specified using this method.

To Configure AM for Mutual TLS Using Self-Signed X.509 Certificates

Follow the steps in this procedure to configure AM to support mutual TLS using self-signed certificates.

If you have not already done so, create an OAuth 2.0 client profile in AM.
For more information, see Client Registration.
To provide the X.509 certificates the client will use to authenticate, navigate to Applications > OAuth 2.0 > Agent Name > Signing and Encryption, and then perform one of the following steps:
- To use a JSON Web Key Set (JWKS) to specify the certificates:
  1. Set the Public key selector property to JWKs.
  2. Enter the contents of the JWKS in the Json Web Key property.
- To use a JSON Web Key Set URI (JWKS_uri) to specify the certificates:
  1. Set the Public key selector property to JWKs_uri.
  2. Enter the JWKS URI in the Json Web Key URI property.
- To use the contents of an X.509 certificate:
  1. Set the Public key selector property to X509.
  2. In the mTLS Self-Signed Certificate field, enter the content of the X.509 certificate, which must be in PEM format.
    Tip
    You can choose to include or exclude the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- labels.
Tip
OpenID Connect clients must also specify the authentication method they are using in their client profiles. See OpenID Connect Client Authentication.
Save your changes.

AM is now configured to accept self-signed client certificate for authentication. For information on how to present the certificates when authenticating, see"Providing Client Certificates to AM".

Providing Client Certificates to AM

The client can provide its certificate to AM by using either of methods below.

Important

You must configure the web container in which AM runs to use TLS connections, and to request and accept client certificates.

Consult the documentation for your web container to determine the appropriate actions to take.

Standard TLS Client Certificate Authentication
The client provides its certificates in the standard servlet client certificate attribute.
This is the preferred method, as the web container will verify that the client authenticated the TLS session with the private key associated with the certificate.
After configuring AM to accept client certificates, the client can authenticate to the OAuth 2.0 access_token endpoint using one of the X.509 certificates registered in the client.
Any of the OAuth 2.0 grant flows that makes a call to the access_token endpoint can authenticate clients using X.509 certificates. The following example uses grant_type=client_credentials, and attaches the client certificates to the request:
```
$ curl --request POST \
--data "client_id=myClient" \
--data "grant_type=client_credentials" \
--data "scope=write" \
--data "response_type=token" \
--cert "myClientCertificate.pem" \
--key "myClientCertificate.key.pem" \
"https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token"
{
  "access_token": "sbQZuveFumUDV5R1vVBl6QAGNB8",
  "scope": "write",
  "token_type": "Bearer",
  "expires_in": 3599
}
```
Trusted Headers
AM receives the certificates in a configured, trusted HTTP header.
This method is intended for cases where TLS is being terminated at a reverse proxy or load balancer, and therefore the container in which AM runs is not directly able to authenticate the client.
You must configure the proxy or load balancer to:
1. Forward the certificate to AM in the trusted header.
  AM supports receiving certificates in the following formats:
  - Raw PEM-encoded.
  - PEM-encoded first, then URL-encoded, for compatibility with the NGINX $ssl_client_escaped_cert variable.
  - PEM-encoded first, URL-encoded next, and then included as a field in a multi-field trusted header, for compatibility with the Envoy x-forwarded-client-cert headers.
  To specify the format of the trusted header, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced, and choose the appropriate value in the TLS Client Certificate Header Format drop-down list:
  - Use URLENCODED_PEM for raw PEM and NGINX-like URL-encoded formats.
  - Use X_FORWARDED_CLIENT_CERT for the Envoy-like format.
2. Strip the trusted header from any incoming requests. This is because AM has no way of authenticating the contents of this header, and so would trust whatever is present.
To specify the name of the trusted header, in the AM console, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced, and enter the header name in the Trusted TLS Client Certificate Header property.
Tip
It is recommended to specify a strong, random name for the trusted header. A misconfigured proxy or load balancer could let an attacker send malicious header values. A trusted header name that is difficult to guess makes this type of attack more difficult.