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, as 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 will try 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 ForgeRock Identity Management.
To prepare external identity repositories, see the following sections:
If you are installing a new Directory Services instance for identity data, see Install and configure Directory Services for identity data.
If you are connecting AM to an existing identity repository, see Configure existing directory servers for identity data.
This section shows how to install and set up a new DS server instance for identity data.
Directory Services 6.5 added support for setup profiles to simplify initial configuration.
Using a setup profile creates the backend, schema, bind user, and indexes required for use with identity data.
|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 will see bind failures with persistent searches.
To install DS using a setup profile, follow the steps in Install DS for AM identities in the Directory Services documentation.
Share the identity store certificate with the AM container to prepare for TLS/LDAPS. Identity stores should communicate over secure connections for security reasons.
DS 7 or later is configured to require secure connections by default; therefore, share its certificate with the AM container before continuing.
Export the DS server certificate:
$ keytool -exportcert \ -keystore /path/to/opendj/config/keystore \ -storepass $(cat /path/to/opendj/config/keystore.pin) \ -alias ssl-key-pair \ -rfc \ -file ds-cert.pem
The default DS server certificate only has the hostname you supplied at setup time, and
localhost, as the value of the
SubjectAlternativeNameattribute; however, certificate hostname validation is strict. Ensure that the certificate matches the hostname (or the FQDN) of the DS server before continuing.
ds-cert.pemfile to an accessible location on the AM host.
Import the DS certificate into the AM truststore:
$ keytool \ -importcert \ -file ds-cert.pem \ -keystore /path/to/openam/security/keystores/truststore
For more information on configuring AM’s truststore, see Prepare the truststore.
If you did not install DS using a setup profile, perform the following steps to update the permissions in an external Directory Services identity repository.
If you are using a directory server other than Directory Services, apply the relevant LDIF files using the appropriate tools.
opendj_userinit.ldifLDIF file in the
/path/to/openam/WEB-INF/template/ldif/opendjdirectory, replacing all variables that are surrounded by at (@ ) symbols with a value specific to your directory server.
For example, in the
opendj_userinit.ldifLDIF file you must replace all instances of @userStoreRootSuffix@ with the root suffix you specified when configuring the external DS identity store, the default being
ldapmodifycommand to add the updated LDIF data to the external instance.
$ /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, see 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 ForgeRock Directory Services repository, you can update the schema by applying the following LDIF files:
$ /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, see Set up directory schemas with LDIF. For directory servers other than ForgeRock Directory Services, adapt the
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
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 a 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:
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.
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
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 accountstask.
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
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. See the following procedures:
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
directory-type is one of the following:
adfor Microsoft Active Directory
adamfor Microsoft Active Directory Lightweight Directory Services
odseefor Oracle Directory Server Enterprise Edition
opendjfor ForgeRock Directory Services and Oracle Unified Directory
tivolifor IBM Tivoli Directory Server
For more information on the LDIF files, see 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/addirectory, 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
Using an Active Directory administrator account, add the required AM schema extensions to your external identity repository.
For example, in PowerShell, run the
ldifdecommand 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:
For more information on these LDIF files, and the equivalent files for supported directory servers, see 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
webauthnDeviceProfilesContaineris in the LDAP User Object Class property. If not, add the value, and then save your changes.
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. See Test external identity repository access.