Securing Administrative Access

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.

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.

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

     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 "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"

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.