Authenticating Clients Using Mutual TLS

Clients can authenticate to Identity Cloud 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

Identity Cloud 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 Identity Cloud.

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

To Configure Identity Cloud for Mutual TLS Using Public Key Infrastructure

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

  1. If you have not already done so, create an OAuth 2.0 client profile in Identity Cloud.

    For more information, see Client Registration.

  2. Add the subject distinguished name that must appear in the client certificate to be able to authenticate:

    1. In the AM Admin UI, 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.

  3. (Optional) Configure the OAuth 2.0 provider to check whether the certificates presented by the authenticating clients have been revoked:

    1. In the AM Admin UI, 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. Identity Cloud will use this service to check the certificates.

      If not specified, Identity Cloud determines the appropriate URI from the certificate.

    4. (Optional) In the OCSP Responder Certificate field, enter the PEM-encoded certificate that Identity Cloud will use to verify all OCSP responses.

      If not specified, Identity Cloud determines the appropriate certificate from the trusted CA certificates configured in the am.services.oauth2.tls.client.cert.authentication secret ID.

Identity Cloud 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 Identity Cloud".

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 Identity Cloud.

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

  1. 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.

  2. JSON Web Key Set URI (JWKS_uri)

    Identity Cloud 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.

  3. 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 Identity Cloud for Mutual TLS Using Self-Signed X.509 Certificates

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

  1. If you have not already done so, create an OAuth 2.0 client profile in Identity Cloud.

    For more information, see Client Registration.

  2. 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.

  3. Save your changes.

Identity Cloud 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 Identity Cloud".

Providing Client Certificates to Identity Cloud

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

Important

You must configure the web container in which Identity Cloud 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.

  1. 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 Identity Cloud 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
    }
  2. Trusted Headers

    Identity Cloud 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 Identity Cloud runs is not directly able to authenticate the client.

    You must configure the proxy or load balancer to:

    1. Forward the certificate to Identity Cloud in the trusted header.

      Identity Cloud 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 Identity Cloud 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 Admin UI, 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.

Read a different version of :