Secure authentication to data stores

By default, AM authenticates to external data stores using simple (username/password) authentication. To enhance security, you can configure mutual TLS (mTLS) authentication. This lets AM and the DS server authenticate each other using trusted certificates.

For additional security, you should periodically rotate the certificates, as described in Map and rotate secrets.

When AM uses certificates to authenticate to external data stores, if the active certificate expires, the TLS handshake will be unsuccessful. In this case, AM won’t be able to establish the connection or process any requests to that data store.

Having a long certificate expiry time can expose your deployment to attacks, for example, in cases of certificate theft.

You must implement best security practices to balance the requirement of reasonable certificate expiry times with the need for an active certificate for authentication.
Due to a known issue in OpenJDK, you can’t configure mTLS authentication to data stores if you’re using Java version 11.0.2. If you’re using this Java version and attempt to authenticate with mTLS, the connection fails and the DS server generates the following error in the ldap-access.audit.json log:
```
"failureReason":"The SASL EXTERNAL bind request could not be processed because the client did not present a certificate
chain during SSL/TLS negotiation"
```
AM then enters an invalid state.

To work around this issue, upgrade to Java 11.0.3 or higher, or authenticate using simple authentication.

This topic describes how to configure mTLS authentication between AM and the following external data stores:

Identity stores
Configuration stores
Policy and application stores
CTS stores
UMA stores

mTLS for identity stores

You can configure mTLS authentication to the following identity stores:

ForgeRock Directory Services
ForgeRock IAM Directory Server

Configuring mTLS authentication to an identity store requires configuration changes on the directory server and on AM. The DS configuration is the same, regardless of which DS type you’re using.

Configure DS for mTLS
Configure mTLS between AM and the identity store

Configure DS for mTLS

This section assumes you installed DS for platform identities and configured DS for identity data.

By default, the credentials of the identity bind account you created when you installed DS are:

Bind DN: uid=am-identity-bind-account,ou=admins,ou=identities.
Password: The password you set with am-identity-store/amIdentityStoreAdminPassword.

Adjust the following steps if you used different credentials.

When the DS server is running, create a keystore and TLS key pair for the AM identity bind account. This command creates the keypair in a new keystore in the default AM security folder:
```
$ ./dskeymgr create-tls-key-pair \
--deploymentId $DEPLOYMENT_ID \
--deploymentIdPassword <password> \
--keyStoreFile /path/to/am/security/keystores/mtls-keystore \
--keyStorePassword:file /path/to/am/security/mtls-keystore.pin \
--alias am-identities-sa-cert \
--subjectDn "uid=am-identity-bind-account,ou=admins,ou=identities"
```
- The subjectDn must match the subject DN of the identity bind account. If you followed the procedure in Install DS for platform identities, the subjectDn is as shown in this example.
- The --keyStorePassword:file option points to a file that contains the password to the new keystore.
- You can choose any certificate alias. The alias used here (am-identities-sa-cert) is an example.

Configure the Certificate Mapper property of the DS External SASL Mechanism Handler:

$ /path/to/opendj/bin/dsconfig set-sasl-mechanism-handler-prop \
--handler-name External \
--set certificate-mapper:Fingerprint\ Mapper \
--hostname ds.example.com \
--port 4444 \
--bindDn uid=admin \
--bindPassword <password> \
--trustAll \
--no-prompt
The External SASL Mechanism Handler was modified successfully

This example configures a Fingerprint Certificate Mapper, but you can use any supported Certificate Mapper.

Obtain the SHA256 fingerprint of the identity bind account.

This command obtains the fingerprint of the certificate you generated in Step 1:

$ keytool -list \
-v \
-alias am-identities-sa-cert \
-keyStore /path/to/am/security/keystores/mtls-keystore \
-storePass:file /path/to/am/security/mtls-keystore.pin
Alias name: am-identities-sa-cert
Creation date: Sep 26, 2023
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: UID=am-identity-bind-account, OU=admins, OU=identities
Issuer: CN=Deployment key, O=ForgeRock.com
Serial number: dba446f7de186933e34a
Valid from: Tue Sep 26 18:02:03 SAST 2023 until: Fri Sep 27 18:02:03 SAST 2024
Certificate fingerprints:
	 SHA1: EB:7D:17:BF:88:F4:1E:43:12:A9:BC:56:53:CB:29:91:4C:3D:DE:03
	 SHA256: D3:A2:DA:97:A3:6B:9C:D0:B2:A6:E7:45:62:B7:51:69:66:AB:22:FA:0C:C3:E2:63:DF:67:4E:DA:CB:C2:DA:65
Signature algorithm name: SHA256withECDSA
Subject Public Key Algorithm: 256-bit EC (secp256r1) key
Version: 3
…

Import the certificate details, including the fingerprint, into the identity bind account on DS.

Use the ldapmodify command to add the certificate details to DS.

Replace the value of the ds-certificate-fingerprint attribute with the SHA256 fingerprint you obtained in the previous step:

$ /path/to/opendj/bin/ldapmodify \
 --hostname ds.example.com \
 --port 1636 \
 --useSsl \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --bindDN uid=admin \
 --bindPassword <password> << EOF
dn: uid=am-identity-bind-account,ou=admins,ou=identities
changetype: modify
add: objectclass
objectclass: ds-certificate-user
-
add: ds-certificate-fingerprint
ds-certificate-fingerprint: D3:A2:DA:97:A3:6B:9C:D0:B2:A6:E7:45:62:B7:51:69:66:AB:22:FA:0C:C3:E2:63:DF:67:4E:DA:CB:C2:DA:65
-
add: ds-certificate-issuer-dn
ds-certificate-issuer-dn: CN=Deployment key,O=ForgeRock.com
-
add: ds-certificate-subject-dn
ds-certificate-subject-dn: UID=am-identity-bind-account, OU=admins, OU=identities
EOF
# MODIFY operation successful for DN uid=am-identity-bind-account,ou=admins,ou=identities

Repeat this step for each replicated DS server in your deployment.

Configure mTLS between AM and the identity store

These steps assume you’re configuring a separate secret store for mTLS certificates. Although this isn’t mandatory, it’s best practice to configure separate secret stores. If your deployment uses only one secret store, you can skip the first step of this procedure.

Configure the mTLS secret store in AM:
1. Go to Configure > Secret Stores and click Add Secret Store.
2. Enter the following details, and click Create:
  - Secret Store ID: mtls-keystore
  - Store Type: Keystore
  - File: /path/to/am/security/keystores/mtls-keystore
3. On the Settings tab, enter the following details:
  - Keystore type: PKCS12
  - Store password secret ID: <mtlsstorepass>
  - Entry password secret ID: <mtlsentrypass>
    
    Click Save Changes.

Add the path to the AM secrets store:

Go to Configure > Secret Stores and click Add Secret Store.
Enter the following details, and click Create:
- Secret Store ID: mtls-password-store
- Store Type: File System Secret Volumes
- Directory: /path/to/am/security/secrets

Set the File format to Plain text and click Save Changes.

For demonstration purposes, this example uses a plain text secret. In production systems, you should use a more secure secret format. For details of the secret types supported by file system secret volumes, refer to Configure a file system secret volume.

Configure mappings.
1. Go to Configure > Secret Stores and select mtls-keystore.
2. On the Mappings tab, click Add Mapping and enter a mapping for the identity store.
  - Secret ID: am.identity.repository.label.cert, where label is the value of the mTLS Secret Label property in the identity store configuration.
    
    You can only select the am.identity.repository.label.cert secret ID for mapping after you have created the mTLS Secret Label in the identity store configuration.
  - Aliases: am-identities-sa-cert
    
    Click Add, then click Create.

AM can now use mTLS to authenticate to the identity store.

mTLS for configuration stores

Configuring mTLS authentication to an external configuration store requires configuration changes on both the DS directory server and on AM.

Configure DS for mTLS
Configure mTLS between AM and the configuration store

Configure DS for mTLS

This section assumes you installed and configured DS as a configuration store.

By default, the credentials of the configuration account you created when you installed DS are:

Bind DN: uid=am-config,ou=admins,ou=am-config
Password: The password you set with am-config/amConfigAdminPassword

Adjust the following steps if you used different credentials.

When the DS server is running, create a keypair and save it to a new keystore:
```
$ dskeymgr create-tls-key-pair \
--deploymentId $DEPLOYMENT_ID \
--deploymentIdPassword <password> \
--keyStoreFile /path/to/mtls-keystore \
--keyStorePassword:file /path/to/mtls-keystore.pin \
--alias am-config-sa-cert \
--subjectDn "uid=am-config,ou=admins,ou=am-config"
```
- The subjectDn must match the subject DN of the configuration account. If you followed the procedure in Install DS for AM configuration, the subjectDn is as shown in this example.
- The --keyStorePassword:file option points to a file containing the password to the new keystore.
- You can choose any certificate alias. The alias used here (am-config-sa-cert) is an example.
- For details on the dskeymgr command, refer to dskeymgr.

Configure the Certificate Mapper property of the DS External SASL Mechanism Handler:

$ /path/to/opendj/bin/dsconfig set-sasl-mechanism-handler-prop \
--handler-name External \
--set certificate-mapper:Fingerprint\ Mapper \
--hostname ds.example.com \
--port 4444 \
--bindDn uid=admin \
--bindPassword <password> \
--trustAll \
--no-prompt
The External SASL Mechanism Handler was modified successfully

This example configures a Fingerprint Certificate Mapper, but you can use any supported Certificate Mapper.

Obtain the SHA256 fingerprint of the configuration account.

This command obtains the fingerprint of the certificate you generated in Step 1:

$ keytool -list \
-v \
-alias am-config-sa-cert \
-keyStore /path/to/mtls-keystore \
-keyStorePassword:file /path/to/mtls-keystore.pin \
Alias name: am-config-sa-cert
Creation date: Sep 20, 2023
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: UID=am-config, OU=admins, OU=am-config
Issuer: CN=Deployment key, O=ForgeRock.com
Serial number: dba446f7de186933e34a
Valid from: Fri Sep 20 18:02:03 SAST 2023 until: Sat Sep 29 18:02:03 SAST 2024
Certificate fingerprints:
	 SHA1: EB:7D:17:BF:88:F4:1E:43:12:A9:BC:56:53:CB:29:91:4C:3D:DE:03
	 SHA256: D3:A2:DA:97:A3:6B:9C:D0:B2:A6:E7:45:62:B7:51:69:66:AB:22:FA:0C:C3:E2:63:DF:67:4E:DA:CB:C2:DA:65
Signature algorithm name: SHA256withECDSA
Subject Public Key Algorithm: 256-bit EC (secp256r1) key
Version: 3
…

Import the certificate details, including the fingerprint, into the configuration account on DS.

Use the ldapmodify command to add the certificate details to DS.

Replace the value of the ds-certificate-fingerprint attribute with the SHA256 fingerprint you obtained in the previous step:

$ /path/to/opendj/bin/ldapmodify \
 --hostname ds.example.com \
 --port 1636 \
 --useSsl \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --bindDN uid=admin \
 --bindPassword <password> << EOF
dn: uid=am-config,ou=admins,ou=am-config
changetype: modify
add: objectclass
objectclass: ds-certificate-user
-
add: ds-certificate-fingerprint
ds-certificate-fingerprint: D3:A2:DA:97:A3:6B:9C:D0:B2:A6:E7:45:62:B7:51:69:66:AB:22:FA:0C:C3:E2:63:DF:67:4E:DA:CB:C2:DA:65
-
add: ds-certificate-issuer-dn
ds-certificate-issuer-dn: CN=Deployment key,O=ForgeRock.com
-
add: ds-certificate-subject-dn
ds-certificate-subject-dn: UID=am-config,OU=admins,OU=am-config
EOF
# MODIFY operation successful for DN uid=am-config,ou=admins,ou=am-config

Repeat this step for each replicated DS server in your deployment.

Configure mTLS between AM and the configuration store

Unlike other data stores, the configuration store doesn’t use the secrets API for mTLS authentication. Because AM stores secret mappings in the configuration store, you can’t use them to authenticate to the configuration store.

To set up mTLS authentication from AM to the configuration store:

Import the keypair that you created in Step 1 from the DS PKCS12 keystore to an AM JCEKS keystore.

(It’s not possible to export the keypair from DS directly to a JCEKS keystore.)

$ keytool -importkeystore \
 -srckeystore /path/to/mtls-keystore \
 -srcstorepass "" \
 -srckeypass "" \
 -destkeystore /path/to/am/security/keystores/keystore.jceks \
 -deststorepass $(cat /path/to/am/security/secrets/default/.storepass) \
 -destkeypass $(cat /path/to/am/security/secrets/default/.keypass) \
 -alias am-config-sa-cert

Go to Deployment > Servers > Server Name > Directory Configuration.
Select mTLS Enabled.
Enter the details of the mTLS certificate that you imported in the previous step, for example:
- mTLS Certificate Alias: am-config-sa-cert
- mTLS KeyStore File: /path/to/am/security/keystores/keystore.jceks
- mTLS KeyStore Type: JCEKS
- mTLS KeyStore Password File: /path/to/am/security/secrets/default/.storepass
- mTLS Key Password File: /path/to/am/security/secrets/default/.keypass

AM can now use mTLS to authenticate to the configuration store.

For security reasons, periodically rotate the certificate that AM uses to authenticate to the configuration store. Update the mTLS Certificate Alias in the Directory Configuration to refer to the new certificate.

When you rotate the active certificate used to authenticate to the configuration store, AM closes existing connections to that data store and establishes new connections. If this directory server is configured as your Default Data Store, AM closes all existing connections that use this server, and terminates any transactions in progress. AM then establishes new connections.

Make sure the Maximum Connection Pool setting for this server has sufficient connections so that AM can grab replacement connections from the pool without disrupting the service.

mTLS for policy and application stores

Configuring mTLS authentication to an external policy or application store requires configuration changes on both the DS directory server and on AM.

Configure DS for mTLS
Configure mTLS between AM and the policy or application store

Configure DS for mTLS

This section assumes you installed and configured DS as a policy or application store.

By default, the credentials of the configuration account you created when you installed DS are:

Bind DN: uid=am-config,ou=admins,ou=am-config
Password: The password you set with am-config/amConfigAdminPassword

Adjust the following steps if you used different credentials.

When the DS server is running, create a keystore and TLS key pair for the AM configuration account. This command creates the keypair in a new keystore in the default AM security folder:
```
$ ./dskeymgr create-tls-key-pair \
--deploymentId $DEPLOYMENT_ID \
--deploymentIdPassword <password> \
--keyStoreFile /path/to/am/security/keystores/mtls-keystore \
--keyStorePassword:file /path/to/am/security/mtls-keystore.pin \
--alias am-config-sa-cert \
--subjectDn "uid=am-config,ou=admins,ou=am-config"
```
- The subjectDn must match the subject DN of the configuration account. If you followed the procedure in Install DS for AM configuration, the subjectDn is as shown in this example.
- The --keyStorePassword:file option points to a file that contains the password to the new keystore.
- You can choose any certificate alias. The alias used here (am-config-sa-cert) is an example.

Configure the Certificate Mapper property of the DS External SASL Mechanism Handler:

$ /path/to/opendj/bin/dsconfig set-sasl-mechanism-handler-prop \
--handler-name External \
--set certificate-mapper:Fingerprint\ Mapper \
--hostname ds.example.com \
--port 4444 \
--bindDn uid=admin \
--bindPassword <password> \
--trustAll \
--no-prompt
The External SASL Mechanism Handler was modified successfully

This example configures a Fingerprint Certificate Mapper, but you can use any supported Certificate Mapper.

Obtain the SHA256 fingerprint of the configuration account.

This command obtains the fingerprint of the certificate you generated in Step 1:

$ keytool -list \
-v \
-alias am-config-sa-cert \
-keyStore /path/to/am/security/keystores/mtls-keystore \
-storePass:file /path/to/am/security/mtls-keystore.pin
Alias name: am-config-sa-cert
Creation date: Jun 30, 2023
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: UID=am-config, OU=admins, OU=am-config
Issuer: CN=Deployment key, O=ForgeRock.com
Serial number: dba446f7de186933e34a
Valid from: Fri Jun 30 18:02:03 SAST 2023 until: Sat Jun 29 18:02:03 SAST 2024
Certificate fingerprints:
	 SHA1: EB:7D:17:BF:88:F4:1E:43:12:A9:BC:56:53:CB:29:91:4C:3D:DE:03
	 SHA256: D3:A2:DA:97:A3:6B:9C:D0:B2:A6:E7:45:62:B7:51:69:66:AB:22:FA:0C:C3:E2:63:DF:67:4E:DA:CB:C2:DA:65
Signature algorithm name: SHA256withECDSA
Subject Public Key Algorithm: 256-bit EC (secp256r1) key
Version: 3
…

Import the certificate details, including the fingerprint, into the configuration account on DS.

Use the ldapmodify command to add the certificate details to DS.

Replace the value of the ds-certificate-fingerprint attribute with the SHA256 fingerprint you obtained in the previous step:

$ /path/to/opendj/bin/ldapmodify \
 --hostname ds.example.com \
 --port 1636 \
 --useSsl \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --bindDN uid=admin \
 --bindPassword <password> << EOF
dn: uid=am-config,ou=admins,ou=am-config
changetype: modify
add: objectclass
objectclass: ds-certificate-user
-
add: ds-certificate-fingerprint
ds-certificate-fingerprint: D3:A2:DA:97:A3:6B:9C:D0:B2:A6:E7:45:62:B7:51:69:66:AB:22:FA:0C:C3:E2:63:DF:67:4E:DA:CB:C2:DA:65
-
add: ds-certificate-issuer-dn
ds-certificate-issuer-dn: CN=Deployment key,O=ForgeRock.com
-
add: ds-certificate-subject-dn
ds-certificate-subject-dn: UID=am-config,OU=admins,OU=am-config
EOF
# MODIFY operation successful for DN uid=am-config,ou=admins,ou=am-config

Repeat this step for each replicated DS server in your deployment.

Configure mTLS between AM and the policy or application store

These steps assume that you are configuring a separate secret store for mTLS certificates. Although this isn’t mandatory, it’s best practice to configure separate secret stores. If your deployment uses only one secret store, you can skip the first step of this procedure.

Configure the mTLS secret store in AM:
1. Go to Configure > Secret Stores and click Add Secret Store.
2. Enter the following details, and click Create:
  - Secret Store ID: mtls-keystore
  - Store Type: Keystore
  - File: /path/to/am/security/keystores/mtls-keystore
3. On the Settings tab, enter the following details:
  - Keystore type: PKCS12
  - Store password secret ID: <mtlsstorepass>
  - Entry password secret ID: <mtlsentrypass>
    
    Click Save Changes.

Add the path to the AM secrets store:

Go to Configure > Secret Stores and click Add Secret Store.
Enter the following details, and click Create:
- Secret Store ID: mtls-password-store
- Store Type: File System Secret Volumes
- Directory: /path/to/am/security/secrets

Set the File format to Plain text and click Save Changes.

Configure mappings.
1. Go to Configure > Secret Stores and select mtls-keystore.
2. On the Mappings tab, click Add Mapping and enter a mapping for the policy or application store.
  - Secret ID: am.external.datastore.label.mtls.cert, where label is the value of the mTLS Secret Label property in the data store configuration.
  - Aliases: am-config-sa-cert
    
    Click Add, then click Create.

AM can now use mTLS to authenticate to the policy or application store.

mTLS for CTS stores

This section assumes you installed Directory Services as a CTS store, as described in Install DS for AM CTS.

You must configure DS and AM for mTLS authentication.

Configure DS for mTLS

When the DS server is running, create a keystore and TLS key pair for the AM CTS account. This command creates the keypair in a new keystore in the default AM security folder:
```
$ /path/to/opendj/bin/dskeymgr create-tls-key-pair \
--deploymentId $DEPLOYMENT_ID \
--deploymentIdPassword <password> \
--keyStoreFile /path/to/am/security/keystores/mtls-keystore \
--keyStorePassword:file /path/to/am/security/mtls-keystore.pin \
--alias am-cts-sa-cert \
--subjectDn "uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens"
```
- The subjectDn must match the subject DN of the CTS account. If you followed the procedure in Install DS for AM CTS, the subjectDn is as shown in this example.
- The --keyStorePassword:file option points to a file that contains the password to the new keystore.
- You can choose any certificate alias. The alias used here (am-cts-sa-cert) is an example.

Configure the Certificate Mapper property of the DS External SASL Mechanism Handler:

$ /path/to/opendj/bin/dsconfig set-sasl-mechanism-handler-prop \
--handler-name External \
--set certificate-mapper:Fingerprint\ Mapper \
--hostname ds.example.com \
--port 4444 \
--bindDn uid=admin \
--bindPassword <password> \
--trustAll \
--no-prompt

The External SASL Mechanism Handler was modified successfully

This example configures a Fingerprint Certificate Mapper, but you can use any supported Certificate Mapper.

Obtain the SHA256 fingerprint of the CTS account.

This command obtains the fingerprint of the certificate you generated in Step 1:

$ keytool -list \
-v \
-alias am-cts-sa-cert \
-keyStore /path/to/am/security/keystores/mtls-keystore \
-storePass:file /path/to/am/security/mtls-keystore.pin
Alias name: am-cts-sa-cert
Creation date: Jun 30, 2023
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: UID=openam_cts, OU=admins, OU=famrecords, OU=openam-session, OU=tokens
Issuer: CN=Deployment key, O=ForgeRock.com
Serial number: 6c100c4b05819d97ee86
Valid from: Fri Jun 30 09:39:00 SAST 2023 until: Sat Jun 29 09:39:00 SAST 2024
Certificate fingerprints:
	 SHA1: 46:E9:0E:7B:A6:51:52:6A:BE:7A:02:04:40:7A:6D:1B:F1:D6:6A:9A
	 SHA256: E2:68:4F:D0:87:A7:E5:52:45:91:CE:EC:46:90:3D:59:5C:6A:6E:31:E2:0D:34:07:63:27:6C:E8:C3:09:25:00
Signature algorithm name: SHA256withECDSA
Subject Public Key Algorithm: 256-bit EC (secp256r1) key
Version: 3
…

Import the certificate details, including the fingerprint, into the CTS account on DS.

Use the ldapmodify command to add the certificate details to DS.

Replace the value of the ds-certificate-fingerprint attribute with the SHA256 fingerprint you obtained in the previous step:

$ /path/to/opendj/bin/ldapmodify \
 --hostname ds.example.com \
 --port 1636 \
 --useSsl \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --bindDN uid=admin \
 --bindPassword <password> << EOF
dn: uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens
changetype: modify
add: objectclass
objectclass: ds-certificate-user
-
add: ds-certificate-fingerprint
ds-certificate-fingerprint: E2:68:4F:D0:87:A7:E5:52:45:91:CE:EC:46:90:3D:59:5C:6A:6E:31:E2:0D:34:07:63:27:6C:E8:C3:09:25:00
-
add: ds-certificate-subject-dn
ds-certificate-subject-dn: UID=openam_cts, OU=admins, OU=famrecords, OU=openam-session, OU=tokens
-
add: ds-certificate-issuer-dn
ds-certificate-issuer-dn: CN=Deployment key,O=ForgeRock.com
EOF
# MODIFY operation successful for DN uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens

Repeat this step for each replicated DS server in your deployment.

Configure mTLS between AM and the CTS store

Configure the mTLS secret store in AM:
1. Go to Configure > Secret Stores and click Add Secret Store.
2. Enter the following details, and click Create:
  - Secret Store ID: mtls-keystore
  - Store Type: Keystore
  - File: /path/to/am/security/keystores/mtls-keystore
3. On the Settings tab, enter the following details:
  - Keystore type: PKCS12
  - Store password secret ID: <mtlsstorepass>
  - Entry password secret ID: <mtlsentrypass>
    
    Click Save Changes.
4. On the Mappings tab, click Add Mapping and enter the following details.
  - Secret ID: am.cts.mtls.cert
  - Aliases: am-cts-sa-cert
    
    Click Add, then click Create.

Add the path to the AM secrets store:

Go to Configure > Secret Stores and click Add Secret Store.
Enter the following details, and click Create:
- Secret Store ID: mtls-password-store
- Store Type: File System Secret Volumes
- Directory: /path/to/am/security/secrets

Set the File format to Plain text and click Save Changes.

Configure the CTS for mTLS:
1. Go to Configure > Server Defaults > CTS.
2. On the CTS Token Store tab > Store Mode, select External Token Store.
3. Set the Root Suffix to ou=famrecords,ou=openam-session,ou=tokens and click Save Changes.
4. On the External Store Configuration tab, set SSL/TLS Enabled and mTLS Enabled.
5. In the Connection String(s) field, enter the connection details of the DS server that you configured as a CTS store, in the format <host>:<port>; for example, ds.example.com:1636.
  
  If you enable mTLS, the port must be a secure LDAP (LDAPS) port.
6. Leave the Login Id and Password fields blank; AM ignores these fields when mTLS is enabled.
7. Click Save Changes.
AM can now use mTLS to authenticate to the CTS store.

If your mTLS configuration is invalid, or uses an invalid secret mapping, AM continues to use the existing connection factory and doesn’t roll over to the mTLS connection. Instead, it logs an error with the reason for the failure. However, if you restart AM with the invalid configuration, the restart fails.

To avoid this situation, check the logs after you update the mTLS configuration and make sure there are no errors relating to the new configuration. AM logs errors in the BASE_DIR/var/debug/OtherLogging file.

An invalid mTLS configuration returns the following error:

ERROR: New connection configuration failed to validate. Error: LDAP connection validation failed. Reason:

A valid mTLS configuration returns messages similar to the following in the audit log:

{
  "_id":"9dc74fc7-025e-491f-92b0-98363f9b3866-5663",
  "timestamp":"2023-10-05T10:23:43.514Z",
  "eventName":"AM-CONNECTION-UPDATE",
  "transactionId":"9dc74fc7-025e-491f-92b0-98363f9b3866-2317",
  "runAs":"",
  "objectId":"UpdatableConnectionFactory",
  "operation":"UPDATE",
  "component":"CTS"
}

mTLS for UMA stores

This section assumes you installed Directory Services as an UMA store, as described in Configure external UMA stores. By default, the credentials of the configuration account you created when you installed DS are:

Bind DN: uid=am-config,ou=admins,ou=am-config
Password: The password you set with am-config/amConfigAdminPassword

You must configure DS and AM for mTLS authentication.

Configure DS for mTLS

When the DS server is running, create a keystore and TLS key pair for the AM configuration account. This command creates the keypair in a new keystore in the default AM security folder:
```
$ ./dskeymgr create-tls-key-pair \
--deploymentId $DEPLOYMENT_ID \
--deploymentIdPassword <password> \
--keyStoreFile /path/to/am/security/keystores/mtls-keystore \
--keyStorePassword:file /path/to/am/security/mtls-keystore.pin \
--alias am-config-sa-cert \
--subjectDn "uid=am-config,ou=admins,ou=am-config"
```
- The subjectDn must match the subject DN of the configuration account. If you followed the procedure in Install DS for AM configuration, the subjectDn is as shown in this example.
- The --keyStorePassword:file option points to a file that contains the password to the new keystore.
- You can choose any certificate alias. The alias used here (am-config-sa-cert) is an example.

Configure the Certificate Mapper property of the DS External SASL Mechanism Handler:

$ /path/to/opendj/bin/dsconfig set-sasl-mechanism-handler-prop \
--handler-name External \
--set certificate-mapper:Fingerprint\ Mapper \
--hostname ds.example.com \
--port 4444 \
--bindDn uid=admin \
--bindPassword <password> \
--trustAll \
--no-prompt
The External SASL Mechanism Handler was modified successfully

This example configures a Fingerprint Certificate Mapper, but you can use any supported Certificate Mapper.

Obtain the SHA256 fingerprint of the configuration account.

This command obtains the fingerprint of the certificate you generated in Step 1:

$ keytool -list \
-v \
-alias am-config-sa-cert \
-keyStore /path/to/am/security/keystores/mtls-keystore \
-storePass:file /path/to/am/security/mtls-keystore.pin
Alias name: am-config-sa-cert
Creation date: Jun 30, 2023
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: UID=am-config, OU=admins, OU=am-config
Issuer: CN=Deployment key, O=ForgeRock.com
Serial number: dba446f7de186933e34a
Valid from: Fri Jun 30 18:02:03 SAST 2023 until: Sat Jun 29 18:02:03 SAST 2024
Certificate fingerprints:
	 SHA1: EB:7D:17:BF:88:F4:1E:43:12:A9:BC:56:53:CB:29:91:4C:3D:DE:03
	 SHA256: D3:A2:DA:97:A3:6B:9C:D0:B2:A6:E7:45:62:B7:51:69:66:AB:22:FA:0C:C3:E2:63:DF:67:4E:DA:CB:C2:DA:65
Signature algorithm name: SHA256withECDSA
Subject Public Key Algorithm: 256-bit EC (secp256r1) key
Version: 3
…

Import the certificate details, including the fingerprint, into the configuration account on DS.

Use the ldapmodify command to add the certificate details to DS.

Replace the value of the ds-certificate-fingerprint attribute with the SHA256 fingerprint you obtained in the previous step:

$ /path/to/opendj/bin/ldapmodify \
 --hostname ds.example.com \
 --port 1636 \
 --useSsl \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --bindDN uid=admin \
 --bindPassword <password> << EOF
dn: uid=am-config,ou=admins,ou=am-config
changetype: modify
add: objectclass
objectclass: ds-certificate-user
-
add: ds-certificate-fingerprint
ds-certificate-fingerprint: D3:A2:DA:97:A3:6B:9C:D0:B2:A6:E7:45:62:B7:51:69:66:AB:22:FA:0C:C3:E2:63:DF:67:4E:DA:CB:C2:DA:65
-
add: ds-certificate-issuer-dn
ds-certificate-issuer-dn: CN=Deployment key,O=ForgeRock.com
-
add: ds-certificate-subject-dn
ds-certificate-subject-dn: UID=am-config,OU=admins,OU=am-config
EOF
# MODIFY operation successful for DN uid=am-config,ou=admins,ou=am-config

Repeat this step for each replicated DS server in your deployment.

Configure mTLS between AM and the UMA store

Configure the mTLS secret store in AM:
1. Go to Configure > Secret Stores and click Add Secret Store.
2. Enter the following details, and click Create:
  - Secret Store ID: mtls-keystore
  - Store Type: Keystore
  - File: /path/to/am/security/keystores/mtls-keystore
3. On the Settings tab, enter the following details:
  - Keystore type: PKCS12
  - Store password secret ID: <mtlsstorepass>
  - Entry password secret ID: <mtlsentrypass>
    
    Click Save Changes.

Add the path to the AM secrets store:

Go to Configure > Secret Stores and click Add Secret Store.
Enter the following details, and click Create:
- Secret Store ID: mtls-password-store
- Store Type: File System Secret Volumes
- Directory: /path/to/am/security/secrets

Set the File format to Plain text and click Save Changes.

Configure the UMA stores for mTLS:
1. Go to Configure > Server Defaults > UMA.
2. On the UMA Resource Store tab > Store Mode, select External Token Store.
3. Set the Root Suffix to ou=am-config and click Save Changes.
4. On the External UMA Resource Store Configuration tab, set SSL/TLS Enabled and mTLS Enabled.
5. In the Connection String(s) field, enter the connection details of the DS server that you configured as a configuration store, in the format <host>:<port>; for example, ds.example.com:1636.
  
  If you enable mTLS, the port must be a secure LDAP (LDAPS) port.
6. Leave the Login Id and Password fields blank; AM ignores these fields when mTLS is enabled.
7. Click Save Changes.
8. Repeat steps b-g for each UMA store type that will use mTLS authentication.
Configure mappings.
1. Go to Configure > Secret Stores and mtls-keystore.
2. On the Mappings tab, click Add Mapping and enter a mapping for each UMA store.
  
  This example uses the same certificate alias for all UMA stores. If your UMA stores are on separate DS servers, you can specify a different certificate alias for each store.
  - Secret ID: am.uma.audit.messages.mtls.cert
  - Aliases: am-config-sa-cert
    
    Click Add, then click Create.
  - Secret ID: am.uma.pending.requests.mtls.cert
  - Aliases: am-config-sa-cert
    
    Click Add, then click Create.
  - Secret ID: am.uma.resource.labels.mtls.cert
  - Aliases: am-config-sa-cert
    
    Click Add, then click Create.
  - Secret ID: am.uma.resource.sets.mtls.cert
  - Aliases: am-config-sa-cert
    
    Click Add, then click Create.
AM can now use mTLS to authenticate to the UMA stores.

An invalid mTLS configuration returns the following error:

ERROR: New connection configuration failed to validate. Error: LDAP connection validation failed. Reason:

A valid mTLS configuration returns messages similar to the following in the audit log:

{
  "_id":"9dc74fc7-025e-491f-92b0-98363f9b3866-5663",
  "timestamp":"2023-10-05T10:23:43.514Z",
  "eventName":"AM-CONNECTION-UPDATE",
  "transactionId":"9dc74fc7-025e-491f-92b0-98363f9b3866-2317",
  "runAs":"",
  "objectId":"UpdatableConnectionFactory",
  "operation":"UPDATE",
  "component":"UMA"
}

AM 7.4.0

Secure authentication to data stores

mTLS for identity stores

Configure DS for mTLS

Configure mTLS between AM and the identity store

mTLS for configuration stores

Configure DS for mTLS

Configure mTLS between AM and the configuration store

mTLS for policy and application stores

Configure DS for mTLS

Configure mTLS between AM and the policy or application store

mTLS for CTS stores

Configure DS for mTLS

Configure mTLS between AM and the CTS store

mTLS for UMA stores

Configure DS for mTLS

Configure mTLS between AM and the UMA store