--- title: Secure administrative access description: Understand how to secure administrative access to PingAM by protecting the amAdmin user, delegating realm privileges, and securing access to administration tools and interfaces component: pingam version: 7.5 page_id: pingam:security:securing-administration canonical_url: https://docs.pingidentity.com/pingam/8.1/security/securing-administration.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Security", "Setup & Configuration", "Identities"] page_aliases: ["security-guide:securing-administration.adoc"] superseded_by: https://docs.pingidentity.com/pingam/8.1/security/securing-administration.html section_ids: securing-admin-users: The amAdmin user amadmin-password-console: Change the amAdmin password external-config-external-datastore: Change the amAdmin password (external configuration store) embedded-config: Change the amAdmin password (embedded configuration store) amadmin-password-secret-store: Store the amAdmin password in a secret store delegating-realm-administration-privileges: Delegate privileges delegate-realm-administration-revoke-sessions: Let delegated subrealm administrators invalidate sessions delegate-agent-profile-creation: Delegate agent profile creation securing-admin-console: Secure access to the admin UIs securing-tools: Secure access to the admin tools --- # 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](#delegating-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](#amadmin-password-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: 1. In the AM admin UI, click on the user avatar ([icon: user-circle, set=fa]) in the top right corner. 2. Click Change Password. 3. Enter the current password in the Current password field. 4. Enter the new password in the New password and Confirm new password fields. 5. Save your work. If your deployment has multiple AM servers, the new password replicates across all servers. #### Change the amAdmin password (embedded configuration store) 1. Back up your deployment as described in [Back up configurations](../maintenance/backup-restore.html). 2. In the AM admin UI, click on the user avatar ([icon: user-circle, set=fa]) in the top right corner. 3. Click Change Password. 4. Enter the current password in the Current password field. 5. Enter the new password in the New password and Confirm new password fields. 6. 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. 7. 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. 8. To change the `uid=admin` and the global administrator passwords in the embedded DS, see [Forgotten superuser password](https://docs.pingidentity.com/pingds/7.5/maintenance-guide/troubleshooting.html#troubleshoot-reset-admin-passwords) 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: 1. 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: ```python #!/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) ``` 2. 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: > **Collapse: 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](https://cloud.google.com/kms/docs) and Google's [Getting Started with Authentication](https://cloud.google.com/docs/authentication/getting-started) for more information. > > To configure AM to connect to the Google Cloud KMS with the service account, refer to [Configure Google service account credentials](secret-stores.html#configuring-google-api-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: ```bash 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: ```none 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](https://cloud.google.com/kms/docs/object-hierarchy#key_resource_id) 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:```bash export CATALINA_OPTS="$CATALINA_OPTS -Dorg.forgerock.openam.secrets.special.user.passwords.format=PLAIN" ``` | 3. 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: ```bash $ echo -n > /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: ```bash 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](../reference/deployment-configuration-reference.html#secrets.special.user.secret.refresh.seconds) advanced server property. For increased security, rotate this secret periodically. For details, refer to [Map and rotate secrets](secret-mapping.html). ## 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. > **Collapse: 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?](https://support.pingidentity.com/s/article/How-do-I-add-privileges-to-identity-groups-in-PingAM). 1. 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. | 2. 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. 3. 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](#realm-privileges-delegation-ref). 4. 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 1. 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`: ```ldif 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. | 2. Run the `ldapmodify` command included with DS to apply the LDIF file to the user data store. For example: ```bash $ /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: 1. In the AM admin UI, go to Realms > *realm name* > Identities. 2. On the Groups tab, click Add Group and create a group for agent administrators. 3. On the Privileges tab, choose Realm Admin. 4. Click Save Changes. 5. Go to Realms > *realm name* > Identities. On the Identities tab, create as many agent administrator users as needed. 6. 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. 7. Click Save Changes. 8. 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 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 [Protecting PingAM with PingGateway](https://docs.pingidentity.com/pinggateway/2024.11/gateway-guide/protect-am.html) and [How do I remove admin UI access in PingAM?](https://support.pingidentity.com/s/article/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](../am-rest/about-api-explorer.html) 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. Learn more in [Private key connections](../amster/connect-am.html#private-login). * **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.