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 (Amster and the ssoadm command).

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. The steps differ depending on whether you’re using an external configuration store or the embedded DS configuration store (evaluation deployments only).

A better way to secure the amAdmin password, regardless of the configuration store, is to Store the amAdmin password in a secret store.

Change the amAdmin password (external configuration store)

If AM is configured to use an external configuration store, follows 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.

Change the amAdmin password (embedded configuration store)

Back up your deployment as described in Back up configurations.
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.
Click Save Changes.

When AM is configured to use the embedded DS server for the configuration store, you must change the passwords of the uid=admin user to match the new amAdmin password.
Change the uid=admin account’s bind password in the AM configuration as follows:
- Change the password for the configuration store binding:
  - Go to Deployment > Servers > Server Name > Directory Configuration.
  - Enter the new Bind Password (the new amAdmin password) and click Save Changes.
    
    Changing the bind password of the configuration store updates the configstorepwd alias in the AM keystore file the next time AM starts.
- (Optional) If you use the embedded DS server as a data store, change the following bind passwords:
  - Go to Realms > Realm Name > Identity Stores > embedded:
    
    Enter the new bind password, which is the new amAdmin password, and click Save Changes.
    
    Make this change in every AM realm that uses the embedded DS as an identity store.
  - Go to Realms > Realm Name > Services > Policy Configuration:
    
    Enter the new bind password, which is the new amAdmin password, and click Save Changes.
    
    Make this change in every AM realm that uses the embedded DS as a data store.
  - Go to Realms > Realm Name > Authentication > Modules, and click LDAP:
    
    Enter the new bind password, which is the new amAdmin password, and save your changes.
    
    Make this change in every AM realm that uses the embedded DS as a data store.
To change the uid=admin and the global administrator passwords in the embedded DS, see Forgotten superuser password in the DS documentation.

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://openam.example.com/openam/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 will 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.
Refer to the Google Key Management Service documentation and Google’s Getting Started with Authentication for more information.

To configure AM to connect to the Google Cloud KMS with the service account, refer to 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
  To find the key ID, refer to 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/openam/security/secrets/userpasswords/password.amadmin

The default location of the special secret store is /path/to/openam/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. For details, refer to 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.
For information about the available AM privileges, see 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 data store, 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=openam,dc=forgerock,dc=org
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=openam,dc=forgerock,
dc=org
```
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 data store.

For example:

$ /path/to/opendj/bin/ldapmodify \
--hostname 'id.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=openam,dc=forgerock,dc=org
# MODIFY operation successful for DN uid=subrealmadmin,ou=people,dc=openam,dc=forgerock,dc=org

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 openam/XUI, and an administration UI, located at openam/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 console URI only to inbound connections from a specific network, or create a denylist or an allowlist with the endpoints the console uses. Learn more in How do I remove admin UI access in PingAM?.
Ensure administrative users present sufficiently strong credentials when logging in to the AM administrative console.

By default, users that log to the console make use of the chain or tree configured in the Organization Authentication Configuration property for the realm. To locate this property, go to Realms > Realm Name > Authentication > Settings > Core.

Ensure that 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.

Do not install the tools on the same server as AM, so that administrators do not 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 chain or 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, ensure that they present sufficiently strong credentials.
- If the administrative users connect to AM using private key connections, make sure that you create your own keys and share them with AM.
  
  For more information, see the Amster User Guide.
ssoadm
- Ensure that your administrative users present sufficiently strong credentials.
- The ssoadm command requires that you provide the password of the administrative user stored in cleartext in a file.
  
  Ensure the file is read-only for its owner.

PingAM 7.5.0

Secure administrative access

The amAdmin user

Change the amAdmin password

Change the amAdmin password (external configuration store)

Change the amAdmin password (embedded configuration store)

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