PingAM 7.5.0

Configure policy and application stores

Setting up an external policy or application store involves the following steps:

  1. Configuring the connection between AM and the directory server.

  2. Enabling a realm to use the newly configured directory server.

Connect AM to a policy or application store

  1. These steps assume you have installed and configured DS as a policy or application store.

  2. In the AM admin UI, go to Configure > Global Services > External Data Stores.

  3. On the Secondary Configurations tab, click Add a Secondary Configuration.

  4. Complete the form as follows:

    1. In the Name field, enter a name for the data store; for example, myPolicyStore.

    2. If you’re ready to use this data store, select Enabled.

      If you enable an external data store configuration, AM checks that it can connect to the server when you save the configuration.

      You can’t select a data store configuration for use (at the realm or global level) until you enable it.

      If you’re configuring mTLS authentication to the data store, don’t enable the connection until you have added an mTLS Secret Label Identifier and the corresponding entry in the secret store. You can’t do this on the create page. You must save the configuration, then edit it to add the mTLS Secret Label Identifier.
    3. In the Host Urls field, enter one or more connection strings. The format for each connection string is HOST:PORT; for example policies1.example.com:636 or applications1.example.com:636.

      AM uses the first connection string in the list unless the server is unreachable. In this case, it tries the next connection strings in the order in which they’re defined.

    4. Enter the Bind DN and Bind Password of the service account AM uses to authenticate to the data store.

    5. Select Use SSL to connect to the directory server over SSL.

    6. Select mTLS Enabled to authenticate to the directory server using mTLS instead of a bind DN and password.

      If you enable mTLS, you must also:

      • Set Use SSL to true.

      • Set secure ports in the Host Urls property.

      • Configure the directory server and mappings for mTLS, as described in mTLS for policy and application stores.

      • Set an mTLS Secret Label Identifier after you save the configuration. (Refer to step 6 of this procedure.)

      AM ignores the values of the Bind DN and Bind Password when mTLS Enabled is true.

    7. Specify whether the directory servers you’re using as application and policy stores use affinity load balancing, rather than a single primary directory instance in an active/passive deployment.

      If you enable this option, specify each of the directory server instances that form the affinity deployment in the Host Urls field.

  5. To save your changes, click Create.

    If the configuration is Enabled, AM attempts to connect to the data store using the specified settings, saves the connection, and makes it available for use as a policy or application store.

    If the connection is unsuccessful, AM logs an error: Failed to load resource: the server responded with a status of 400 ().

    On successful connection, AM attempts to change the schema and structure of the external directory server. If the specified Bind DN property doesn’t have permission to change the schema and structure, you must apply the required settings manually. For details, refer to Prepare external stores.

    You can select an external data store for use at the global or realm level only when it’s Enabled.
  6. If you enabled mTLS authentication to the data store, edit the configuration to set an mTLS Secret Label Identifier.

    To edit the connection settings:

    1. Click the Secondary Configuration tab and click the name of the data store configuration.

    2. Add an mTLS Secret Label Identifier.

      AM uses this identifier to create a specific secret label for this policy or application store. It uses the secret label to map to the mTLS certificate in the secret store.

      The generated secret label takes the form am.external.datastore.identifier.mtls.cert, where identifier is the value of mTLS Secret Label Identifier. You can only view and map the secret label after you have set the identifier.

      The identifier can only contain alphanumeric characters (a-z, A-Z, 0-9) and periods (.). It can’t start or end with a period.

      All LDAP servers configured for this policy or application store share the same secret label identifier.

    3. Click Save Changes.

  7. Repeat these steps for additional policy or application stores.

Configure a realm to use a policy or application store

Changing the policy or application store will cause any existing policies or applications to become unavailable to the realm.

Either recreate the policies or applications manually, or use Amster to export the existing instances, then import them back after changing the stores.

  1. In the AM admin UI, go to Realms > Realm name Services.

  2. Configure the External Data Stores service in the realm:

    1. If the External Data Stores service has not yet been added to the realm, click Add a Service, and select External Data Stores.

    2. If the External Data Stores service has already been added to the realm, click External Data Stores to edit the configuration.

  3. On the External Data Stores page, select the name of the store to use as the Policy Data Store and/or Application Data Store, and click Save Changes.

    If you choose the Default Datastore option for either property, AM will use the configuration data store that was specified during installation.

    Changes take effect immediately. New policies or applications are created in the configured data store.

Remove a policy or application store

Follow these steps to remove a policy or application store from a realm, and to delete the store from the AM configuration.

You can’t remove a policy or application store a realm is currently using.
  1. For each realm that’s using the store, in the AM admin UI, go to Realms > Realm Name > Services > External Data Stores, and change each of the drop-down menus to either Default Datastore, or an alternative data store.

    Save your changes.

  2. Go to Configure > Global Services > External Data Stores > Secondary Configurations. Click the name of the store to remove, and click the delete icon.

    If the data store is still in use, AM returns the following error message:

    Unable to modify data store instance because it is referenced by the data store service of realm /Realm Name
    Error message when removing data store.

    In this case, repeat the first step to remove the unwanted store from the listed realm, then repeat this step.