PingAM 7.5.1

Prepare external UMA data stores

This page explains how to prepare DS instances as external UMA data stores. You can create separate DS instances to store the following UMA-related data:

  • Resources

  • Resource labels

  • UMA audit messages

  • Pending requests

The procedure for preparing external DS instances is similar for each of the UMA-related data types. The steps to perform are as follows:

  1. If you haven’t already done so, install PingDS.

  2. As an administrative user, for example, uid=admin:

    1. Create a backend and base DN entry in the external store.

    2. Create a user account with the minimum required privileges. This user lets AM bind to the directory server, and access necessary data.

    3. Apply the relevant schema to the directory.

      Each data type requires a specific set of LDIF schema files.

      LDIF files for UMA data stores
      Data Store LDIF Files

      Resources

      */path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_uma_resource_sets.ldif

      Resource labels

      */path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_uma_labels_schema.ldif

      */path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_uma_resource_set_labels.ldif

      UMA audit messages

      */path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_uma_audit.ldif

      Pending requests

      */path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_uma_pending_requests.ldif

You can use a single external DS instance with multiple backend configurations to store each of the UMA-related data types. Change the steps in the sections below to apply the backends, schema, and administrative accounts to a single DS instance.

This page shows how to set up a DS instance to store UMA resources. Repeat these procedures with the relevant schema files to set up a DS instance to store other types of UMA-related data.

The commands in this section use example values for user IDs and port numbers. Adjust the values to match your deployment.

Install and configure PingDS for UMA data

  1. Download and install PingDS.

    • Generate a DS deployment ID, unless you already have one:

      $ /path/to/opendj/dskeymgr create-deployment-id --deploymentIdPassword password
deployment-id

      Save the deployment ID and deployment ID password, and keep the password secret. Use the same deployment ID and password for all servers in the same environment; for example, if you use replicated DS servers. Replication is not covered in this example.

    • DS doesn’t provide an UMA setup profile; create an example DS UMA server by providing the parameters in a single setup command. For example:

      $ /path/to/opendj/setup \
--instancePath '/path/to/opendj' \
--serverId uma-resource-server\
--deploymentId deployment-id \
--deploymentIdPassword deployment-id-password \
--rootUserDN uid=admin \
--rootUserPassword str0ngAdm1nPa55word \
--hostname uma-rs.example.com \
--adminConnectorPort 4444 \
--ldapPort 1389 \
--enableStartTls \
--ldapsPort 1636 \
--httpsPort 8443 \
--acceptLicense

      For additional options for the setup command, refer to setup in the PingDS 7.5.0 Tools Reference.

      DS doesn’t start automatically after installation; don’t start the server until you have created a backend and added the required schemas at the end of this section.

  2. When the install has completed, create a backend for UMA resource data, named umaRsStore, and prepare for a base DN of dc=uma-resources,dc=example,dc=com:

    $ /path/to/opendj/bin/dsconfig create-backend \
--hostname 'uma-rs.example.com' \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--backend-name umaRsStore \
--set base-dn:dc=uma-resources,dc=example,dc=com \
--set enabled:true \
--type je \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--offline
The JE Backend was created successfully

  3. Share the UMA store certificate with the AM container to prepare for TLS/LDAPS. AM must connect to UMA stores over secure connections.

    DS is configured to require secure connections by default. Share the DS certificate with the AM container before continuing.

    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.

      Use the dskeymgr command to export the CA certificate:

      $ /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:

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

Create an UMA store base DN

  1. Create an LDIF file to add the base DN to the UMA store, and save the file as add-uma-base-dn.ldif:

    dn: dc=uma-resources,dc=example,dc=com
changetype:add
objectClass: top
objectClass: domain
dc: uma-resources

  2. Apply the LDIF file to the DS instance by using the ldapmodify command:

    $ /path/to/opendj/bin/ldapmodify \
--hostname 'uma-rs.example.com' \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--continueOnError \
--offline \
add-uma-base-dn.ldif
# ADD operation successful for DN dc=uma-resources,dc=example,dc=com
    If you are having trouble with the LDIF file, remove any line feeds in the ACI attributes.

Create an UMA store bind account

As a best practice, don’t use the root uid=admin to access data on the directory server. Instead, create a new service account, the UMA store bind account, with limited access and fewer privileges.

  1. Create an LDIF file to add the bind account to the UMA store, and save the file as add-uma-bind-account.ldif.

    When AM connects as the bind account to store the UMA-related data, it requires read, write, persistent search, and server-side sorting access privileges. You add these privileges by setting access control instructions (ACIs) on the base distinguished name (DN) entry you created in the previous step (for example, dc=uma-resources,dc=example,dc=com).

    The following is an example of a suitable add-uma-bind-account.ldif LDIF file:

    dn: ou=admins,dc=uma-resources,dc=example,dc=com
objectclass: top
objectclass: organizationalUnit
ou: admins

dn: uid=am-uma-bind-account,ou=admins,dc=uma-resources,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: am-uma-bind-account
sn: am-uma-bind-account
uid: am-uma-bind-account
userPassword: {ds_bind_password}
aci: (targetattr="*")(version 3.0; acl "Allow CRUDQ operations"; allow (search, read, write, add, delete)(userdn = "ldap:///uid=am-uma-bind-account,ou=admins,dc=uma-resources,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-uma-bind-account,ou=admins,dc=uma-resources,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-uma-bind-account,ou=admins,dc=uma-resources,dc=example,dc=com");)

  2. Apply the LDIF file to the DS instance by using the ldapmodify command:

    $ /path/to/opendj/bin/ldapmodify \
--hostname 'uma-rs.example.com' \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--continueOnError \
--offline \
add-uma-bind-account.ldif
# ADD operation successful for DN uid=am-uma-bind-account,ou=admins,dc=uma-resources,dc=example,dc=com
    If you are having trouble with the LDIF file, remove any line feeds in the ACI attributes.

    The am-uma-bind-account account can now connect to the PingDS instance. Note that you must use the full distinguished name of the account when binding, for example uid=am-uma-bind-account,ou=admins,dc=uma-resources,dc=example,dc=com, with the configured password, for example 5up35tr0ng.

Create a schema for UMA-related data

When the DS instance is installed and operational, import the schema files required for UMA-related data. You must do this as an administrative user, such as uid=admin. For information on the required schema files, see LDIF files for UMA data stores.

These steps use the LDIF files provided with AM.

  1. Replace the @SM_CONFIG_ROOT_SUFFIX@ variable in the LDIF files with the base DN you configured in the directory server.

    For example, dc=uma-resources,dc=example,dc=com.

    Depending on the UMA-related data type you will store in this directory server, replace the variable in the following LDIF files:

    • /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_uma_audit.ldif

    • /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_uma_resource_sets.ldif

    • /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_uma_resource_set_labels.ldif

    • /path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_uma_pending_requests.ldif

    If you’ve previously edited the files to replace the variables, replace those root entry values with the new UMA directory server root entries. For example, replace occurrences of dc=cts,dc=example,dc=com with dc=uma-resources,dc=example,dc=com.

  2. Apply the required LDIF files to the store by using the ldapmodify command.

    The following applies the schema required for storing resources:

    $ /path/to/opendj/bin/ldapmodify \
--hostname 'uma-rs.example.com' \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--continueOnError \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--offline \
/path/to/tomcat/webapps/openam/WEB-INF/template/ldif/opendj/opendj_uma_resource_sets.ldif
# ADD operation successful for DN ou=resource_sets,dc=uma-resources,dc=example,dc=com

    For more information on the required LDIF files, refer to LDIF files for UMA data stores.

  3. After applying all the required LDIF files, start the DS server.

    $ /path/to/opendj/bin/start-ds

    The DS instance is now ready to store UMA resources. To set up additional DS instances for other UMA-related data repeat the steps above, specifying the relevant schema LDIF files.

    To configure AM to use the external DS instances to store UMA-related data, refer to Configure external UMA stores.