AM 7.4.0

Prepare policy and application stores

This section explains how to prepare an external DS server for use as a policy or application data store.

In a new AM deployment, you can install new instances of DS for policy or application data. See Install and configure Directory Services for policy or application data.

In deployments where there is existing policy or application data, you may prefer to migrate this data from the existing location alongside the configuration data, into separate DS instances. See Migrate policy or application data to DS.

Install and configure Directory Services for policy or application data

The following instructions show how to install and set up the DS server.

Directory Services setup profiles simplify initial configuration.

Using a setup profile creates the backend, schema, bind user, and indexes required for use with policy or application data. Policy and application data have the same schema requirements as configuration data.

  1. To install DS using a setup profile, follow the steps in DS for AM Configuration Data in the Directory Services documentation.

    You must specify the same base DN value as your configuration store when using a setup profile to create a policy or application store.

    For example:

    --set am-config/baseDn:"dc=example,dc=com"

    Creating a separate DS backend for policies or applications in the configuration store isn’t supported.

  2. Share the store certificate with the AM container to prepare for TLS/LDAPS. Application and policy stores should communicate over secure connections.

    ForgeRock Directory Services 7 and later requires secure connections by default; therefore, share the DS certificate with the AM container before continuing.

    Share the DS certificate with AM

    1. Export the DS server certificate:

      $ keytool -exportcert \
-keystore /path/to/opendj/config/keystore \
-storepass:file /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 SubjectAlternativeName attribute; however, certificate hostname validation is strict. Ensure that the certificate matches the hostname (or the FQDN) of the DS server before continuing.

      Copy the ds-cert.pem file to an accessible location on the AM host.

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

  3. You have successfully installed and prepared the DS directory server for use as an external policy or application store.

    You can use the DS server instance created in these procedures for both policy and application data simultaneously. If you want to use separate DS server instances for policies and applications, repeat the previous step to create an additional external policy or application store.

    Configure AM to use the prepared DS directory servers as external policy or application stores. For details, refer to Policy and application stores.

    The bind DN of the default AM service account used to authenticate to the external store has the form:

    uid=am-config,ou=admins,Base DN

Migrate policy or application data to DS

If you are upgrading existing AM instances to use external DS instances for policy or application data, you may want to migrate the existing data into the new instances. Migrating policy or application data to a separate store lets you tune and scale dynamic data separately from more static configuration data.

This section covers the following high-level methods for migrating policy or application data to new DS instances:

Export and import DS LDIF data

This section gives an overview of migrating data to new DS instances by using the import-ldif and export-ldif commands.

The top-level steps are as follows:

  1. Install a DS instance to store policy or application data, by following the steps in Install and configure Directory Services for policy or application data.

  2. Use the export-ldif command to create an LDIF file of the structure of the new DS instance.

    For example:

    $ /path/to/opendj/bin/export-ldif \
--hostname 'config.example.com' \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--backendId cfgStore \
--ldifFile /tmp/Apps_and_or_Policies.ldif

  3. Use the export-ldif command to append your existing policy and/or application data to the previous LDIF file.

    The export-ldif command has a --includeBranch option to limit the data exported to just policy and/or application data.

    See the following commands to export application data, policy data, or both:

    • Policy and application data

    • Policy data

    • Application data

    $ /path/to/opendj/bin/export-ldif \
--hostname 'config.example.com'\
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--includeBranch o=sunamhiddenrealmdelegationservicepermissions,ou=services,dc=example,dc=com \
--includeBranch ou=AgentService,ou=services,dc=example,dc=com \
--includeBranch ou=sunEntitlementService,ou=services,dc=example,dc=com \
--includeBranch ou=sunEntitlementIndexes,ou=services,dc=example,dc=com \
--includeBranch ou=sunFMCOTConfigService,ou=services,dc=example,dc=com \
--includeBranch ou=sunFMIDFFMetadataService,ou=services,dc=example,dc=com \
--includeBranch ou=sunFMSAML2MetadataService,ou=services,dc=example,dc=com \
--includeBranch ou=sunFMWSFederationMetadataService,ou=services,dc=example,dc=com \
--backendId appData \
--appendToLdif \
--ldifFile /tmp/Apps_and_or_Policies.ldif
    $ /path/to/opendj/bin/export-ldif \
--hostname 'config.example.com'\
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--includeBranch ou=sunEntitlementService,ou=services,dc=example,dc=com \
--includeBranch ou=sunEntitlementIndexes,ou=services,dc=example,dc=com \
--includeBranch o=sunamhiddenrealmdelegationservicepermissions,ou=services,dc=example,dc=com \
--backendId appData \
--appendToLdif \
--ldifFile /tmp/Apps_and_or_Policies.ldif
    $ /path/to/opendj/bin/export-ldif \
--hostname 'config.example.com'\
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--includeBranch ou=AgentService,ou=services,dc=example,dc=com \
--includeBranch ou=sunFMCOTConfigService,ou=services,dc=example,dc=com \
--includeBranch ou=sunFMIDFFMetadataService,ou=services,dc=example,dc=com \
--includeBranch ou=sunFMSAML2MetadataService,ou=services,dc=example,dc=com \
--includeBranch ou=sunFMWSFederationMetadataService,ou=services,dc=example,dc=com \
--backendId appData \
--appendToLdif \
--ldifFile /tmp/Apps_and_or_Policies.ldif

    Replace dc=example,dc=com in the commands above with your base DN.

  4. To also export policy and/or application data from subrealms, repeat the previous step, but altered to include the path to the subrealm in the included branches.

    For example, to export data from a realm named mySubRealm, add ou=services,o=mySubRealm, into each of the included branches, as shown below:

    $ /path/to/opendj/bin/export-ldif \
--hostname 'config.example.com'\
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--includeBranch o=sunamhiddenrealmdelegationservicepermissions,<replaceable>ou=services,o=mySubRealm,</replaceable>ou=services,dc=example,dc=com \
--includeBranch ou=AgentService,<replaceable>ou=services,o=mySubRealm,</replaceable>ou=services,dc=example,dc=com \
--includeBranch ou=sunEntitlementService,<replaceable>ou=services,o=mySubRealm,</replaceable>ou=services,dc=example,dc=com \
--includeBranch ou=sunEntitlementIndexes,<replaceable>ou=services,o=mySubRealm,</replaceable>ou=services,dc=example,dc=com \
--includeBranch ou=sunFMCOTConfigService,<replaceable>ou=services,o=mySubRealm,</replaceable>ou=services,dc=example,dc=com \
--includeBranch ou=sunFMIDFFMetadataService,<replaceable>ou=services,o=mySubRealm,</replaceable>ou=services,dc=example,dc=com \
--includeBranch ou=sunFMSAML2MetadataService,<replaceable>ou=services,o=mySubRealm,</replaceable>ou=services,dc=example,dc=com \
--includeBranch ou=sunFMWSFederationMetadataService,<replaceable>ou=services,o=mySubRealm,</replaceable>ou=services,dc=example,dc=com \
--backendId appData \
--appendToLdif \
--ldifFile /tmp/Apps_and_or_Policies.ldif

    Repeat this step for each subrealm that contains application and/or policy data you want to transfer to an external store.

  5. Edit the LDIF file to include the required top-level ou=services entry. For example, after the entry for dn: dc=example,dc=com add the following:

    dn: ou=services,dc=example,dc=com
objectclass: top
objectclass: organizationalunit
objectclass: sunServiceComponent
ou: services
    This LDIF example requires a blank line before and after the content. You must replace dc=example,dc=com with your base DN value.

    The start of the resulting LDIF will resemble the following:

    dn: dc=example,dc=com
objectClass: top
objectClass: untypedObject
dc: openam
aci: (targetattr="*")(version 3.0;acl "Allow CRUDQ operations";allow (search, read, write, add, delete)(userdn = "ldap:///uid=am-config,ou=admins,dc=example,dc=com");)
aci: (targetcontrol="2.16.840.1.113730.3.4.3")(version 3.0;acl "Allow persistent search"; allow (search, read)(userdn = "ldap:///uid=am-config,ou=admins,dc=example,dc=com");)
aci: (targetcontrol="1.2.840.113556.1.4.473")(version 3.0;acl "Allow server-side sorting"; allow (read)(userdn = "ldap:///uid=am-config,ou=admins,dc=example,dc=com");)
entryUUID: 5beee9ea-1c31-3129-a8f9-c79da3102f26

dn: ou=services,dc=example,dc=com
objectclass: top
objectclass: organizationalunit
objectclass: sunServiceComponent
ou: services

dn: ou=admins,dc=example,dc=com
objectClass: top
objectClass: organizationalUnit
ou: admins
...
...

  6. Repeat the previous step to create the parent entries for any subrealms that you exported.

    For example, before the ou=admins,dc=example,dc=com line, add the following for a subrealm named mySubRealm:

    dn: o=mySubRealm,ou=services,dc=example,dc=com
objectClass: sunRealmService
objectClass: top
o: mySubRealm

dn: ou=services,o=mySubRealm,ou=services,dc=example,dc=com
objectClass: organizationalUnit
objectClass: sunServiceComponent
objectClass: top
ou: services

    Note that the example above requires a blank line both before and after, and you must replace dc=example,dc=com with your base DN value.

    The start of the resulting LDIF will resemble the following:

    dn: dc=example,dc=com
objectClass: top
objectClass: untypedObject
dc: openam
aci: (targetattr="*")(version 3.0;acl "Allow CRUDQ operations";allow (search, read, write, add, delete)(userdn = "ldap:///uid=am-config,ou=admins,dc=example,dc=com");)
aci: (targetcontrol="2.16.840.1.113730.3.4.3")(version 3.0;acl "Allow persistent search"; allow (search, read)(userdn = "ldap:///uid=am-config,ou=admins,dc=example,dc=com");)
aci: (targetcontrol="1.2.840.113556.1.4.473")(version 3.0;acl "Allow server-side sorting"; allow (read)(userdn = "ldap:///uid=am-config,ou=admins,dc=example,dc=com");)
entryUUID: 5beee9ea-1c31-3129-a8f9-c79da3102f26

dn: ou=services,dc=example,dc=com
objectclass: top
objectclass: organizationalunit
objectclass: sunServiceComponent
ou: services

dn: o=mySubRealm,ou=services,dc=example,dc=com
objectClass: sunRealmService
objectClass: top
o: mySubRealm

dn: ou=services,o=mySubRealm,ou=services,dc=example,dc=com
objectClass: organizationalUnit
objectClass: sunServiceComponent
objectClass: top
ou: services

dn: ou=admins,dc=example,dc=com
objectClass: top
objectClass: organizationalUnit
ou: admins
...
...

  7. Use the import-ldif command to add the updated LDIF data to the new instance. For example:

    $ /path/to/opendj/bin/import-ldif \
--hostname external.example.com \
--port 4444 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--backendId cfgStore \
--ldifFile /tmp/Apps_and_or_Policies.ldif

  8. Configure AM to use the new store for policy and/or application data, by following the steps in Configure policy and application stores.

For more information and the specific steps for importing and exporting data by using LDIF, see Data Storage in the DS documentation.

Back up and restore a DS instance

This section gives an overview of migrating data to new DS instances by using the DS backup and restore commands.

The dsbackup command replaced these commands in DS 7.

The top-level steps are as follows:

  1. Use the backup command to make a backup copy of the existing configuration store.

  2. Install a DS instance to store the policy and/or application data, by following the steps in Install and configure Directory Services for policy or application data.

    The DS instance MUST have the same base DN, and backend name, as the instance from which the backup was created.

  3. Use the restore command to restore your policy and/or application data to the new store.

  4. Configure AM to use the new store for policy and/or application data, by following the steps in Configure policy and application stores.

For more information and the specific steps for performing backup and restore operations in DS, see Backup and Restore, and Initialize from backup in the DS documentation.

Copyright © 2010-2024 ForgeRock, all rights reserved.