Secure administrative access

Some deployments may need only one administrator. For example, deployments whose configuration never changes in production. If your deployment requires more than one administrative user, it makes sense to limit what individual administrators can do.

This approach reduces the risk of accidental or intentional abuse of power, and lets you divide work between different teams and audit configuration changes.

To secure administrative access to AM make sure you:

Understand and secure the amAdmin user.
Know how to delegate realm privileges to groups of users.
Secure access to the AM admin UI.
Secure access to the tools you use to configure AM.

The `amAdmin` user

The AM installation process creates an amAdmin administrative account. This account has unrestricted access to the AM configuration, including the ability to create new users and augment their list of administrative privileges.

You can’t delete the amAdmin account because it’s hard-coded in the source code of several files. The amAdmin user is defined in AM’s configuration, so it’s always available to AM even if the identity stores become unavailable. Because this account isn’t an identity defined in an identity store, it can’t use any capabilities that require a user profile, such as device match or push notifications.

The advanced server property com.sun.identity.authentication.super.user defines the DN of the amAdmin user. You can change this property to the DN of a regular user that exists in any identity store configured in AM.

Changing the name of the amAdmin user might affect functionality in some areas where the name is hardcoded. Make sure you test a change like this before deploying it in production.

Secure the amAdmin user with a strong password and restrict its use as much as possible. Delegate realm administration privileges to regular users instead.

Change the amAdmin password

This topic describes how to use the AM admin UI to change the amAdmin user.

A better way to secure the amAdmin password is to Store the amAdmin password in a secret store.

Follow these steps to change the amAdmin password:

In the AM admin UI, click on the user avatar () in the top right corner.
Click Change Password.
Enter the current password in the Current password field.
Enter the new password in the New password and Confirm new password fields.
Save your work.

If your deployment has multiple AM servers, the new password replicates across all servers.

Store the amAdmin password in a secret store

Using a secure secret store is more secure than storing the amAdmin password in the configuration.

The secret store you use for the amAdmin password is a special secret store and is not visible in the AM admin UI. If you store the amAdmin password in a secret store, you can’t change the password in the AM admin UI unless you remove the secret configuration.
When you remove the secret configuration, the amAdmin password reverts to what it was before you configured the secret.
You must salt and hash an amAdmin password stored in a secret. Encryption is optional but highly recommended.

To store the amAdmin password in a secret store:

Create a new password then salt and hash it using a script similar to the following. The comments in the script indicate the salt and hash requirements:

#!/usr/bin/env python3
import getpass
import os
import sys
import struct
import hashlib
import base64

if os.isatty(0):
   pwd = getpass.getpass()
   cnf = getpass.getpass('Confirm: ')
else:
   pwd = sys.stdin.buffer.readline().decode('utf-8').strip()
   cnf = pwd

if pwd != cnf:
   sys.exit("Password and confirmation don't match")

## Create some random bytes as the salt
salt = os.urandom(20)

## Hash the salt and the new password with a SHA-512 function
h = hashlib.sha512()
h.update(salt)
h.update(pwd.encode('utf-8'))
hash = h.digest()

## Concatenate the salt length as a single byte, the raw salt, and the hashed password
packed = struct.pack("B20s64s", 20, salt, hash)

## Generate the final hashed string
outform = "{SSHA-512}" + base64.b64encode(packed).decode('ascii')
print(outform)

Optionally, encrypt the hashed string with the AM encryption password or with a secret stored in the Google Cloud Key Management Service (KMS).

Encrypt with the AM encryption password:
1. Log in to the AM admin UI as an administrative user.
2. Go to https://am.example.com:8443/am/encode.jsp and paste the hashed string in the field.
  
  Alternatively, use the ampassword command to encrypt the password.
  
  Copy the encrypted password string.
3. Go to Configure > Server Defaults > Advanced.
4. Set the org.forgerock.openam.secrets.special.user.passwords.format advanced server property to ENCRYPTED_PLAIN.
Encrypt with a secret stored in the Google Cloud KMS:
Prerequisites
You need a Google Cloud Platform account with a project that includes the following:
- A key ring containing the secrets that you’ll use to encrypt the hash of the password of the amAdmin user.
  
  You can configure the key ring in any Google Cloud location.
- A service account that AM will use to connect to the project.
Learn more in the Google Key Management Service documentation and Google’s Getting Started with Authentication.

You can find information on configuring AM to connect to the Google Cloud KMS with the service account in Configure Google service account credentials.
1. Check if you already have a Google Cloud KMS secret for decrypting.
  
  Go to Configure > Server Defaults > Advanced, and check if the org.forgerock.openam.secrets.googlekms.decryptionkey advanced server property is configured.
  
  If the property is configured, you don’t need to create another key.
  
  If the property isn’t configured, log in to your Google Cloud dashboard and create a secret of one of the following types in the key ring of your choosing:
  - Symmetric encrypt/decrypt
  - Asymmetric decrypt
2. Use the secret you identified or created in the previous step to encrypt the hashed string.
  
  You can use the gcloud tool included in Google Cloud’s SDK to encrypt the string. The tool creates a binary file with the encrypted secret, but AM does not support secrets in binary format. To work around this, base64-encode the encrypted secret. For example:
  gcloud kms encrypt \ --plaintext-file=./amadmin_password_hashed_string.txt \ --ciphertext-file=- \ --project=my_project_ID \ --location=my_location \ --keyring=my_keyring_for_AM \ --key=my_key_for_decrypting_secrets_in_AM \| base64 > encrypted_hash_of_amadmin_password.enc
3. In the AM admin UI, go to Configure > Server Defaults > Advanced.
4. (Optional) If unset, set the org.forgerock.openam.secrets.googlekms.decryptionkey advanced server property to the fully qualified resource ID of the Google Cloud KMS secret that you used to encrypt the hash string. For example:
  projects/my_project_ID/locations/my_location/keyRings/my_keyring_for_AM/cryptoKeys/my_key_for_decrypting_secrets_in_AM
  Learn how to find the key ID in Object Hierarchy in the Google Cloud KMS documentation.
5. Set the org.forgerock.openam.secrets.special.user.passwords.format advanced server property to GOOGLE_KMS_ENCRYPTED.
Leave the hashed string unencrypted (not recommended)

Ensure that the password is randomly generated and has high entropy before continuing.
1. In the AM admin UI, go to Configure > Server Defaults > Advanced.
2. Set the org.forgerock.openam.secrets.special.user.passwords.format advanced server property to PLAIN.

If you don’t have access to the AM admin UI, you can add the required property to the CATALINA_OPTS variable. For example, for Apache Tomcat, add the following to the $CATALINA_BASE/bin/setenv.sh file:

export CATALINA_OPTS="$CATALINA_OPTS -Dorg.forgerock.openam.secrets.special.user.passwords.format=PLAIN"

Map the encrypted secret to the secret label that you will use. Perform one of the following:

Save the encrypted password to a file in the special secret store directory:

$ echo -n salted_encrypted_password > /path/to/am/security/secrets/userpasswords/password.amadmin

The default location of the special secret store is /path/to/am/security/secrets/userpasswords. To change it, configure the org.forgerock.openam.secrets.special.user.passwords.dir advanced server property.

Create an operating system variable named PASSWORD_AMADMIN and set its value to the encrypted password. Make the variable available to the user running the container where AM runs; for example, add it to the user’s bash.profile file.
Create a Java system variable called password.amadmin and set its value to the encrypted password. Make the variable available to the container where AM runs.

For example, if using Apache Tomcat, add it to $CATALINA_BASE/bin/setenv.sh as follows:
```
export password.amadmin="y3GVzNP5Z3$EXZQHX75aRE!8FjN"
```

AM caches this special secret after it’s been read. The expiry time of the cache is 900 seconds (15 minutes) by default. To change the expiry time, set the org.forgerock.openam.secrets.special.user.secret.refresh.seconds advanced server property.

For increased security, rotate this secret periodically. Learn more in Map and rotate secrets.

Delegate privileges

The amAdmin user can change any setting in AM’s configuration, but giving that power to each of your administrative users is not ideal.

In AM, you do not create administrative users. You create regular users and delegate realm administration privileges to a group they belong to. For example, you can create a group of users that are only allowed to make REST calls to endpoints in a specific realm, or a group of users that have full administrative privileges for a particular realm.

This approach of splitting responsibilities lowers the risk of accidental or intentional abuse.

Because users with delegated administration privileges are regular users in the identity store, they can use any form of multi-factor authentication.

You can also delegate other kinds of privileges, such as making REST calls to realms for policy evaluation, modifying policies, and more.

Realm privileges available for delegation

The following table describes privileges that you can assign in the AM admin UI or by using the ssoadm add-privileges command:

Privileges
Privilege as it appears in the AM admin UI	Privilege name to use with the `ssoadm add-privileges` command	Notes
Read and write access to all realm and policy properties	`Realm Admin`	Assign this privilege to administrators in order to let them modify or read any part of an AM realm. Use this privilege when you do not require granularity in your delegation model. All other AM privileges are included with this privilege. Administrators using the AM admin UI must have this privilege.
Read and write access to all configured agents	`Agent Admin`	Provides access to centralized agent configuration; subset of the `RealmAdmin` privilege.
Read and write access to all log files	`Log Admin`	Subset of the `Realm Admin` privilege.
Read access to all log files	`Log Read`	Subset of the `Realm Admin` privilege.
Write access to all log files	`Log Write`	Subset of the `RealmAdmin` privilege.
Read and write access to all federation metadata configurations	`Federation Admin`	Subset of the `Realm Admin` privilege.
REST calls for reading realms	`Realm Read Access`	Subset of the `Realm Admin` privilege.
Read and write access only for policy properties, including REST calls	`Policy Admin`	Assign this privilege to policy administrators in order to let them modify or read any part of the AM policy configuration. This privilege lets an administrator modify or read all policy components: policies, applications, subject types, condition types, subject attributes, and decision combiners. All other AM privileges that affect policy components are included with this privilege. Subset of the `Realm Admin` privilege.
REST calls for policy evaluation	`Entitlement Rest Access`	Subset of the `Realm Admin` and `Policy Admin` privileges.
REST calls for reading policies	`Privilege Rest Read Access`	Subset of the `Realm Admin` and `Policy Admin` privileges.
REST calls for managing policies	`Privilege Rest Access`	Subset of the `Realm Admin` and `Policy Admin` privileges.
REST calls for reading policy applications	`Application Read Access`	Subset of the `Realm Admin` and `Policy Admin` privileges.
REST calls for modifying policy applications	`Application Modify Access`	Subset of the `Realm Admin` and `Policy Admin` privileges.
REST calls for reading policy resource types	`Resource Type Read Access`	Subset of the `Realm Admin` and `Policy Admin` privileges.
REST calls for modifying policy resource types	`Resource Type Modify Access`	Subset of the `Realm Admin` and `Policy Admin` privileges.
REST calls for reading policy application types	`Application Types Read Access`	Subset of the `Realm Admin` and `Policy Admin` privileges.
REST calls for reading environment conditions	`Condition Types Read Access`	Subset of the `Realm Admin` and `Policy Admin` privileges.
REST calls for reading subject conditions	`Subject Types Read Access`	Subset of the `Realm Admin` and `Policy Admin` privileges.
REST calls for reading decision combiners	`Decision Combiners Read Access`	Subset of the `Realm Admin` and `Policy Admin` privileges.
REST calls for reading subject attributes	`Subject Attributes Read Access`	Subset of the `Realm Admin` and `Policy Admin` privileges.
REST calls for modifying session properties	`Session Property Modify Access`	Subset of the `Realm Admin` and `Policy Admin` privileges.

These steps describe how to create a user and assign administrative privileges using the AM admin UI. You can also delegate privileges over REST. Learn more in How do I add privileges to identity groups in PingAM?.

Go to the realm for which you want to delegate privileges.

For example, go to Realms > Top Level Realm.

Delegating administrative privileges in the Top Level Realm allows members of the group full access to the AM instance. Administration privileges in any other realm allows the group to access administrative functionality only in that realm, and any child realms.

Go to Identities > Groups and click the name of the group to which you intend to grant access.

If you do not have a group yet, create one.

The All Authenticated Identities virtual group lets you assign privileges to any identity that has a valid session in AM. Use it with caution, since not every identity authenticates to AM by using strong authentication.
Choose the administrative privileges to delegate for the realm:
1. To grant users in the group access to the AM admin UI for the realm, click Realm Admin.
  
  Administrators can use the AM admin UI as follows:
  - Delegated administrators with the Realm Admin privilege can access full administration console functionality within the realms they can administer.
  - Users with lesser privileges, such as the Policy Admin privilege, can not access the AM admin UI, but can use REST to create and manage the functionality for which they have privileges.
  - Both the top-level administrator (such as amAdmin) and delegated administrators in the Top Level Realm with the Realm Admin privilege have access to full console functionality in all realms and can access AM’s global configuration.
2. To grant users in the group access to REST endpoints, choose the required privileges from the list.
Learn more about the available privileges in Realm privileges available for delegation.
Click Save Changes.

To enable delegated subrealm administrators to invalidate sessions, you must add an attribute to their entry in the datastore, as described in the following procedure:

Let delegated subrealm administrators invalidate sessions

Create an LDIF file that modifies the distinguished name entry of the subrealm administrator, adds the iplanet-am-session-destroy-sessions attribute, and sets its value to the subrealm’s DN.

In the following example, the delegated administrator is named subRealmAdmin and the subrealm is called mySubRealm:
```
dn: uid=subrealmadmin,ou=people,dc=am,dc=example,dc=com
changetype: modify
add: objectClass
objectClass: iplanet-am-session-service
-
add: iplanet-am-session-destroy-sessions
iplanet-am-session-destroy-sessions: o=mysubrealm,ou=services,dc=am,dc=example,dc=com
```
All values in the LDIF must be in lowercase, even if the subrealm or administrator name is not.

Run the ldapmodify command included with DS to apply the LDIF file to the user datastore.

For example:

$ /path/to/opendj/bin/ldapmodify \
--hostname 'ds.example.com' \
--port 1636  \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
/path/to/ldif.file
# Processing MODIFY request for uid=subrealmadmin,ou=people,dc=am,dc=example,dc=com
# MODIFY operation successful for DN uid=subrealmadmin,ou=people,dc=am,dc=example,dc=com

The delegated realm administrator will now be able to invalidate sessions created in the subrealm.

Delegate agent profile creation

If you want to create agent profiles when installing web or Java agents, then you need the credentials of an AM user who can read and write agent profiles.

You can use the AM administrator account when creating agent profiles. If you delegate web or Java agent installation, then you might not want to share AM administrator credentials with everyone who installs agents.

Follow these steps to create agent administrator users for a realm:

In the AM admin UI, go to Realms > Realm Name > Identities.
On the Groups tab, click Add Group and create a group for agent administrators.
On the Privileges tab, choose Realm Admin.
Click Save Changes.
Go to Realms > Realm Name > Identities.

On the Identities tab, create as many agent administrator users as needed.
For each agent administrator user, edit the user profile.

On the Groups tab of the user profile, add the user to agent profile administrator group.
Click Save Changes.
Provide each system administrator who installs web or Java agents with their agent administrator credentials.

When installing Java agents with the --custom-install option, the system administrator can choose the option to create the profile during installation, and then provide the agent administrator user name and the path to a read-only file containing the agent administrator password. For silent installs, you can add the --acceptLicense option to auto-accept the software license agreement.

Secure access to the admin UIs

AM provides end-user pages, located at am/XUI, and an administration UI, located at am/ui-admin.

Consider the following points to secure the AM admin UI:

Limit access to the AM admin UI.

For example, allow access to the AM admin UI URI only to inbound connections from a specific network, or create a denylist or an allowlist with the endpoints the AM admin UI uses. Learn more in How do I remove admin UI access in PingAM?.
Make sure administrative users present strong credentials when logging in to the AM admin UI.

By default, users that log in to the AM admin UI use the tree configured in the Organization Authentication Configuration property for the realm. To locate this property, go to Realms > Realm Name > Authentication > Settings > Core.

Make sure you change the default for all realms, including the Top Level Realm.

The API Explorer is enabled by default. For security reasons, it is strongly recommended that you disable it in production environments.

To disable the API Explorer, go to Configure > Global Services > REST APIs, and select Disabled in the API Descriptors drop-down list.

Secure access to the admin tools

AM provides the following administrative tools that you can use instead of the administrative console to configure AM: Amster and ssoadm.

Don’t install the tools on the same server as AM, so that administrators don’t require a local system account on that server.

Also, make sure you create a username/password tree specifically for tools, so that you can track it easily in your logs.

Review the following information to secure access to the tools:

By default, users logging in through Amster or ssoadm use the tree configured in the Administrator Authentication Configuration property for the realm.

To locate this property, go to Realms > Realm Name > Authentication > Settings > Core.
Amster:
- If the administrative users connect to AM using interactive login, make sure they present strong credentials.
- If the administrative users connect to AM using private key connections, make sure you create your own keys and share them with AM.
  
  Learn more in Amster User Guide.
ssoadm
- Make sure your administrative users present strong credentials.
- The ssoadm command requires that you provide the password of the administrative user stored in cleartext in a file.
  
  Make sure the file is read-only for its owner.

PingAM 8.0.0

Secure administrative access

The amAdmin user

Change the amAdmin password

Store the amAdmin password in a secret store

Delegate privileges

Let delegated subrealm administrators invalidate sessions

Delegate agent profile creation

Secure access to the admin UIs

Secure access to the admin tools

The `amAdmin` user