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

Note

You should not configure more than one writeable 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:

Installing and Configuring Directory Services for Identity Data

This section shows how to install and set up a new DS server instance for identity data.

To Install and Configure Directory Services for Identity Data

Directory Services 6.5 added support for setup profiles to greatly simplify initial configuration.

Using a setup profile will create the backend, schema, bind user, and indexes required for use with identity data.

  1. To install DS using a setup profile, follow the steps in DS for AM Identities in the Directory Services 7 Installation Guide.

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

    1. Export the DS server certificate:

      $ /path/to/opendj/bin/dskeymgr export-ca-cert \
      --deploymentKey $DEPLOYMENT_KEY \
      --deploymentKeyPassword password \
      --alias ds-ca-cert \
      --outputFile ds-ca-cert.pem

      Note that $DEPLOYMENT_KEY is a Unix variable that contains the DS deployment key, so that it is not logged in the user's command history.

      The default DS server certificate only has the hostname you supplied at setup time, and localhost, as the value of the SubjectAlternativeName attribute; however, certificate hostname validation is strict.

      Ensure that the certificate matches the hostname (or the FQDN) of the DS server before continuing.

    2. Import the DS certificate into the AM truststore:

      $ keytool \
      -importcert \
      -alias ds-ca-cert \
      -file ds-ca-cert.pem \
      -keystore /path/to/openam/security/keystores/truststore

    For more information on configuring AM's truststore, see "Preparing a Truststore".

  3. (Optional) 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.

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

    2. 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, see "Supported LDIF Files".

    3. (Optional) 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/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, see "Supported LDIF Files". For directory servers other than ForgeRock Directory Services, adapt the opendj_*.ldif files accordingly.

  4. Proceed to configuring the identity store in AM. See Identity Stores.

    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.

Configuring 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 a list of supported external directory servers, see "Supported Data Stores".

The following sections show you how to prepare an existing identity repository for use in AM:

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

The following procedure gives an example of creating a bind account in Active Directory:

To Create a Bind Account in Active Directory for AM Connections

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:

    1. In the Active Directory Users and Computers tool, right-click Users in the domain, and select New > User.

    2. Provide descriptive values for the new user, and a logon name such as AM-Bind-Account.

    3. Click Next.

    4. Enter a strong password for the bind account, disable the User must change password at next logon option, and then click Next.

    5. Review the details of the new account, and then click Finish.

  2. Give the new bind account access to the directory data:

    1. In the Active Directory Users and Computers tool, right-click the domain that contains your users, and then select Delegate Control.

    2. Add the bind account you created in the previous step, and then click Next.

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

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

Updating 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. See the following procedures:

To 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 ForgeRock Directory Services and Oracle Unified Directory

  • tivoli for IBM Tivoli Directory Server

For more information on the LDIF files, see "Supported LDIF Files".

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. (Optional) 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, see "Supported LDIF Files".

  4. Proceed to configuring the identity store in AM. See Identity Stores.

    Important

    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.

To 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 "To Configure an Identity Store".

    Important

    Enable the Load Schema option before clicking Save Changes, and AM will apply the neccessary 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. See "Testing External Identity Repository Access".

Read a different version of :