Securing Administrative Access

Some deployments may require a single administrator, for example, those where the configuration never changes in production. However, if your deployment benefits from having more than one administrator user, 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 changes in AM's configuration.

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 console, and to the tools that you can use to configure AM: Amster and the ssoadm command.

About the amAdmin User

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

The amAdmin account cannot be deleted since it is hard-coded in the source code of several files. The user is defined within AM's configuration, so it is always available to AM even in the event that the identity stores become unavailable. Since it is not an identity defined in any 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. This property can be changed to a 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.

Changing the amAdmin Password (UI)

In this section you will find procedures to change the password of the top-level administrator amAdmin, when:

Tip

For a different way to change the amAdmin user's password, regardless of how the configuration store is configured, see "Changing the amAdmin Password (Secret Stores)".

To Change the amAdmin User's Password: External Configuration Store

If AM is configured to use an external configuration store, perform the following steps to change the amAdmin user's password:

  1. In the AM console, click on the user avatar () in the top right hand corner of the UI.

  2. Select 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 changes.

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

To Change the amAdmin User's Password: Embedded Configuration Store
  1. Back up your deployment as described in Backing Up Configurations.

  2. In the AM console, click on the user avatar () in the top right hand corner of the UI.

  3. Select 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. Save your 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:

    1. Change the password for the configuration store binding:

      1. Navigate to Deployment > Servers > Server Name > Directory Configuration.

      2. Enter the new bind password, which is the new amAdmin password, and save your changes.

        Note

        Changing the bind password of the configuration store updates the configstorepwd alias in the AM keystore file the next time AM starts.

    2. (Optional) If you use the embedded DS server as a data store, change the following bind passwords:

      1. Navigate to Realms > Realm Name > Identity Stores > embedded:

        1. 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 an identity store.

      2. Navigate to Realms > Realm Name > Services > Policy Configuration:

        1. 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.

      3. Navigate to Realms > Realm Name > Authentication > Modules, and select LDAP:

        1. 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 in the ForgeRock Directory Services Maintenance Guide.

Changing the amAdmin Password (Secret Stores)

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

This secret store does not show in the AM console, and the password of the amAdmin user stored in a secret must be salted and hashed. Encryption is optional, but highly recommended.

Important

If you supply the amAdmin password using secrets, you cannot change the password using the AM console unless you remove the secret configuration.

When you remove the secret configuration, the amAdmin password will revert to what it was before you configured the secrets.

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

To Store the Password of the amAdmin User in a Secret
  1. 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)
  2. Decide whether to encrypt the hashed string, and how to do it:

    • Encrypting with the AM encryption password

      1. Log in to the AM console 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 Setting 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.

    • Encrypting with a secret stored in the Google Cloud KMS

      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 "Configuring the 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 console, 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.

    • Leaving the hashed string unencrypted

      Caution

      Ensure that the password is randomly generated and high entropy before continuing.

      1. In the AM console, go to Configure > Server Defaults > Advanced.

      2. Set the org.forgerock.openam.secrets.special.user.passwords.format advanced server property to PLAIN.

      Tip

      If you cannot access the AM console, 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"
  3. 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

      Tip

      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"

Delegating 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 to a specific realm, or a group of users that have full administration privileges for a particular realm.

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

Since 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.

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

Privileges
Privilege as it Appears in the AM console

Privilege Name to Use With the ssoadm add-privileges Command

Notes
Read and write access to all realm and policy propertiesRealm 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 console must have this privilege.

Read and write access to all configured agentsAgent Admin

Provides access to centralized agent configuration; subset of the RealmAdmin privilege.

Read and write access to all log filesLog AdminSubset of the Realm Admin privilege.
Read access to all log filesLog ReadSubset of the Realm Admin privilege.
Write access to all log filesLog WriteSubset of the RealmAdmin privilege.
Read and write access to all federation metadata configurationsFederation AdminSubset of the Realm Admin privilege.
REST calls for reading realmsRealm Read AccessSubset of the Realm Admin privilege.
Read and write access only for policy properties, including REST callsPolicy 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 evaluationEntitlement Rest Access

Subset of the Realm Admin and Policy Admin privileges.

REST calls for reading policiesPrivilege Rest Read Access

Subset of the Realm Admin and Policy Admin privileges.

REST calls for managing policiesPrivilege Rest Access

Subset of the Realm Admin and Policy Admin privileges.

REST calls for reading policy applicationsApplication Read Access

Subset of the Realm Admin and Policy Admin privileges.

REST calls for modifying policy applicationsApplication Modify Access

Subset of the Realm Admin and Policy Admin privileges.

REST calls for reading policy resource typesResource Type Read Access

Subset of the Realm Admin and Policy Admin privileges.

REST calls for modifying policy resource typesResource Type Modify Access

Subset of the Realm Admin and Policy Admin privileges.

REST calls for reading policy application typesApplication Types Read Access

Subset of the Realm Admin and Policy Admin privileges.

REST calls for reading environment conditionsCondition Types Read Access

Subset of the Realm Admin and Policy Admin privileges.

REST calls for reading subject conditionsSubject Types Read Access

Subset of the Realm Admin and Policy Admin privileges.

REST calls for reading decision combinersDecision Combiners Read Access

Subset of the Realm Admin and Policy Admin privileges.

REST calls for reading subject attributesSubject Attributes Read Access

Subset of the Realm Admin and Policy Admin privileges.

REST calls for modifying session propertiesSession Property Modify Access

Subset of the Realm Admin and Policy Admin privileges.


To Delegate 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. For information about how to do this, see How do I add privileges to identity groups in AM (All versions)? in the ForgeRock Knowledge Base.

  1. Navigate to the realm for which you want to delegate privileges. For example, navigate to Realms > Top Level Realm.

    Important

    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. Navigate to Identities > Groups and select 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 allows you to assign privileges to any identity that has a valid session in AM. Use it with caution, because not every identity authenticates to AM by using strong authentication. For example, this virtual group may contain the anonymous user, which is enabled by default.

  3. Select the administrative privileges to delegate for the realm:

    • (Optional) To grant users in the group access to the AM console for the realm, select Realm Admin.

      Administrators can use the AM console 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 console, 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.

    • (Optional) To grant users in the group access to REST endpoints, select the required privileges from the list.

    For information about the available AM privileges, see Realm Privileges Available for Delegation.

  4. Save your work.

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:

To Enable Delegated Subrealm Administrators to 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:

    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

    Note

    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:

    $ /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.

Delegating 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.

To Create Agent Administrators for a Realm

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

  1. In the AM console, 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, select Realm Admin, and Save your changes.

  4. Navigate to Realms > Realm Name > Identities. On the Identities tab, create as many agent administrator users as needed.

  5. 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, and then Save your work.

  6. 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.

Securing the Administration Console

AM provides both end-user pages, located at openam/XUI, and an administrative console, located at openam/ui-admin.

Consider the following points to secure the AM console:

  • Limit access to the administrative console.

    For example, allow access to the console URI only to inbound connections from a specific network, or create a blacklist or a whitelist with the endpoints the console uses. For more information and examples, see the How do I remove console access in AM (All versions)? in the ForgeRock Knowledge Base.

  • 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, navigate to Realms > Realm Name > Authentication > Settings > Core.

    Ensure that you change the default for all realms, including the Top Level Realm.

  • Disable the AM API explorer in production environments.

    Caution

    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.

Securing Administrative 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 that you create a username/password tree specifically for tools so that you can track it easily in the logs.

Review the following information to secure access to the tools:

Amster
  • If the administrative users connect to AM using interactive login, ensure that they present sufficiently strong credentials.

    By default, users logging in through Amster make use of the chain or tree configured in the Administrator Authentication Configuration property for the realm. To locate this property, navigate to Realms > Realm Name > Authentication > Settings > Core.

  • 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
  • By default, users logging in through the ssoadm command make use of the chain or tree configured in the Administrator Authentication Configuration property for the realm. To locate this property, navigate to Realms > Realm Name > Authentication > Settings > Core.

    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.

Read a different version of :