Skip to content

Add Support for tls_client_auth (mTLS Authentication)

Jump to bottom
dreed12 edited this page Jun 22, 2023 · 2 revisions

Overview

tls_client_auth is one of the FAPI compliant OAuth 2.0 client authentication methods.

To support this method of authentication, Identity Cloud needs to know which certificate authorities to trust for this purpose.

Configuring Identity Cloud

Identity Cloud supports configuring Environment Secrets and Variables (ESVs): Introduction to ESVs, which can be leveraged for the purposes of mutual TLS.

Create an ESV secret

The trusted certificate authority certificates need to be configured as a single ESV secret. The file must be in PEM format, but it can contain multiple certificates. The full certificate chain that has signed the client certificate must be present.

Once the trusted set of certificates has been determined and concatenated into a PEM truststore, then the secret can be created in the Identity Cloud tenant as an ESV. PEM format secrets must be created via the API (the UI only supports generic secrets) as explained here: Manage ESVs using the API.

Example curl command

Variables:

  • ${access_token} - an OAuth 2.0 access_token with scope: fr:idc:esv:update or fr:idc:esv:*; see Authenticate to Identity Cloud REST API with access token for details on how to obtain an access token.
  • ${base64_enc_secret} - a base64 encoded PEM, which contains the certificate chains to trust.
  • ${tenant_env_fqdn} - the FQDN of the Identity Cloud tenant you are configuring.
  • ${secret_name} - the name of the secret to create (esv-am-oauth2-ca-certs).

Curl command:

curl -X PUT -H "Authorization: Bearer ${access_token}" \
  -H 'Content-Type: application/json' \
  -H 'Accept-API-Version: protocol=1.0;resource=1.0' \
  --data-raw "{ \"encoding\": \"pem\", \"useInPlaceholders\": false, \"valueBase64\": \"${base64_enc_secret}\" }" \
  https://${tenant_env_fqdn}/environment/secrets/${secret_name}

Configure the initializer

Once the ESV secret has been created, then the initializer can be configured to make Identity Cloud use the secret for the purpose of OAuth 2.0 tls_client_auth trust.

This is done by setting the following environment variables within the initializer container:

IDENTITY.GOOGLE_SECRET_STORE_NAME: ESV
IDENTITY.GOOGLE_SECRET_STORE_OAUTH2_CA_CERTS_SECRET_NAME: esv-am-oauth2-ca-certs

NOTE: the store name ESV is the name of the store used for ESVs in Identity Cloud; the secret name must match the name of the secret created in the previous step.

Run the initializer

Once the initializer configuration has been updated, you can run the initializer to apply the configuration.

Verify the secret has been mapped

  • Log in to the Identity Cloud admin UI.
  • Navigate to the Access Management native console.
  • Select the realm that has been configured by the initializer (typically: alpha).
  • Select Secret Stores > ESV > Mappings.

The store should contain a mapping for the am.services.oauth2.tls.client.cert.authentication secret id to the name of the secret created in the ESV as illustrated below: fidc-tls-client-auth-secret-mapping

Clone this wiki locally