PingAM 7.5.1

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:

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.

  1. Follow the steps in Install DS for AM identities in the PingDS documentation.

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

  3. 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 being ou=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 \
--truststorepassword:file /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 \
--truststorepassword:file /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.

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

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

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

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

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

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

  4. 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:

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

  2. Verify that the new identity repository is correctly configured in AM. Refer to Test external identity repository access.