--- title: Prepare policy and application stores description: This section explains how to prepare a DS server for use as an external policy or application data store. component: pingam version: 7.3 page_id: pingam:setup-guide:prepare-policy-and-application-store canonical_url: https://docs.pingidentity.com/pingam/8.1/setup/prepare-policy-and-application-store.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Setup & Configuration", "Policy", "Application Store"] section_ids: prepare-ds-for-policy-and-application: Install and configure Directory Services for policy and/or application data migrate-policy-and-application-data: Migrate policy and/or application data to DS migrate-data-ldif: Export and import DS LDIF data migrate-data-backup-restore: Back up and restore a DS instance --- # 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](#prepare-ds-for-policy-and-application). 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](#migrate-policy-and-application-data). ## 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](https://docs.pingidentity.com/pingds/7.3/install-guide/profile-am-config.html) 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. > **Collapse: Share the DS certificate with AM** > > * 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](https://docs.pingidentity.com/pingds/7.3/security-guide/pki.html#about-deployment-ids). > > Use the `dskeymgr` command to export the CA certificate: > > ```bash > $ /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: > > ```bash > $ 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](../install-guide/prepare-trust-store.html). 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](setting-up-data-stores.html). 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](#migrate-data-ldif) * [Back up and restore a DS instance](#migrate-data-backup-restore) ### 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](#prepare-ds-for-policy-and-application). 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 ```bash $ /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 ``` ```bash $ /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 ``` ```bash $ /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: ```bash $ /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,o=mySubRealm,ou=services,dc=example,dc=com \ --includeBranch ou=AgentService,ou=services,o=mySubRealm,ou=services,dc=example,dc=com \ --includeBranch ou=sunEntitlementService,ou=services,o=mySubRealm,ou=services,dc=example,dc=com \ --includeBranch ou=sunEntitlementIndexes,ou=services,o=mySubRealm,ou=services,dc=example,dc=com \ --includeBranch ou=sunFMCOTConfigService,ou=services,o=mySubRealm,ou=services,dc=example,dc=com \ --includeBranch ou=sunFMIDFFMetadataService,ou=services,o=mySubRealm,ou=services,dc=example,dc=com \ --includeBranch ou=sunFMSAML2MetadataService,ou=services,o=mySubRealm,ou=services,dc=example,dc=com \ --includeBranch ou=sunFMWSFederationMetadataService,ou=services,o=mySubRealm,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: ```ldif 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: ```ldif 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`: ```ldif 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: ```ldif 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: ```bash $ /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](setting-up-policy-and-app-stores.html). You can find more information and the specific steps for importing and exporting data by using LDIF in [Data Storage](https://docs.pingidentity.com/pingds/7.3/config-guide/import-export.html) 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](#prepare-ds-for-policy-and-application). 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](setting-up-policy-and-app-stores.html). For more information and the specific steps for performing backup and restore operations in DS, see [Backup and Restore](https://docs.pingidentity.com/pingds/7.3/maintenance-guide/backup-restore.html), and [Initialize from backup](https://docs.pingidentity.com/pingds/7.3/config-guide/replication.html#init-repl-backup) in the DS documentation.