Secure administrative access

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

This approach not only reduces the risk of accidental or intentional abuse of power, but also allows you to split the work between different teams and to audit configuration changes.

Securing administration in AM can be summed up as follows:

Understanding the amAdmin user and learning how to delegate realm privileges to groups of users.
Securing access to the AM admin UI, and to the tools that you can use to configure AM: Amster and the ssoadm command.

The `amAdmin` user

When you install AM, the amAdmin administrative account is created. This user has unrestricted access to the AM configuration, including creating new users and augmenting their list of administrative privileges.

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

The com.sun.identity.authentication.super.user advanced server property 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, however, affect the functionality of those files where the user name is hard-coded.

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 (UI)

This covers how to change the password of the top-level administrator amAdmin, when:

AM is configured using an external configuration store.

See Change the amAdmin password (external configuration store).
AM is configured for evaluation and is using the embedded DS server as the configuration store.

See Change the amAdmin password (embedded configuration store).

For a different way to change the amAdmin user’s password, regardless of how the configuration store is configured, see Change the amAdmin password using 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, which is 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.

Change the amAdmin password (secret store)

Another way to change the password of the amAdmin user is to use a special secret store.

This secret store is not visible in the AM admin UI. If you supply the amAdmin password using secrets, you cannot change the password using the AM admin UI unless you remove the secret configuration.
If you remove the secret configuration, the amAdmin password reverts to what it was before you configured the secrets.
The password of the amAdmin user stored in a secret must be salted and hashed. Encryption is optional, but highly recommended.

You can provide the password of the amAdmin user in different secrets, as shown in the following procedure:

Store the amAdmin password in a secret

Salt and hash the new password of the amAdmin user.

You can use a script similar to the following one. Review the comments to understand 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)

Decide whether to encrypt the hashed string, and how to do it:

Encrypt with the AM encryption password
1. Log in to the AM admin UI with an administrative user.
  
  For example, amAdmin.
2. Go to https://openam.example.com/openam/encode.jsp, and paste the final hashed string in the field.
  
  Optionally, you can use the ampassword command to encrypt the password. See Set up administration tools and ampassword.
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 that has a project. The project must have:
- A key ring containing the secrets that you will use to encrypt the hash of the password of the amAdmin user.
  
  The key ring can be configured 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, see 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 it is, you do not need to create another key.
  
  If the property is not 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 it. 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
  For information about how to find the key ID, see 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

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 cannot access the AM admin UI, you can instead 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 output to the secret ID that you will use. Perform one of the following:

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

$ echo -n amadmin_salted_encrypted_pass > /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.

Store the encrypted password in an operating system variable called PASSWORD_AMADMIN, and make sure it is available to the user running the container where AM runs. For example, add it to the user’s bash.profile file.
Store the encrypted password in a Java system variable called password.amadmin, and make sure it is 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"
```

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

Access Management 7.2.2

Secure administrative access

The amAdmin user

Change the amAdmin password (UI)

Change the amAdmin password (external configuration store)

Change the amAdmin password (embedded configuration store)

Change the amAdmin password (secret store)

Store the amAdmin password in a secret

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