External DS Repository

IDM supports the following deployment scenarios with a DS repository:

Configure a Single External DS Instance as a Repository

  1. If you have not yet installed DS, download it from the ForgeRock BackStage download site and extract the .zip archive.

  2. Install DS according to the instructions in the DS Installation Guide:

    1. If you are planning to use a generic object mapping for managed users, install DS with the idm-repo profile (see Install DS as an IDM Repository).

    2. If you are planning to use an explicit object mapping for managed users, install DS with both the idm-repo and am-identity-store profiles (see Install DS as an IDM Repository and Install DS for AM Identities).

    This example configures DS on the localhost, listening on the following ports:

    • LDAP port: 31389

    • Admin port: 34444

    • LDAPS port: 31636

    We've used these ports to avoid a port conflict with the default ports used in the LDAP samples. You can use any host and available ports in the setup. If you use a different host and ports, change the primaryLdapServers property in your repo.ds-external.json file accordingly.

    Note

    Every DS deployment requires a deployment key and a deployment key password to secure network connections. The deployment key is a random string generated by DS software. The deployment key password is a secret string that you choose. It must be at least 8 characters long. The deployment key and password automate key pair generation and signing without storing the CA private key. For more information, see Deployment Keys in the DS Security Guide.

  3. In your IDM installation, remove the default DS repository configuration file (repo.ds.json) from your project's conf/ directory. For example: 

    cd /path/to/openidm/my-project/conf/
rm repo.ds.json

  4. Copy the external DS repository configuration file (repo.ds-external.json) to your project's conf directory and rename it repo.ds.json: 

    cp /path/to/openidm/db/ds/conf/repo.ds-external.json my-project/conf/repo.ds.json

  5. Enable IDM to trust the DS server certificate for your deployment.

    For example, in the default case, where DS servers use TLS key pairs generated using a deployment key and password, import the deployment key-based CA certificate into the IDM truststore: 

    /path/to/opendj/bin/dskeymgr \
export-ca-cert \
--deploymentKey your-deployment-key \
--deploymentKeyPassword password \
--outputFile ds-ca-cert.pem
    keytool \
-importcert \
-alias ds-ca-cert \
-keystore /path/to/openidm/security/truststore \
-storepass:file /path/to/openidm/security/storepass \
-file ds-ca-cert.pem
Owner: CN=Deployment key, O=ForgeRock.com
Issuer: CN=Deployment key, O=ForgeRock.com
...
Trust this certificate? [no]:  yes
Certificate was added to keystore

  6. Adjust the connection settings from IDM to DS in the IDM repository configuration file, repo.ds.json:

    • If your DS instance is not running on the localhost and listening for LDAP connections on port 31389, adjust the primaryLdapServers property in that file to match your DS setup.

    • Make sure the password for the DS directory superuser (uid=admin) matches the DS root user password in the IDM configuration.

    For details about the connection settings, see the information in Gateway LDAP Connections in the DS HTTP User Guide. (IDM shares these configuration settings with the DS REST to LDAP Gateway.)

  7. Start IDM with the configuration for your project. For example: 

    /path/to/openidm/startup.sh -p my-project
Executing ./startup.sh...
Using OPENIDM_HOME:   /path/to/openidm
Using PROJECT_HOME:   /path/to/my-project
Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m
Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/my-project/conf/logging.properties
-> OpenIDM version "7.1.6"
OpenIDM ready

  8. (Optional) Verify that IDM successfully connects to DS: 

    grep 31389 /path/to/opendj/logs/ldap-access.audit.json | tail -n 1 | jq .
{
  "eventName": "DJ-LDAP",
  "client": {
    "ip": "127.0.0.1",
    "port": 35874
  },
  "server": {
    "ip": "127.0.0.1",
    "port": 31389
  },
  "request": {
    "protocol": "LDAP",
    "operation": "SEARCH",
    "connId": 1,
    "msgId": 232,
    "dn": "ou=triggers,ou=scheduler,dc=openidm,dc=forgerock,dc=com",
    "scope": "one",
    "filter": "(&(&(fr-idm-json:caseIgnoreJsonQueryMatch:=/state eq \"NORMAL\")(!(fr-idm-json:caseIgnoreJsonQueryMatch:=/nodeId pr)))(objectClass=uidObject)(objectClass=fr-idm-generic-obj)(objectClass=top))",
    "attrs": [
      "objectClass",
      "uid",
      "etag",
      "createTimestamp",
      "modifyTimestamp",
      "fr-idm-json"
    ]
  },
  "transactionId": "transaction-id",
  "response": {
    "status": "SUCCESSFUL",
    "statusCode": "0",
    "elapsedTime": 1,
    "elapsedTimeUnits": "MILLISECONDS",
    "nentries": 0
  },
  "timestamp": "timestamp",
  "_id": "id"
}
Configure Two DS Repositories in an Active/Passive Deployment

With this configuration, IDM fails over to the secondary DS instance if the primary instance becomes unavailable. When the primary DS instance is restarted, that instance again becomes the target of all requests.

  1. Download DS from the ForgeRock BackStage download site and extract the .zip archive.

  2. Install two DS servers, according to the instructions in the DS Installation Guide.

    Important

    When you set up each server, specify a replicationPort and bootstrapReplicationServer so that both servers are installed as replicas. For information on these setup options, see setup in the DS Tools Reference.

    1. If you are planning to use a generic object mapping for managed users, install DS with the idm-repo profile (see Install DS as an IDM Repository).

    2. If you are planning to use an explicit object mapping for managed users, install DS with both the idm-repo and am-identity-store profiles (see Install DS as an IDM Repository and Install DS for AM Identities).

    Note

    Every DS deployment requires a deployment key and a deployment key password to secure network connections. The deployment key is a random string generated by DS software. The deployment key password is a secret string that you choose. It must be at least 8 characters long. The deployment key and password automate key pair generation and signing without storing the CA private key. For more information, see Deployment Keys in the DS Security Guide.

  3. In your IDM installation, remove the default DS repository configuration file (repo.ds.json) from your project's conf/ directory. For example: 

    cd /path/to/openidm/my-project/conf/
rm repo.ds.json

  4. Copy the external DS repository configuration file (repo.ds-external.json) to your project's conf directory and rename it repo.ds.json: 

    cp /path/to/openidm/db/ds/conf/repo.ds-external.json my-project/conf/repo.ds.json

  5. Enable IDM to trust each DS server certificate for your deployment.

    For example, in the default case, where DS servers use TLS key pairs generated using a deployment key and password, import the deployment key-based CA certificate for each server into the IDM truststore.

    You will need to give the CA certificate of the second server a different alias. 

    /path/to/opendj/bin/dskeymgr \
export-ca-cert \
--deploymentKey your-deployment-key \
--deploymentKeyPassword password \
--outputFile ds-ca-cert.pem
keytool \
-importcert \
-alias ds-ca-cert \
-keystore /path/to/openidm/security/truststore \
-storepass:file /path/to/openidm/security/storepass \
-file ds-ca-cert.pem
Owner: CN=Deployment key, O=ForgeRock.com
Issuer: CN=Deployment key, O=ForgeRock.com
...
Trust this certificate? [no]:  yes
Certificate was added to keystore

  6. Specify the connection settings from IDM to the two DS servers in the ldapConnectionFactories property of the repository configuration file (repo.ds.json).

    This example assumes that the first DS server runs on the host ds1.example.com, and the second DS server runs on the host ds2.example.com: 

    "ldapConnectionFactories": {
    "bind": {
        "connectionSecurity": "startTLS",
        "heartBeatIntervalSeconds": 60,
        "heartBeatTimeoutMilliSeconds": 10000,
        "primaryLdapServers": [{ "hostname": "ds1.example.com", "port": 31389 }],
        "secondaryLdapServers": [{ "hostname": "ds2.example.com", "port": 31389 }]
}

    Adjust the settings to match your DS server setup.

    For details about the connection settings, see the information in Gateway LDAP Connections in the DS HTTP User Guide. (IDM shares these configuration settings with the DS REST to LDAP Gateway.)

  7. Also in the repo.ds.json file, check the authentication settings: 

    "root": {
    "inheritFrom": "bind",
    "authentication": {
        "simple": { "bindDn": "uid=admin", "bindPassword": "5up3r53cr3t" }
    }
}

    Make sure that the bindDn and bindPassword match the bind details of the DS superuser.

  8. Start IDM and verify that the connection to the primary DS server is successful.

  9. (Optional) Shut down the primary DS server and verify that the failover to the secondary server occurs, as expected.

Read a different version of :