How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I change the dsameuser password in AM 5.x or 6.x?

Last updated Apr 13, 2021

The purpose of this article is to provide information on how to change the password for the internal dsameuser in AM. This article also covers changing the dsameuser password on multiple servers in a site configuration.


1 reader recommends this article

Background information

The dsameuser is present in two notable locations:

  • Globally in the SpecialRepo userstore, amongst the amAdmin and anonymous users.
  • Locally in the service configuration for each server, which contains the puser (legacy proxy user), dsameuser and the embedded DS Directory Manager credentials.

When AM starts up and writes to its bootstrap file, it uses the dsameuser password from the server configuration to write the dsameuser details to the bootstrap.

Note

By default, the dsameuser has the same password as amAdmin and the Directory Manager if you are using an embedded configuration store. It is your choice whether the dsameuser password matches the amAdmin password; they do by default, but do not need to. If you want to change the amAdmin password at the same time, refer to How do I change the amadmin and dsameuser passwords at the same time in AM 5.x or OpenAM 13.x? instead. 

The password for the dsameuser is held in the dsameuserpwd alias in the keystore, although is not required and will be removed in a future release: OPENAM-10175 (Remove dsameuser password from bootstrap file / keystore).

What is it used for?

Internally AM uses this user identity from the bootstrap file to perform actions on the embedded configuration store that are not related to a specific user. You cannot use the embedded DS in production for anything in AM 7 and later.

Externally this user is used by ssoadm (pre-AM 7). The first authentication attempt to ssoadm uses the dsameuser password from the bootstrap file and subsequent authentication attempts use the dsameuser password from the SpecialRepo userstore. This is a known issue: OPENAM-4292 (dsameuser authentication on /authservice differs at startup). Therefore, if your dsameuser passwords are different in your global and local configurations, subsequent authentications to ssoadm will fail. 

How do I change this password in both places?

The process you use to change the dsameuser password differs according to your setup:

Single AM server

You can change the dsameuser password as follows:

  1. Take a backup of your configuration data as described in How do I make a backup of configuration data in AM 5.x or 6.x?
  2. Export the server configuration using the get-svrcfg-xml command, for example: $ ./ssoadm get-svrcfg-xml -u amadmin -f pwd.txt -s http://host1.example.com:8080/openam -o serverconfig.xml
  3. Encode the new dsameuser password using encode.jsp or ampassword, for example:
    1. Create a file with the password in clear text: $ cat > newpassword.txt newPassword
    2. Encode the password: $ ./ampassword -e newpassword.txt AQICproF2sZsPQJlwBaVBFMj/423Ucpa5e8P
  4. Update the server configuration you exported in step 2 with the new encoded password. You need to change the DirPassword string for User 2 (cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org): <User name="User2" type="admin">            <DirDN>                 cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org             </DirDN>             <DirPassword>                 AQICproF2sZsPQJlwBaVBFMj/423Ucpa5e8P             </DirPassword>         </User>
  5. Create a batch file with the following commands, where the first command updates the dsameuser password (you must specify this password in clear text) and the second command imports the updated server configuration (it is essential you keep these commands in this order, else you will encounter an error). For example: $ cat > update.batch set-identity-attrs -t User -e / -i dsameuser -a userpassword=newPassword set-svrcfg-xml -s http://host1.example.com:8080/openam -X serverconfig.xml
  6. Run the do-batch command to apply the changes in your batch file, for example: $ ./ssoadm do-batch -u amadmin -f pwd.txt -Z update.batch
  7. Restart the web application container in which AM runs to apply these changes.

Multiple AM servers in a site

You can change the dsameuser password as follows:

  1. Take a backup of your configuration data as described in How do I make a backup of configuration data in AM 5.x or 6.x?
  2. Export the server configuration files for each server using the get-svrcfg-xml command, for example: $ ./ssoadm get-svrcfg-xml -u amadmin -f pwd.txt -s http://host1.example.com:8080/openam -o server1config.xml $ ./ssoadm get-svrcfg-xml -u amadmin -f pwd.txt -s http://host2.example.com:8080/openam -o server2config.xml
  3. Encode the new password using encode.jsp or ampassword, for example:
    1. Create a file with the password in clear text: $ cat > newpassword.txt newPassword
    2. Encode the password: $ ./ampassword -e newpassword.txt AQICproF2sZsPQJlwBaVBFMj/423Ucpa5e8P
  4. Update each of the server configurations you exported in step 2 with the new encoded password. You need to change the DirPassword string for User 2 (cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org): <User name="User2" type="admin">            <DirDN>                 cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org             </DirDN>             <DirPassword>                 AQICproF2sZsPQJlwBaVBFMj/423Ucpa5e8P             </DirPassword>        </User>
  5. Create a batch file with the following commands, where the first command updates the dsameuser password (you must specify this password in clear text), and the second two commands import the updated server configurations (it is essential you keep these commands in this order, else you will encounter an error). For example: $ cat > update.batch set-identity-attrs -t User -e / -i dsameuser -a userpassword=newPassword set-svrcfg-xml -s http://host1.example.com:8080/openam -X server1config.xml set-svrcfg-xml -s http://host12.example.com:8080/openam -X server2config.xml
  6. Run the do-batch command to apply the changes in your batch file, for example: $ ./ssoadm do-batch -u amadmin -f pwd.txt -Z update.batch
  7. Restart the web application container in which AM runs to apply these changes.

See Also

Subsequent attempts to use ssoadm fail in AM 5.x and 6.x

Administrator and user accounts in AM

Reference › ampassword

Related Training

N/A

Related Issue Tracker IDs

OPENAM-10175 (Remove dsameuser password from bootstrap file / keystore)

OPENAM-4292 (dsameuser authentication on /authservice differs at startup)


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.