AM 7.3.1

Prepare policy and application stores

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

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

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

Install and configure Directory Services for policy and/or application data

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

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

Using a setup profile creates the backend, schema, bind user, and indexes required for use with policy and/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 and/or applications in the configuration store is not supported.

  2. Share the store certificate with the AM container to prepare for TLS/LDAPS. Application and policy 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.

    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 instance created in these procedures for both policy and application data simultaneously. To have separate instances for policies and applications, repeat the previous step to create an additional external policy or application store.

    Proceed to configuring AM to use the prepared DS directory servers as external policy or application stores, see 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 and/or application data to DS

If you are upgrading existing AM instances to use external DS instances for policy and/or application data, you may want to migrate that existing data into the new instances. Migrating policy and/or application data to a separate store allows tuning and scaling of the more dynamic data, separately from the more static nature of configuration data.

This section covers the following high-level methods for migrating policy and/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 the policy and/or application data, by following the steps in Install and configure Directory Services for policy and/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

    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: 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 Set up 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 and/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 Set up 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.