Prepare identity repositories
AM accesses user identity data from one or more identity repositories.
In most deployments, AM connects to existing LDAP directory servers for user identity data, because it shares data in an identity repository with other applications.
You should not configure more than one writable identity repository in a single realm. AM tries to perform write operations on each identity repository configured in a realm, and there is no way to configure which repository is written to. To manage identities and reconcile differences between multiple identity repositories, use PingIDM. |
To prepare external identity repositories, refer to the following sections:
-
If you’re installing a new PingDS instance for identity data, read Install and configure PingDS for identity data.
-
If you’re connecting AM to an existing identity repository, read Configure existing directory servers for identity data.
Install and configure PingDS for identity data
This section shows how to install and set up a new DS server for identity data. Make sure DS replicas use the same configuration.
Installing DS with a setup profile creates the required backend, schema, bind user, and indexes.
The bind account for the identity store is fetched when AM starts up. If you change the account (DN or password) while AM is running, you must restart AM for the change to be taken into account. Otherwise, you’ll encounter bind failures with persistent searches. |
-
Follow the steps in Install DS for AM identities in the PingDS documentation.
-
Share the identity store certificate with the AM container to prepare for TLS/LDAPS. Communication with the identity store must use a secure connection.
-
On the DS host, export the DS CA certificate.
DS uses a deployment ID and password to generate a CA key pair. Learn more in Deployment IDs.
Use the
dskeymgr
command to export the CA certificate:$ /path/to/opendj/bin/dskeymgr \ export-ca-cert \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --outputFile /path/to/ca-cert.pem
-
Copy the
ca-cert.pem
file to an accessible location on the AM host.
-
Import the DS certificate into the AM truststore:
$ keytool \ -importcert \ -file /path/to/ca-cert.pem \ -keystore /path/to/openam/security/keystores/truststore
Learn more about configuring AM’s truststore, in Prepare the truststore.
-
-
If you did not install DS using a setup profile, perform the following steps to update the permissions in an external PingDS identity repository.
If you are using a directory server other than PingDS, apply the relevant LDIF files using the appropriate tools.
-
Edit the
opendj_userinit.ldif
LDIF file in the/path/to/openam/WEB-INF/template/ldif/opendj
directory, replacing all variables that are surrounded by at (@ ) symbols with a value specific to your directory server.For example, in the
opendj_userinit.ldif
LDIF file you must replace all instances of @userStoreRootSuffix@ with the root suffix you specified when configuring the external DS identity store, the default beingou=identities
. -
Use the
ldapmodify
command to add the updated LDIF data to the external instance.For example:
$ /path/to/opendj/bin/ldapmodify \ --hostname 'id.example.com' \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --continueOnError \ --bindDN uid=admin \ --bindPassword str0ngAdm1nPa55word \ /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_userinit.ldif
For more information on this LDIF file, and equivalent files for supported directory servers, refer to Set up directory schemas with LDIF.
-
If you intend to use web authentication, or perform device profiling with the ForgeRock SDK, you might need to update the directory server schema. For a PingDS repository, you can update the schema by applying the following LDIF files:
-
/path/to/openam/WEB-INF/template/ldif/opendj/opendj_webauthndevices.ldif
-
/path/to/openam/WEB-INF/template/ldif/opendj/opendj_deviceprofiles.ldif
For example:
$ /path/to/opendj/bin/ldapmodify \ --hostname 'id.example.com' \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --continueOnError \ --bindDN uid=admin \ --bindPassword str0ngAdm1nPa55word \ /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_webauthndevices.ldif\ /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_deviceprofiles.ldif
For more information on these LDIF files, refer to Set up directory schemas with LDIF. For directory servers other than PingDS, adapt the
opendj_*.ldif
files accordingly.
-
-
-
Proceed to configure the identity store in AM.
The bind DN of the service account to use when configuring the identity store in AM is
uid=am-identity-bind-account,ou=admins,ou=identities
.
Configure existing directory servers for identity data
It is common for AM to access identity data from an existing directory server. AM requires a user account to connect to the directory server, and AM LDAP schema to update entries with AM-related identity data.
For the list of supported external directory servers, refer to Directory servers.
The following sections show you how to prepare an existing identity repository for use in AM:
Create a directory server user for AM connections
AM connects to an external directory server with a service account that you specify in the AM identity repository configuration. This service account is known as the AM bind account.
Specifying the directory administrator as the AM bind account is not recommended for production deployments as it would give AM directory administrator privileges to the identity repository.
Instead, create a separate AM bind account with fewer access privileges than the directory administrator so that you can assign the appropriate level of privileges for the AM bind account.
You need to consider two areas of permission for the AM bind account:
- Schema Update Privileges
-
AM needs to update the directory schema when you configure a new identity repository and when you upgrade AM software. If the AM bind account has schema update privileges, AM can update the schema dynamically during identity repository configuration and during AM upgrades. If the AM bind account does not have schema update privileges, you must update the schema manually before configuring a new identity repository and before upgrading AM.
- Directory Read and Write Access Privileges
-
If you want AM to create, update, and delete user entries, then the AM bind account must have full read and write access to the identity data in the directory. If you are using an external identity repository as a read-only user directory, then the AM bind account needs read privileges only.
The level of access privileges you give the AM bind account is specific to each AM deployment. Work with your directory server administrator to determine the appropriate level of privileges as part of the process of preparing your external identity repositories.
Create a bind account in Active Directory for AM connections
The following procedure gives an example of creating a bind account in Active Directory:
Perform these steps to create a user that AM can use to connect to Active Directory. These steps are one example, consult with your Active Directory administrator on how best to create an account.
-
Create a new user account in the Active Directory domain. For example, in Windows 2019:
-
In the Active Directory Users and Computers tool, right-click Users in the domain, and select New > User.
-
Provide descriptive values for the new user, and a logon name such as
AM-Bind-Account
. -
Click Next.
-
Enter a strong password for the bind account, disable the User must change password at next logon option, and click Next.
-
Review the details of the new account, and click Finish.
-
-
Give the new bind account access to the directory data:
-
In the Active Directory Users and Computers tool, right-click the domain that contains your users, and select Delegate Control.
-
Add the bind account you created in the previous step, and click Next.
-
Select the tasks you want to allow the AM bind account to perform from the list.
For example, to allow read and write access to users, enable the
Create, delete, and manage inetOrgPerson accounts
task. -
After assigning the tasks you want to allow the AM bind account to perform, click Finish.
You can now set up the necessary schema in the directory server.
The bind account to use when configuring the identity store in AM is the full DN of the user, for example
uid=AM-Bind-Account,ou=Users,dc=example,dc=org
. -
Update the schema in an external identity repository
AM can add the necessary LDAP schema definitions itself, if it has sufficient privileges to do so, or you can apply the LDAP schema definition LDIF files manually if required. Refer to the following procedures:
Prepare an external identity repository with manual schema updates
If the AM bind account does not have permission to update schema then you must configure existing external data stores by using manual schema updates. To do this, you must update the directory server schema of the external identity repository manually at the following times:
-
Before you configure the identity repository as part of initial AM configuration.
-
Before you configure an identity repository after initial AM configuration.
-
Whenever you upgrade AM.
A number of LDIF files are provided in the AM .war
file for supported identity directory servers.
The path is /path/to/openam/WEB-INF/template/ldif/directory-type
, where directory-type
is one of the following:
-
ad
for Microsoft Active Directory -
adam
for Microsoft Active Directory Lightweight Directory Services -
odsee
for Oracle Directory Server Enterprise Edition -
opendj
for PingDS and Oracle Unified Directory -
tivoli
for IBM Tivoli Directory Server
For more information on the LDIF files, refer to Set up directory schemas with LDIF.
The following steps update the schema in an Active Directory identity repository. For other directory servers, apply the relevant LDIF files using the appropriate tools.
-
Edit the LDIF files in the
/path/to/openam/WEB-INF/template/ldif/ad
directory, replacing any variables that are surrounded by at (@ ) symbols with a value specific to your directory server.For the Active Directory LDIF files you must replace all instances of @userStoreRootSuffix@ with the root suffix used by your Active Directory identity store, for example
DC=example,DC=org
. -
Using an Active Directory administrator account, add the required AM schema extensions to your external identity repository.
For example, in PowerShell, run the
ldifde
command to import the user, device print, and dashboard schema extensions:PS C:\Users\Administrator> cd \path\to\openam\WEB-INF\template\ldif\ad PS C:\path\to\openam\WEB-INF\template\ldif\ad> ldifde -i -f .\ad_user_schema.ldif Connecting to "domain.example.org" Logging in as current user using SSPI Importing directory from file ".\ad_user_schema.ldif" Loading entries................................................................. 64 entries modified successfully. The command has completed successfully PS C:\path\to\openam\WEB-INF\template\ldif\ad> ldifde -i -f .\ad_deviceprint.ldif Connecting to "domain.example.org" Logging in as current user using SSPI Importing directory from file ".\ad_deviceprint.ldif" Loading entries................................................................. 6 entries modified successfully. The command has completed successfully PS C:\path\to\openam\WEB-INF\template\ldif\ad> ldifde -i -f .\ad_dashboard.ldif Connecting to "domain.example.org" Logging in as current user using SSPI Importing directory from file ".\ad_dashboard.ldif" Loading entries................................................................. 6 entries modified successfully. The command has completed successfully
-
If you intend to use push or web authentication, apply the following LDIF files:
-
/path/to/openam/WEB-INF/template/ldif/ad/ad_pushdevices.ldif
-
/path/to/openam/WEB-INF/template/ldif/ad/ad_webauthndevices.ldif
For more information on these LDIF files, and the equivalent files for supported directory servers, refer to Set up directory schemas with LDIF.
-
-
Proceed to configure the identity store in AM.
If you updated the schema to make use of web authentication, when configuring the external identity store in a realm, on the User Configuration tab, ensure webauthnDeviceProfilesContainer
is in the LDAP User Object Class property. If not, add the value, and then save your changes.
Prepare an external identity repository with automatic schema updates
If the bind account has permission to update schema then you can allow AM to update the schema automatically.
To allow AM to update the schema, you must first configure AM to be able to access the directory server, and enable the Load Schema option, by performing the following steps:
-
Configure the directory server in AM by following the instructions in Configure an identity store.
Enable the Load Schema option before saving your changes, and AM will apply the necessary schema to the directory server. The schema is loaded as part of configuring the identity store in AM. No further configuration is required.
-
Verify that the new identity repository is correctly configured in AM. Refer to Test external identity repository access.