Configuring UMA Stores

AM stores information about registered resources, audit information generated when users manage access to their protected resources, pending requests, and resource labels. AM stores these items in the configuration store by default.

You can instead configure external stores for this information.

Preparing External UMA Data Stores

This section 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 for use by AM is similar for each of the different UMA-related data types. The steps to perform are as follows:

If you have not done so yet, install Directory Services.

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

Create a backend and base DN entry in the external store.
Create a user account with the minimum required privileges for AM to bind to the directory server with, and access necessary data.

Apply the relevant schema to the directory. Each type of data requires a specific set of schema LDIF files to be applied.

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`

Tip

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

This section details how to set up a DS instance to store UMA resources. Repeat the procedures in the sections below with the relevant schema files to set up a DS instance to store other types of UMA-related data.

Note

Example commands throughout this section use example values for user IDs and port numbers. When running similar commands, be sure to use appropriate values for your deployment.

Installing and Configuring Directory Services for UMA Data

The following instructions show how to download, install, and set up the Directory Services server.

To Install and Configure Directory Services for UMA Data

Download and install Directory Services.
1. Generate a DS deployment key unless you already have one:
```
$ /path/to/opendj/dskeymgr create-deployment-key --deploymentKeyPassword password
```
  Save the deployment key and its deployment password. Keep the key and the password safe, and keep the password secret. Use the same deployment key and password for all the servers in the same environment. For example, if you plan to deploy replication.
  Replication is not covered in this example.
2. DS does not include a UMA 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\
--deploymentKey deployment_key \
--deploymentKeyPassword deployment_key_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, see setup - install OpenDJ server in the Directory Services 7 Tools Reference.
  DS 7 or later does not start automatically after installation; do not start it until after you have created a backend and added the required schemas at the end of this section.

When the install has completed, create 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 \
--trustStorePasswordFile /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

Share the UMA store certificate with the AM container to prepare for TLS/LDAPS. UMA 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.
Sharing the DS Certificate with AM
1. Export the DS server certificate:
  $ /path/to/opendj/bin/dskeymgr export-ca-cert \ --deploymentKey $DEPLOYMENT_KEY \ --deploymentKeyPassword password \ --alias ds-ca-cert \ --outputFile ds-ca-cert.pem
  Note that $DEPLOYMENT_KEY is a Unix variable that contains the DS deployment key, so that it is not logged in the user's command history.
  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.
2. Import the DS certificate into the AM truststore:
  $ keytool \ -importcert \ -alias ds-ca-cert \ -file ds-ca-cert.pem \ -keystore /path/to/openam/security/keystores/truststore
For more information on configuring AM's truststore, see "Preparing a Truststore".

Creating an UMA Store Base DN

Create a base DN that AM uses to store UMA directory server data by performing the following steps:

To Create an UMA Base DN

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

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 \
--trustStorePasswordFile /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

Tip

If you are having trouble with the LDIF file, remove any line feeds in the ACI attributes.

Creating an UMA Store Bind Account

As a best practice, the use of the root uid=admin is not recommended for accessing data on the directory server. Instead, you can create a new service account, the UMA store bind account, with limited access and fewer privileges.

Create a bind account that AM uses to access the UMA directory server data by performing the following steps:

To Create and Configure an UMA Store Bind Account

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: 5up35tr0ng
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");)

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 \
--trustStorePasswordFile /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
```
Tip
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 Directory Services 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.

Creating a Schema for UMA-related Data

Once the DS installation is complete and the instance is operational, as an administrative user such as uid=admin, import the schema files required for UMA-related data. For information on the required schema files, see LDIF Files for UMA Data Stores.

To Apply the Schema for UMA-Related Data

Note

This procedure makes use of LDIF files that are shipped with the AM server.

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
Note
If you have 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.

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 \
--trustStorePasswordFile /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, see LDIF Files for UMA Data Stores.

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, perform the following procedures:

Configuring UMA Stores in AM

Tip

If you cannot find the attribute you are looking for, click on the dropdown button on the left-hand side of the tabs or use the Search box. For more information, see "AM Console Responsiveness" and "The AM Console Search Feature".

To Configure an UMA Resource Store

Resource Store properties are inherited from the defaults. For more information about inherited properties, see "Configuring Servers"

Log in to the AM console as an administrator. For example, amAdmin.
Go to Deployment > Servers > Server Name > UMA > UMA Resource Store.
- Unlock the Store Mode property and choose External Token Store.
- Unlock the Root Suffix property and enter the base DN of the store. For example, dc=uma-resources,dc=example,dc=com.
- Save your work.
Go to Deployment > Servers > Server Name > UMA > External UMA Resource Store Configuration.
- Enter the properties for the store. For information about the available settings, see "UMA Properties".
- Save your work.

To Configure an UMA Audit Store

UMA Audit Store properties are inherited from the defaults. For more information about inherited properties, see "Configuring Servers"

Log in to the AM console as an administrator. For example, amAdmin.
Go to Deployment > Servers > Server Name > UMA > UMA Audit Store.
- Unlock the Store Mode property and choose External Token Store.
- Unlock the Root Suffix property and enter the base DN of the store. For example, dc=uma-audit,dc=example,dc=com.
- Save your work.
Go to Deployment > Servers > Server Name> UMA > External UMA Audit Store Configuration.
- Enter the properties for the store. For information about the available settings, see "UMA Properties".
- Save your work.

To Configure an UMA Pending Requests Store

UMA Pending Requests Store properties are inherited from the defaults. For more information about inherited properties, see "Configuring Servers"

Go to Deployment > Servers > Server Name> UMA > Pending Requests Store.
- Unlock the Store Mode property and choose External Token Store.
- Unlock the Root Suffix property and enter the base DN of the store. For example, dc=uma-pending,dc=example,dc=com.
- Save your work.
Go to Deployment > Servers > Server Name> UMA > External Pending Requests Store Configuration.
- Enter the properties for the store. For information about the available settings, see "UMA Properties".
- Save your work.

To Configure an UMA Resource Labels Store

UMA Resource Labels Store properties are inherited from the defaults. For more information about inherited properties, see "Configuring Servers"

Log in to the AM console as an administrator. For example, amAdmin.
Go to Deployment > Servers > Server Name > UMA > UMA Resource Labels Store.
- Unlock the Store Mode property and choose External Token Store.
- Unlock the Root Suffix property and enter the base DN of the store. For example, dc=uma-labels,dc=example,dc=com.
- Save your work.
Go to Deployment > Servers > Server Name> UMA > External UMA Resource Labels Store Configuration.
- Enter the properties for the store. For information about the available settings, see "UMA Properties".
- Save your work.