PingAM 8.0.0

Mutual TLS

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

AM also supports the Certificate Bound Access Tokens part of the specification. Learn more in Certificate-bound proof-of-possession.

Mutual TLS using PKI

To authenticate OAuth 2.0 clients with mTLS, the certificate presented by the client must have a subject-distinguished name that exactly matches a value specified in the client profile in AM.

The Certificate Authority (CA) specified in the chain must also be trusted by AM. Configure a secret mapping with the secret label am.services.oauth2.tls.client.cert.authentication to specify the CAs AM trusts.

Configure AM for mutual TLS using PKI

Follow these steps to configure AM to support mutual TLS using PKI:

  1. If you haven’t already done so, create an OAuth 2.0 client profile.

    Learn more in Client application registration.

  2. Set up a secret store in the same realm as the OAuth 2.0 client.

    AM maintains the details of trusted CAs in this secret store.

    You can use an existing secret store or create a new store as follows:

    1. In the AM admin UI, go to Realms > Realm Name > Secret Stores, and click Add Secret Store.

    2. Enter an ID for the secret store (for example, TrustStore), select the store type, complete the required fields, and click Create.

    You might need to configure the credentials for accessing the new store in one of the other configured secret stores. Learn more about configuring secret stores in Secrets, certificates, and keys.

  3. Import the certificates belonging to the CAs you want the instance of AM to trust.

  4. Map the aliases of the imported certificates to the am.services.oauth2.tls.client.cert.authentication secret label:

    • In the AM admin UI, go to Realms > Realm Name > Secret Stores > Store Name > Mappings, and click Add Mapping.

    • In the Secret Label field, select am.services.oauth2.tls.client.cert.authentication.

    • In the Aliases field, enter the alias of the imported CA certificate to trust and click Add.

    • Repeat the previous step to add the aliases of all the CA certificates to trust, and click Create.

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

    • In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Agent Name > Signing and Encryption.

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

      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.

    • Save your changes.

  6. Configure the OAuth 2.0 provider to check whether the certificates presented by the authenticating clients have been revoked:

    • In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced.

    • Enable Check TLS Certificate Revocation Status.

    • In the OCSP Responder URI field, enter the URI of the online certificate status protocol responder service. AM uses this service to check the certificates.

      If not specified, AM determines the appropriate URI from the certificate.

    • 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 label.

AM is now configured to accept CA-signed client certificates for authentication. For information on how to present the certificates when authenticating, refer to Provide 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 exactly matches a certificate specified in the client profile in AM.

Specify the expected self-signed X.509 certificate in the client profile using one of these methods:

  • JSON Web Key Set (JWKS)

    Specify the X.509 certificates in the X.509 Certificate Chain (x5c) attribute of the 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.

  • Store the X.509 certificate as a secret in the secret store.

  • Store the X.509 certificate in the configuration.

    Add the exact content of the X.509 certificate in the client profile.

    Unlike the other methods, only a single certificate can be specified using this method.

Configure AM for Mutual TLS using self-signed X.509 certificates

Follow these steps to configure AM to support mutual TLS using self-signed certificates.

  1. If you haven’t already done so, create an OAuth 2.0 client profile in AM.

  2. To provide the X.509 certificates the client will use to authenticate, go to Applications > OAuth 2.0 > Clients > Client Name > Signing and Encryption, and then perform one of the following steps:

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

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

    • Store the X.509 certificate as a secret in a secret store:

      1. Follow the steps in Secret stores to add the certificate as a secret.

      2. Map this secret to the am.applications.oauth2.client.identifier.mtls.trusted.cert secret label, where identifier is the value of the Secret Label Identifier configured for the client on the Core tab.

    • 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 contents of the X.509 certificate in PEM or DER format.

    OIDC clients must also specify the authentication method they’re using in their client profiles. Learn more in OIDC client authentication.

  3. Save your changes.

AM is now configured to accept self-signed client certificates for authentication. For information on how to present the certificates when authenticating, refer to Provide client certificates to AM.

Provide client certificates to AM

The client can provide its certificate to AM using either standard TLS client certificate authentication or trusted headers.

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 method is preferred because the web container verifies that the client authenticated the TLS session with the private key associated with the certificate.

When you’ve configured 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 the Client credentials grant 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://am.example.com:8443/am/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, so the container in which AM runs can’t directly authenticate the client.

AM can receive certificates in the following formats:

  • DER-encoded.

  • Raw PEM-encoded.

  • DER- or PEM-encoded first, then URL-encoded, for compatibility with the NGINX $ssl_client_escaped_cert variable.

  • DER- or PEM-encoded first, URL-encoded next, then included as a field in a multi-field trusted header, for compatibility with the Envoy x-forwarded-client-cert headers.

You must configure the proxy or load balancer to do the following:

  1. Forward the certificate to AM in the trusted header.

    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 BASE64_ENCODED_CERT for Base64-encoded, URL-encoded certificates in PEM or DER format.

      AM infers the certificate type from the contents of the certificate. For example, a certificate that starts with -----BEGIN CERTIFICATE----- and ends with -----END CERTIFICATE----- is inferred to be a PEM format certificate. A certificate that starts and ends with a colon (:) is inferred to be a DER format certificate.

      NGINX, Google GKE, and AWS provide certificates in this format.

    • Use X_FORWARDED_CLIENT_CERT if the proxy provides the certificate in the X-Forwarded-Client-Cert header.

      Istio/Envoy proxies provide certificates in this way. Find more information in the Envoy documentation.

  2. Strip the trusted header from any incoming requests.

    You must do this because AM has no way of authenticating the contents of this header, so will 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.

    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’s difficult to guess makes this type of attack more difficult.