Administrator and user accounts in AM/OpenAM

This book provides information on administrator and user accounts in AM/OpenAM including changing passwords, what privileges are available, account lockout and known issues (with solutions).


Administrator Passwords


How do I change the amadmin and dsameuser passwords at the same time in AM/OpenAM (All versions)?

The purpose of this article is to provide assistance with changing the amadmin and dsameuser passwords at the same time in AM/OpenAM. This article also covers changing these passwords on multiple servers in a site configuration.

Overview

The amadmin user and dsameuser are special internal users and need to have their passwords changed in the correct order to avoid issues with logging in and using ssoadm. The individual articles for changing these passwords have more background information (How do I change the amadmin password in AM/OpenAM (All versions)? and How do I change the dsameuser password in AM/OpenAM (All versions)?) but the salient information about these users is: 

  • The amadmin user is stored in the configuration data store in AM/OpenAM rather than the user data store. This means you cannot apply a password policy (such as locking out the user after 3 failed attempts) to the amadmin user. 
  • If you use the embedded DS/OpenDJ configuration store, you must also update the LDAP bind password in AM/OpenAM, the cn=Directory Manager password in the embedded DS/OpenDJ and the global (replication) administrator password in the embedded DS/OpenDJ to match the new amadmin password. This ensures AM/OpenAM continues to function correctly, for example, you can access the configuration data store, log into the console as amadmin and add new servers to the existing deployment.
  • If you use the embedded DS/OpenDJ user store, you must also update the bind passwords to match the new amadmin password, this is necessary since AM/OpenAM by default binds to the embedded DS/OpenDJ using the credentials of the top level administrator (cn=Directory Manager) contained in the AM/OpenAM configuration store. You should update the LDAP bind passwords in the Identity Store, Services Policy configuration and LDAP authentication module.
  • The dsameuser is present in a global location (the SpecialRepo userstore with the amadmin and anonymous users) and in a local location (the service configuration for each server).
  • The dsameuser password in both these locations must match, else you will encounter a known issue with ssoadm, where subsequent authentications will fail: OPENAM-4292 (dsameuser authentication on /authservice differs at startup).
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. This article uses the same password to make the process simpler but highlights what you need to do if you want different passwords.

 The process you use to change these passwords differ according to your setup:

Caution

Once you have changed the amadmin password, you must also update any ssoadm scripts, password files or third-party applications that rely on the current amadmin password, else these scripts or applications will fail.

Single AM/OpenAM server with external DS/OpenDJ

You can change the amadmin and dsameuser passwords as follows:

  1. Take a backup of your configuration data as described in How do I make a backup of configuration data in AM/OpenAM (All versions)?
  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 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 two commands update the amadmin and dsameuser passwords (you must specify these passwords in clear text), and the third 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 amadmin -a userpassword=newPassword
    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
    
Note

This ssoadm command is performed against all data stores, meaning AM/OpenAM will send a password change request for the amadmin user to all data stores and therefore may report a failure if the user does not exist in a particular data store.

  1. Restart the web application container in which AM/OpenAM runs to apply these changes.
  2. Update the password file used by ssoadm, and any ssoadm scripts or third-party applications that rely on the current amadmin password.

Different passwords 

If you want to have different passwords for amadmin and dsameuser, you must follow the above steps with the following differences:

  • Encode the dsameuser password in step 3.
  • Specify different passwords in step 5 ensuring the dsameuser password matches the clear text password you encoded in step 3.

Multiple AM/OpenAM servers in a site with external DS/OpenDJ

You can change the amadmin and dsameuser passwords as follows:

  1. Take a backup of your configuration data as described in How do I make a backup of configuration data in AM/OpenAM (All versions)?
  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 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 two commands update the amadmin and dsameuser passwords (you must specify these passwords in clear text), and the second two 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 amadmin -a userpassword=newPassword
    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
    
Note

This ssoadm command is performed against all data stores, meaning AM/OpenAM will send a password change request for the amadmin user to all data stores and therefore may report a failure if the user does not exist in a particular data store.

  1. Restart the web application container in which AM/OpenAM runs to apply these changes.
  2. Update the password file used by ssoadm, and any ssoadm scripts or third-party applications that rely on the current amadmin password.

Different passwords 

If you want to have different passwords for amadmin and dsameuser, you must follow the above steps with the following differences:

  • Encode the dsameuser password in step 3.
  • Specify different passwords in step 5 ensuring the dsameuser password matches the clear text password you encoded in step 3.

Single AM/OpenAM server with an embedded DS/OpenDJ

The following process can be used to change the amadmin and dsameuser passwords if you have an embedded configuration store and optionally an embedded user store:

  1. Take a backup of your configuration data as described in How do I make a backup of configuration data in AM/OpenAM (All versions)?
  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 password using 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 both User 2s:
            <User name="User2" type="admin">
                <DirDN>
                    cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org
                </DirDN>
                <DirPassword>
                    AQICproF2sZsPQJlwBaVBFMj/423Ucpa5e8P
                </DirPassword>
           </User>
    ...
           <User name="User2" type="admin">
                <DirDN>
                    cn=Directory Manager
                </DirDN>
                <DirPassword>
                    AQICproF2sZsPQJlwBaVBFMj/423Ucpa5e8P
                </DirPassword>
            </User>
    
  5. Create a batch file with the following commands, where the first two commands update the amadmin and dsameuser passwords (you must specify these passwords in clear text), and the third one 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 amadmin -a userpassword=newPassword
    set-identity-attrs -t User -e / -i dsameuser -a userpassword=newPassword
    set-svrcfg-xml -s http://host1.example.com:8080/openam -X serverconfig.xml
    
    The amadmin password must not contain only a single " (double quote mark) as this will cause the command to fail and not update the password. Either do not use quote marks at all or encase the password in quotes, for example, "Passw0rd1".
  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
    
Note

This ssoadm command is performed against all data stores, meaning AM/OpenAM will send a password change request for the amadmin user to all data stores and therefore may report a failure if the user does not exist in a particular data store.

  1. Encode the new amadmin password using the DS/OpenDJ encode tool, for example:
    $ cd $HOME/[am_instance]/opends/bin
    $ ./encode-password --storageScheme SSHA512 --clearPassword newPassword
    
    {SSHA512}RypyBA65dxSQP0Zd2HZ2Ue7C2/FEQ/7YU0FU59jhD8kirLXToEaMelrY90/21QJcr3mfyB1KXPSZjCgq6OcQqIOsklOGlXOH
    
  2. Stop the web application container in which AM/OpenAM runs.
  3. Update the rootUser.ldif file (located in the $HOME/[am_instance]/opends/db/rootUser directory) in AM 6 and later or the config.ldif file (located in the $HOME/[am_instance]/opends/config directory) in pre-AM 6 with this new encoded password (the server must not be running when you edit these files). You need to change the password for dn: cn=Directory Manager (this is shown as dn=Directory Manager,cn=Root DNs,cn=config in pre-AM 6), for example:
    dn: cn=Directory Manager
    objectClass: top
    objectClass: person
    objectClass: organizationalPerson
    objectClass: inetOrgPerson
    givenName: Directory
    sn: Manager
    ...
    cn: Directory Manager
    userPassword: {SSHA512}RypyBA65dxSQP0Zd2HZ2Ue7C2/FEQ/7YU0FU59jhD8kirLXToEaMelrY90/21QJcr3mfyB1KXPSZjCgq6OcQqIOsklOGlXOH
    
  4. Restart the web application container in which AM/OpenAM runs to apply these changes.
  5. Update the global admin password to match the new amadmin password using ldappasswordmodify (this is needed to ensure you can add new AM/OpenAM nodes in the future without password conflicts). For example:
    $ ./ldappasswordmodify --hostname ds1.example.com --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --useStartTLS --authzID "cn=admin,cn=Administrators,cn=admin data" --newPassword newPassword
  6. Update the password file used by ssoadm, and any ssoadm scripts or third-party applications that rely on the current amadmin password.
  7. Only applicable if you have an embedded user store as well:
    1. Create a batch file with the following commands to update all the required user store bind passwords. You must update each of these passwords in every realm that uses the embedded user store. For example:
      $ cat > userstore.batch
      update-datastore -e / -m embedded -a sun-idrepo-ldapv3-config-authpw=newPassword
      set-realm-attrs -e / -s iPlanetAMPolicyConfigService -a iplanet-am-policy-config-ldap-bind-password=newPassword
      update-auth-instance -e / -m LDAP -a iplanet-am-auth-ldap-bind-passwd=newPassword
      
    2. Run the do-batch command to apply the changes in your batch file, for example:
      $ ./ssoadm do-batch -u amadmin -f pwd.txt -Z userstore.batch

Different passwords 

If you want to have different passwords for amadmin and dsameuser, you must follow the above steps with the following differences:

  • Repeat step 3 for both the amadmin and dsameuser passwords.
  • Use the encoded amadmin password for cn=Directory Manager in step 4 and the encoded dsameuser password for cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org in step 4.
  • Specify different passwords in step 5 ensuring your passwords match the clear text passwords you encoded in step 3.
  • Encode the amadmin password in step 7.

Multiple AM/OpenAM servers in a site with embedded DS/OpenDJ

The following process can be used to change the amadmin and dsameuser passwords if you have an embedded configuration store and optionally an embedded user store:

  1. Take a backup of your configuration data as described in How do I make a backup of configuration data in AM/OpenAM (All versions)?
  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 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 the server configurations you exported in step 2 with the new encoded password. You need to change the DirPassword string for both User 2s:
            <User name="User2" type="admin">
                <DirDN>
                    cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org
                </DirDN>
                <DirPassword>
                    AQICproF2sZsPQJlwBaVBFMj/423Ucpa5e8P
                </DirPassword>
           </User>
    ...
           <User name="User2" type="admin">
                <DirDN>
                    cn=Directory Manager
                </DirDN>
                <DirPassword>
                    AQICproF2sZsPQJlwBaVBFMj/423Ucpa5e8P
                </DirPassword>
            </User>
    
  5. Create a batch file with the following commands, where the first two commands update the amadmin and dsameuser passwords (you must specify these passwords in clear text), and the second two 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 amadmin -a userpassword=newPassword
    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
    
    The amadmin password must not contain only a single " (double quote mark) as this will cause the command to fail and not update the password. Either do not use quote marks at all or encase the password in quotes, for example, "Passw0rd1".
  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
    
Note

This ssoadm command is performed against all data stores, meaning AM/OpenAM will send a password change request for the amadmin user to all data stores and therefore may report a failure if the user does not exist in a particular data store.

  1. Encode the new amadmin password using the DS/OpenDJ encode tool. Ensure that the first server you change the directory manager password on, is the same server in which you ran the ssoadm do-batch command on in step 6 , for example:
    $ cd $HOME/[am_instance]/opends/bin
    $ ./encode-password --storageScheme SSHA512 --clearPassword newPassword
    
    {SSHA512}RypyBA65dxSQP0Zd2HZ2Ue7C2/FEQ/7YU0FU59jhD8kirLXToEaMelrY90/21QJcr3mfyB1KXPSZjCgq6OcQqIOsklOGlXOH
    
  2. Wait! You must allow enough time at this point for replication to complete.
  3. Stop the web application container in which AM/OpenAM runs.
  4. Update the rootUser.ldif file (located in the $HOME/[am_instance]/opends/db/rootUser directory) in AM 6 and later or the config.ldif file (located in the $HOME/[am_instance]/opends/config directory) in pre-AM 6 with this new encoded password (the server must not be running when you edit these files). You need to change the password for dn: cn=Directory Manager (this is shown as dn=Directory Manager,cn=Root DNs,cn=config in pre-AM 6), for example:
    dn: cn=Directory Manager
    objectClass: top
    objectClass: person
    objectClass: organizationalPerson
    objectClass: inetOrgPerson
    givenName: Directory
    sn: Manager
    ...
    cn: Directory Manager
    userPassword: {SSHA512}RypyBA65dxSQP0Zd2HZ2Ue7C2/FEQ/7YU0FU59jhD8kirLXToEaMelrY90/21QJcr3mfyB1KXPSZjCgq6OcQqIOsklOGlXOH
    
  5. Restart the web application container in which AM/OpenAM runs to apply these changes. 
  6. At this point, the bootstrap file will have been changed, and you should be able to login to server 1.
  7. Repeat steps 7 to 11 on all the remaining servers. Ensure to stop the server before performing the steps.
  8. You should now see the bootstrap files for the remaining servers have also been updated and you can login with your new password.
  9. Update the global admin password to match the new amadmin password using ldappasswordmodify (this is needed to ensure you can add new AM/OpenAM nodes in the future without password conflicts). You only need to do this on one server as replication will copy the password change to other replicas. For example:
    $ ./ldappasswordmodify --hostname ds1.example.com --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --useStartTLS --authzID "cn=admin,cn=Administrators,cn=admin data" --newPassword newPassword
  10. Update the password file used by ssoadm, and any ssoadm scripts or third-party applications that rely on the current amadmin password.
  11. Only applicable if you have an embedded user store as well:
    1. Create a batch file with the following commands to update all the required user store bind passwords. You must update each of these passwords in every realm that uses the embedded user store. For example:
      $ cat > userstore.batch
      update-datastore -e / -m embedded -a sun-idrepo-ldapv3-config-authpw=newPassword
      set-realm-attrs -e / -s iPlanetAMPolicyConfigService -a iplanet-am-policy-config-ldap-bind-password=newPassword
      update-auth-instance -e / -m LDAP -a iplanet-am-auth-ldap-bind-passwd=newPassword
      
    2. Run the do-batch command to apply the changes in your batch file, for example:
      $ ./ssoadm do-batch -u amadmin -f pwd.txt -Z userstore.batch
      
    3. Repeat steps 17.a and 17.b on all remaining servers that use the embedded user store.

Different passwords 

If you want to have different passwords for amadmin and dsameuser, you must follow the above steps with the following differences:

  • Repeat step 3 for both the amadmin and dsameuser passwords.
  • Use the encoded amadmin password for cn=Directory Manager in step 4 and the encoded dsameuser password for cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org in step 4.
  • Specify different passwords in step 5 ensuring your passwords match the clear text passwords you encoded in step 3.
  • Encode the amadmin password in step 7.

See Also

How do I change the amadmin password in AM/OpenAM (All versions)?

How do I change the dsameuser password in AM/OpenAM (All versions)?

How do I change the password for the configuration store in AM/OpenAM (All versions)?

How do I create an admin user in AM/OpenAM (All versions) with amadmin privileges?

Administrator and user accounts in AM/OpenAM

Administration Guide › Resetting Administrator Passwords 

Reference › ampassword

Related Training

N/A

Related Issue Tracker IDs

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

OPENAM-6956 (ssoadm import-svc-cfg fails after changing amadmin password)

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

OPENAM-4280 (ampassword -a (admin) doesn't work)

OPENAM-3187 (Updating a special user's password fails if there is an AD data store configured in the root realm)

OPENAM-1228 (Inability to rename/ replace the 'amAdmin' account)


How do I change the amadmin password in AM/OpenAM (All versions)?

The purpose of this article is to provide assistance with changing the amadmin password in AM/OpenAM. The amadmin user is stored in the configuration data store in AM/OpenAM. This article also covers changing the amadmin password on multiple servers in a site configuration.

Overview

The amadmin account is stored in the configuration data store in AM/OpenAM which is separate to the user data store. You can change the password for the amadmin account but it cannot be disabled, deleted or renamed since it is hard-coded in the source code of several files; it also has separate requirements for password changes if AM/OpenAM is configured to use an embedded DS/OpenDJ.

Embedded DS/OpenDJ configuration store

If you use the embedded DS/OpenDJ configuration store, you must also update the following passwords to match the new amadmin password:

  • The LDAP bind password in AM/OpenAM.
  • The cn=Directory Manager user password in the embedded DS/OpenDJ. 
  • The global (replication) administrator user password in the embedded DS/OpenDJ. By default the global admin is created in the directory server by AM/OpenAM after a second AM/OpenAM server is added to the deployment.

These passwords must all match amadmin to ensure AM/OpenAM continues to function correctly, for example, you can access the configuration data store, log into the console as amadmin and add new servers to the existing deployment.

Embedded DS/OpenDJ user store

If you use the embedded DS/OpenDJ user store, you must also update the bind passwords to match the new amadmin password, this is necessary since AM/OpenAM by default binds to the embedded DS/OpenDJ using the credentials of the top level administrator (cn=Directory Manager) contained in the AM/OpenAM configuration store:

  • LDAP bind passwords for the user store in AM/OpenAM. These must be updated in the following locations:
    • Identity Store
    • Services Policy configuration
    • LDAP authentication module

These passwords must all match amadmin to ensure continued access to the embedded user store. 

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 dsameuser password at the same time, refer to How do I change the amadmin and dsameuser passwords at the same time in AM/OpenAM (All versions)? instead.

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

Caution

Once you have changed the amadmin password, you must also update any ssoadm scripts, password files or third-party applications that rely on the current amadmin password, else these scripts or applications will fail.

One or more AM/OpenAM servers with external DS/OpenDJ

The following process applies regardless of whether you have a single server or multiple servers in a site; if you have multiple servers, replication will update the password on the other servers in the site once it is updated on one server.

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM/OpenAM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains valid resource versions (AM 5 and later).

See How do I avoid common issues with REST calls in AM/OpenAM (All versions)? for further information.

You can change the amadmin 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/OpenAM (All versions)?
  2. Update the amadmin password using either the console, REST or ssoadm (you cannot change the password via the console in AM 6.0.x and 6.5 due to a known issue: OPENAM-14183 (Cannot change amadmin's password through XUI); this is fixed in AM 6.5.1):
    • AM / OpenAM 13.x console: navigate to: Realms > Top Level Realm / > Subjects > User > amAdmin > Password and click Edit. Enter your old password if necessary, your new password twice and then click OK to update your password.
    • Pre-OpenAM 13 console: navigate to: Access Control > (Top Level Realm) > Subjects > User > amAdmin > Password and click Edit. Enter your old password if necessary, your new password twice and then click OK to update your password.
    • REST:
      1. Authenticate as an admin user. For example:
        • AM 5 and later:
          $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate
          
        • Pre-AM 5:
          $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate
        Example response:
        { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
        
      2. Change the password for amadmin using the following curl command, replacing newpassword with your actual new password:
        $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0" -d '{“userpassword”:“newpassword”}' http://host1.example.com:8080/openam/json/users/amadmin 
    • ssoadm: enter the following command:
      $ ./ssoadm set-identity-attrs -t User -e / -i amAdmin -u [adminID] -f [passwordfile] -a userpassword=[newpassword]
      replacing [adminID], [passwordfile] and [newpassword] with appropriate values.
Note

This ssoadm command is performed against all data stores, meaning AM/OpenAM will send a password change request for the amadmin user to all data stores and therefore may report a failure if the user does not exist in a particular data store.

  1. Restart the web application container in which AM/OpenAM runs. 
  2. Update the password file used by ssoadm, and any ssoadm scripts or third-party applications that rely on the current amadmin password.

Single AM/OpenAM server with an embedded DS/OpenDJ

The following process can be used to change the amadmin password if you have an embedded configuration store and optionally an embedded user store:

  1. Take a backup of your configuration data as described in How do I make a backup of configuration data in AM/OpenAM (All versions)?
  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 amadmin 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=Directory Manager):
            <User name="User2" type="admin">
                <DirDN>
                    cn=Directory Manager
                </DirDN>
                <DirPassword>
                    AQICproF2sZsPQJlwBaVBFMj/423Ucpa5e8P
                </DirPassword>
            </User>
    
  5. Create a batch file with the following commands, where the first command updates the amadmin 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 amadmin -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
    
Note

This ssoadm command is performed against all data stores, meaning AM/OpenAM will send a password change request for the amadmin user to all data stores and therefore may report a failure if the user does not exist in a particular data store.

  1. Encode the new amadmin password using the DS/OpenDJ encode tool, for example:
    $ cd $HOME/[am_instance]/opends/bin
    $ ./encode-password --storageScheme SSHA512 --clearPassword newPassword
    
    {SSHA512}RypyBA65dxSQP0Zd2HZ2Ue7C2/FEQ/7YU0FU59jhD8kirLXToEaMelrY90/21QJcr3mfyB1KXPSZjCgq6OcQqIOsklOGlXOH
    
  2. Stop the web application container in which AM/OpenAM runs.
  3. Update the rootUser.ldif file (located in the $HOME/[am_instance]/opends/db/rootUser directory) in AM 6 and later or the config.ldif file (located in the $HOME/[am_instance]/opends/config directory) in pre-AM 6 with this new encoded password (the server must not be running when you edit these files). You need to change the password for dn: cn=Directory Manager (this is shown as dn=Directory Manager,cn=Root DNs,cn=config in pre-AM 6), for example:
    dn: cn=Directory Manager
    objectClass: top
    objectClass: person
    objectClass: organizationalPerson
    objectClass: inetOrgPerson
    givenName: Directory
    sn: Manager
    ...
    cn: Directory Manager
    userPassword: {SSHA512}RypyBA65dxSQP0Zd2HZ2Ue7C2/FEQ/7YU0FU59jhD8kirLXToEaMelrY90/21QJcr3mfyB1KXPSZjCgq6OcQqIOsklOGlXOH
    
  4. Restart the web application container in which AM/OpenAM runs to apply these changes.
  5. Update the global admin password to match the new amadmin password using ldappasswordmodify (this is needed to ensure you can add new AM/OpenAM nodes in the future without password conflicts). For example:
    $ ./ldappasswordmodify --hostname ds1.example.com --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --useStartTLS --authzID "cn=admin,cn=Administrators,cn=admin data" --newPassword newPassword
    
  6. Update the password file used by ssoadm, and any ssoadm scripts or third-party applications that rely on the current amadmin password.
  7. Only applicable if you have an embedded user store as well:
    1. Create a batch file with the following commands to update all the required user store bind passwords. You must update each of these passwords in every realm that uses the embedded user store. For example:
      $ cat > userstore.batch
      update-datastore -e / -m embedded -a sun-idrepo-ldapv3-config-authpw=newPassword
      set-realm-attrs -e / -s iPlanetAMPolicyConfigService -a iplanet-am-policy-config-ldap-bind-password=newPassword
      update-auth-instance -e / -m LDAP -a iplanet-am-auth-ldap-bind-passwd=newPassword
      
    2. Run the do-batch command to apply the changes in your batch file, for example:
      $ ./ssoadm do-batch -u amadmin -f pwd.txt -Z userstore.batch
      

Multiple AM/OpenAM servers in a site with embedded DS/OpenDJ

The following process can be used to change the amadmin password if you have an embedded configuration store and optionally an embedded user store.

  1. Take a backup of your configuration data as described in How do I make a backup of configuration data in AM/OpenAM (All versions)?
  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 amadmin 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 the server configurations you exported in step 2 with the new encoded password. You need to change the DirPassword string for User 2 (cn=Directory Manager):
            <User name="User2" type="admin">
                <DirDN>
                    cn=Directory Manager
                </DirDN>
                <DirPassword>
                    AQICproF2sZsPQJlwBaVBFMj/423Ucpa5e8P
                </DirPassword>
            </User>
    
  5. Create a batch file with the following commands, where the first command updates the amadmin 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 amadmin -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
    
Note

This ssoadm command is performed against all data stores, meaning AM/OpenAM will send a password change request for the amadmin user to all data stores and therefore may report a failure if the user does not exist in a particular data store.

  1. Encode the new amadmin password using the DS/OpenDJ encode tool. Ensure that the first server you change the directory manager password on, is the same server in which you ran the ssoadm do-batch command on in step 6 , for example:
    $ cd $HOME/[am_instance]/opends/bin
    $ ./encode-password --storageScheme SSHA512 --clearPassword newPassword
    
    {SSHA512}RypyBA65dxSQP0Zd2HZ2Ue7C2/FEQ/7YU0FU59jhD8kirLXToEaMelrY90/21QJcr3mfyB1KXPSZjCgq6OcQqIOsklOGlXOH
    
  2. Wait! You must allow enough time at this point for replication to complete.
  3. Stop the web application container in which AM/OpenAM runs.
  4. Update the rootUser.ldif file (located in the $HOME/[am_instance]/opends/db/rootUser directory) in AM 6 and later or the config.ldif file (located in the $HOME/[am_instance]/opends/config directory) in pre-AM 6 with this new encoded password (the server must not be running when you edit these files). You need to change the password for dn: cn=Directory Manager (this is shown as dn=Directory Manager,cn=Root DNs,cn=config in pre-AM 6), for example:
    dn: cn=Directory Manager
    objectClass: top
    objectClass: person
    objectClass: organizationalPerson
    objectClass: inetOrgPerson
    givenName: Directory
    sn: Manager
    ...
    cn: Directory Manager
    userPassword: {SSHA512}RypyBA65dxSQP0Zd2HZ2Ue7C2/FEQ/7YU0FU59jhD8kirLXToEaMelrY90/21QJcr3mfyB1KXPSZjCgq6OcQqIOsklOGlXOH
    
  5. Restart the web application container in which AM/OpenAM runs to apply these changes. 
  6. At this point, the bootstrap file will have been changed, and you should be able to login to server 1.
  7. Repeat steps 7 to 11 on all the remaining servers. Ensure to stop the server before performing the steps.
  8. You should now see the bootstrap files for the remaining servers have also been updated and you can login with your new password.
  9. Update the global admin password to match the new amadmin password using ldappasswordmodify (this is needed to ensure you can add new AM/OpenAM nodes in the future without password conflicts). You only need to do this on one server as replication will copy the password change to other replicas. For example:
    $ ./ldappasswordmodify --hostname ds1.example.com --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --useStartTLS --authzID "cn=admin,cn=Administrators,cn=admin data" --newPassword newPassword
  10. Update the password file used by ssoadm, and any ssoadm scripts or third-party applications that rely on the current amadmin password.
  11. Only applicable if you have an embedded user store as well:
    1. Create a batch file with the following commands to update all the required user store bind passwords. You must update each of these passwords in every realm that uses the embedded user store. For example:
      $ cat > userstore.batch
      update-datastore -e / -m embedded -a sun-idrepo-ldapv3-config-authpw=newPassword
      set-realm-attrs -e / -s iPlanetAMPolicyConfigService -a iplanet-am-policy-config-ldap-bind-password=newPassword
      update-auth-instance -e / -m LDAP -a iplanet-am-auth-ldap-bind-passwd=newPassword
      
    2. Run the do-batch command to apply the changes in your batch file, for example:
      $ ./ssoadm do-batch -u amadmin -f pwd.txt -Z userstore.batch
      
    3. Repeat steps 17.a and 17.b on all remaining servers that use the embedded user store.

See Also

How do I change the amadmin and dsameuser passwords at the same time in AM/OpenAM (All versions)?

How do I change the dsameuser password in AM/OpenAM (All versions)?

How do I change the password for the configuration store in AM/OpenAM (All versions)?

How do I create an admin user in AM/OpenAM (All versions) with amadmin privileges?

Administrator and user accounts in AM/OpenAM

Setup and Maintenance Guide › Changing the amadmin User's Password

Reference › ampassword

Related Training

N/A

Related Issue Tracker IDs

OPENAM-14183 (Cannot change amadmin's password through XUI)

OPENAM-6956 (ssoadm import-svc-cfg fails after changing amadmin password)

OPENAM-1228 (Inability to rename/ replace the 'amAdmin' account)


How do I change the dsameuser password in AM/OpenAM (All versions)?

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

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/OpenDJ Directory Manager credentials.

When AM/OpenAM 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/OpenAM (All versions)? instead. 

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

What is it used for?

Internally AM/OpenAM uses this user identity from the bootstrap file to perform actions on the embedded configuration store that are not related to a specific user.

Externally this user is used by ssoadm. 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/OpenAM 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/OpenAM (All versions)?
  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/OpenAM runs to apply these changes. 

Multiple AM/OpenAM 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/OpenAM (All versions)?
  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 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/OpenAM runs to apply these changes. 

See Also

How do I change the amadmin and dsameuser passwords at the same time in AM/OpenAM (All versions)?

How do I change the amadmin password in AM/OpenAM (All versions)?

Subsequent attempts to use ssoadm fail in AM/OpenAM (All versions)

Administrator and user accounts in AM/OpenAM

Reference › Command Line Tools › 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)

OPENAM-4280 (ampassword -a (admin) doesn't work)

OPENAM-4218 (JAVA_HOME is not set correctly when installing admin tools (ssoadm, ampassword, amverifyarchive))


How do I change the password for the configuration store in AM/OpenAM (All versions)?

The purpose of this article is to provide information on changing the password for the configuration store in AM/OpenAM. This article also covers changing the configuration store password in a high availability (HA) environment where you have multiple servers in a site.

Changing the configuration store password

As of AM 5, the password for the configuration store is held in the configstorepwd alias in the keystore. Each time you update the configuration store password, AM also modifies the content of the configstorepwd alias in the keystore.jceks keystore file. See Setup and Maintenance Guide › Setting Up Keys and Keystores › Configuring Password String Aliases for further information.

You can change the configuration store password using either the console or ssoadm:

Note

If you use embedded DS/OpenDJ your configuration store password and amadmin password should match. See How do I change the amadmin password in AM/OpenAM (All versions)? for further information on changing the amadmin password.

Console

  1. Update the configuration store (directory bind) password on all AM/OpenAM servers using the console:
    • AM / OpenAM 13.5 console: navigate to: Deployment > Servers > [Server Name] > Directory Configuration > Bind Password and enter your new password.​
    • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > [Server Name] > Directory Configuration > Bind Password and enter your new password.​
    This configuration is server specific and must be changed on all servers in your site.
  2. Update the password for cn=Directory Manager on all directory servers to match your new password. This configuration is server specific and must be changed on all directory servers. If you use DS/OpenDJ, refer to Administration Guide › Troubleshooting Server Problems › Resetting Administrator Passwords for further information. If you use the embedded DS/OpenDJ, you must restart the web application container in which AM/OpenAM runs to restart the DS/OpenDJ server.

ssoadm 

  1. Export the current server configuration details to a XML file using the following command:
    $ ./ssoadm get-svrcfg-xml -u [adminID] -f [passwordfile] -s [serverName] -o [XMLfile]
    
    replacing [adminID], [passwordfile], [serverName] and [XMLfile] with appropriate values.
  2. Encrypt your new configuration store password using ampassword:
    $ ./ampassword -e [passwordfile]
    
    replacing [passwordfile] with an appropriate value.
  3. Edit the XML file you exported in step 1 to replace the <DirPassword> value in the sms section with the encrypted password you generated in step 2:
        <ServerGroup name="sms" minConnPool="1" maxConnPool="10">
            <Server name="Server1" host="host1.example.com" port="8080"
                 type="SIMPLE" />
                 <User name="User2" type="admin">
                    <DirDN>cn=Directory Manager</DirDN>
                    <DirPassword>AQICUsKIqPqiF0SPBdLZ99beokClGjSB0vuR</DirPassword>
                 </User>
                 <BaseDN>dc=example,dc=com</BaseDN>
        </ServerGroup>
    
  4. Import the updated server configuration XML file to AM/OpenAM using the following command:
    $ ./ssoadm set-svrcfg-xml -u [adminID] -f [passwordfile] -s [serverName] -X [XMLfile]
    replacing [adminID], [passwordfile], [serverName] and [XMLfile] with appropriate values.
  5. Repeat steps 1 to 4 on on all AM/OpenAM servers if you have multiple servers in a site; this configuration is server specific and must be changed on all servers in your site.
  6. Update the password for cn=Directory Manager on all directory servers to match your new password. This configuration is server specific and must be changed on all directory servers. If you use DS/OpenDJ, refer to Administration Guide › Troubleshooting Server Problems › Resetting Administrator Passwords for further information. To restart the embedded DS/OpenDJ server, you must restart the web application container in which AM/OpenAM runs.
  1. Restart the web application container in which AM/OpenAM runs to update the configuration.

Example using ssoadm

The following example changes the configuration store password from cangetinam to newPassw0rd on a single server using ssoadm:

  1. Export the current server configuration details to a XML file:
    $ ./ssoadm get-svrcfg-xml -u amadmin -f pwd.txt -s http://host1.example.com:8080/openam -o serverConfig.xml
  2. Create a text file containing your new password:
    $ echo newPassw0rd > password.txt
  3. Encrypt your new configuration store password using ampassword:
    $ ./ampassword -e password.txt
    Output:
    AQIC61K+PS/+xIv3c4Y4Wxwb66cCcCYeKa/9
    
  4. Edit the serverConfig.xml file you exported in step 1 to replace the <DirPassword> value in the sms section with the encrypted password you generated in step 3:
        <ServerGroup name="sms" minConnPool="1" maxConnPool="10">
            <Server name="Server1" host="host1.example.com" port="8080"
                 type="SIMPLE" />
                 <User name="User2" type="admin">
                    <DirDN>cn=Directory Manager</DirDN>
                    <DirPassword>AQIC61K+PS/+xIv3c4Y4Wxwb66cCcCYeKa/9</DirPassword>
                 </User>
                 <BaseDN>dc=example,dc=com</BaseDN>
        </ServerGroup>
    
  5. Import the updated serverConfig.xml file to AM/OpenAM:
    $ ./ssoadm set-svrcfg-xml -u amadmin -f pwd.txt -s http://host1.example.com:8080/openam -X serverConfig.xml
  6. Update the password for cn=Directory Manager on all directory servers to newPassw0rd.
  7. Restart the web application container in which AM/OpenAM runs.

See Also

How do I change the amadmin password in AM/OpenAM (All versions)?

How do I change the dsameuser password in AM/OpenAM (All versions)?

How do I add a second configuration store or edit an existing configuration store in AM/OpenAM (All versions)?

Setup and Maintenance Guide › Setting Up Keys and Keystores › Configuring Password String Aliases 

Reference › Command Line Tools › ssoadm

Reference › Configuration Reference › Directory Configuration Properties

Related Training

N/A

Related Issue Tracker IDs

N/A


Administrator Privileges


How do I understand what privileges apply to amadmin and delegated administrators in AM/OpenAM (All versions)?

The purpose of this article is to provide comparison information on the difference between the administrative privileges assigned to amadmin and those of delegated administrators, and which administrative tasks require amadmin (Super user) access rights. Some aspects of amadmin functionality are hard-coded and therefore only apply to the amadmin user.

Overview

You can create other admin users with similar privileges to the amadmin user by delegating administration but you should be aware that these users will not function in exactly the same way as the amadmin user. Some aspects of the amadmin functionality is hard-coded and therefore only applies to the amadmin user. From Setup and Maintenance Guide › Maintaining an Instance › Changing the amadmin User's Password:

The built-in amadmin account cannot be disabled, deleted, or renamed, since it is hard-coded in the source code of several files.

This article looks at the capabilities of amadmin and delegated administrators in more detail, and covers:

Delegated privileges

You can delegate tasks based on privileges. See the following links for further information:

The following diagram illustrates the scope of control by administrator users at different levels; this is discussed in more detail below:

Top level realm

If you create an administrator user in the top level realm with all the privileges listed in Realm Privileges Configuration Reference, they will have full control over the configuration and services of the top level realm, including the ability to add and update sub-realms. Such an administrator user is operationally equivalent to the amadmin user.

See the amadmin only tasks section below for details on the limitations of a top level realm administrator compared to the amadmin user.

Sub-realm

If you create an administrator user in a sub-realm (child realm) with all the privileges listed in Realm Privileges Configuration Reference, they will be able to add services and alter the configuration of the sub-realm to which they belong and any sub-realms beneath that level. They will not be able to do anything at a Server instance or global level.

A sub-realm administrator cannot perform the following tasks:

  • Alter Global service configuration defaults that impact all realms.
  • Configure the following details for a Server instance:
    • File system installation locations.
    • Site and load balancing information.
    • Logging locations.
    • Keystore configuration.
    • Encryption and Certificate Revocation.
    • Core Token Service configuration.
    • User-Managed Access storage configuration.
    • Advanced parameters, instance and debug configuration.

amadmin only tasks

The following tasks can only be performed by the amadmin user:

  • Changing the amadmin user's password. See How do I change the amadmin password in AM/OpenAM (All versions)? for further information.
  • Recording troubleshooting information via REST. See How do I record troubleshooting information in AM/OpenAM (All versions)? for further information.
  • Logging in to a server once the maximum number of sessions has been exceeded. However, the amadmin user cannot log in to a realm if client-based sessions are configured (but a delegated administrator can).
  • Using the following directory JSP endpoints, which are detailed in Reference › Service Endpoints › Top-Level JSP Files:
    • Debug.jsp 
    • encode.jsp
    • getServerInfo.jsp
    • showServerConfig.jsp
    • services.jsp
    • ssoadm.jsp (this page was removed in AM 5.5, was deprecated in AM 5 and was deactivated by default prior to that to prevent potential misuse)
  • Triggering the following workflow tasks accessed from the realm level Common Tasks page:
    • Configure SAMLv2 Provider
    • Configure OAuth Provider
    • Create Fedlet Configuration
    • Configure Google Apps
    • Configure Salesforce CRM
    • Configure Social Authentication
    These workflows are triggered by the AjaxProxy.jsp endpoint, which is detailed in Reference › Service Endpoints › Console Ajax JSP Files. Only the amadmin user has access to this endpoint.
Note

Delegated administrators can manually configure the providers, services and SAML entities configured via these workflow tasks; automation is also possible for delegated users via ssoadm and REST (where REST is available). 

  • Configuring SOAP and REST via the console (delegated administrators can configure these via ssoadm). Again, these configuration pages rely on the AjaxProxy.jsp endpoint, which is only accessible to the amadmin user. 
  • Listing and retrieving SAML assertions and artifacts in the OpenAM Java SDK (also referred to as the Client SDK).

Performance considerations

The amadmin user is likely to have faster response times when compared to a user with delegated administrative privileges. This is because delegation policies explicitly check to see if the current user is the amadmin user: 

  • If they are, it is assumed that all operations are permitted.
  • If they aren't, additional checks are performed to see if the group they belong to has been delegated the correct privilege.

Upgrade considerations

Upgrade processing does not typically require use of the amadmin account; however, it does require file system access to the web container in which AM/OpenAM is running.

See Also

How do I create an admin user in AM/OpenAM (All versions) with amadmin privileges?

How do I change the amadmin password in AM/OpenAM (All versions)?

How do I change the amadmin and dsameuser passwords at the same time in AM/OpenAM (All versions)?

FAQ: Users in AM/OpenAM

Administrator and user accounts in AM/OpenAM

Setup and Maintenance Guide › Setting Up Realms › Delegating Realm Administration Privileges

Setup and Maintenance Guide › Reference › Realm Privileges Configuration Reference

Related Training

N/A

Related Issue Tracker IDs

OPENAM-13339 (Custom Admin can't view SAML or configuration tab)

OPENAM-10976 (Provide a fully delegated non-amAdmin account in the top level realm for use with the Record endpoint)

OPENAM-10912 (Describe permissions required to use each REST endpoint in API Explorer)

OPENAM-10860 (refactor checks for superUser to make it easier to analyse where it is required)

OPENAM-10802 (bugs caused by hard coded amadmin check in admincheck.jsp and AjaxProxy.jsp)

OPENAM-6740 (need to add delegation privilege of checking a users' token's MaxTime to a privilege such as RealmAdmin)

OPENAM-6502 (Only admins are allowed to retrieve information about sessions)

OPENAM-4713 (Can't use Common Tasks wizards when logged in as a delegated administrator)

OPENAM-4034 (AM REST needs delegation support)


How do I create an admin user in AM/OpenAM (All versions) with amadmin privileges?

The purpose of this article is to provide information on creating an admin user in AM/OpenAM with similar privileges to the amadmin user. You can also create an admin user who can do CRUD operations using the REST API. This allows you to have a user other than amadmin who can Create, Read, Update and Delete Users.

Overview

You can create other admin users with similar privileges to the amadmin user by delegating administration but you should be aware that these users will not function in exactly the same way as the amadmin user. Some aspects of the amadmin functionality is hard-coded and therefore only applies to the amadmin user. From Setup and Maintenance Guide › Changing the amadmin User's Password:

The built-in amadmin account cannot be disabled, deleted, or renamed, since it is hard-coded in the source code of several files.

You can also create users with differing levels of access according to what privileges you assign them; however, it is not possible to create a user who only has Read-only access to the console. An RFE has been raised for this: OPENAM-5714 (Add support for more granular delegation privileges).

Alternatively, you can make the whole data store read-only as described in How do I make a whole user data store read-only to users in AM/OpenAM (All versions)?

Creating an admin user

You can create an admin user as follows:

  1. Create the user who you want to make the admin user if they do not already exist. You can do this using either the console or ssoadm:
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Identities, click Add Identity and enter details for the user.
    • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name]  > Subjects, click New and enter details for the user.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name]  > Subjects, click New and enter details for the user.
    • ssoadm: enter the following command:
      $ ./ssoadm create-identity -e [realmname] -u [adminID] -f [passwordfile] -i [username] -t User -a userpassword=[userpassword]
      
      replacing [realmname], [adminID], [passwordfile], [username] and [userpassword] with appropriate values. The userpassword attribute is appropriate if you are using DS/OpenDJ for your user store (identity store); if you are using a different directory server, you will need to use the relevant attribute for user password. 
  2. Create a new group to represent this type of admin user using either the console or ssoadm:
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Identities > Groups, click Add Group and enter an ID for the group.
    • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name]  > Subjects > Group, click New and enter an ID for the group.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name]  > Subjects > Group, click New and enter an ID for the group.
    • ssoadm: enter the following command:
      $ ./ssoadm create-identity -e [realmname] -u [adminID] -f [passwordfile] -i [groupname] -t Group
      
      replacing [realmname], [adminID], [passwordfile] and [groupname] with appropriate values. 
  3. Add your admin user to this new group using either the console or ssoadm:
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Identities > Groups > [Group Name] and add the user you created in step 1 as a member.
    • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name]  > Subjects > [Admin User] > Group and add the group you created in step 2.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name]  > Subjects > [Admin User] > Group and add the group you created in step 2.
    • ssoadm: enter the following command:
      $ ./ssoadm add-member -e [realmname] -u [adminID] -f [passwordfile] -i [groupname] -t Group -m [username] -y User 
      
      replacing [realmname], [adminID], [passwordfile], [groupname] and [username] with appropriate values. 
  4. Give this group the required privileges using either the console or ssoadm: 
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Identities > Groups > [Group Name] > Privileges and enable the required privileges. For full read and write access (including via the REST API), enable Realm Admin.
    • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name]  > Privileges > [Group Name] and select the required privilege. For full read and write access (including via the REST API), select the Read and write access to all realm and policy properties option.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name]  > Privileges > [Group Name] and select the required privilege. For full read and write access (including via the REST API), select the Read and write access to all realm and policy properties option.
    • ssoadm: enter the following command:
      $ ./ssoadm add-privileges -e [realmname] -u [adminID] -f [passwordfile] -i [groupname] -t Group -g [privilegename]
      
      replacing [realmname], [adminID], [passwordfile], [groupname] and [privilegename] with appropriate values.​ For full read and write access (including via the REST API) use RealmAdmin for the [privilegename]. As of AM 5, delegated administrators with the RealmAdmin privilege can also access full console functionality within the realms they can administer. In addition, delegated administrators in the top level realm who have this privilege can access the global configuration.
Note

See Setup and Maintenance Guide › Realm Privileges Configuration Reference for further information on the different privileges available and the equivalent privilege name for use with the ssoadm add-privileges command.

The new admin user now has access according to the privileges assigned to them. If you gave them full read and write access, they have full read and write access to the console and can also create, read, update and delete users via the REST API using curl commands such as the ones detailed in Setup and Maintenance Guide › Identity Management.

You should ensure that the corresponding user account on the directory server has at least CN=Directory Manager privileges. If you're using DS/OpenDJ, see Administration Guide › Configuring Privileges & Access Control for further information.

See Also

How do I understand what privileges apply to amadmin and delegated administrators in AM/OpenAM (All versions)?

How do I change the amadmin and dsameuser passwords at the same time in AM/OpenAM (All versions)?

How do I change the amadmin password in AM/OpenAM (All versions)?

How do I change the dsameuser password in AM/OpenAM (All versions)?

How do I make a whole user data store read-only to users in AM/OpenAM (All versions)?

Administrator and user accounts in AM/OpenAM

Setup and Maintenance Guide › Setting Up Realms › Introducing Realms

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-13339 (Custom Admin can't view SAML or configuration tab)

OPENAM-6740 (need to add delegation privilege of checking a users' token's MaxTime to a privilege such as RealmAdmin)

OPENAM-5714 (Add support for more granular delegation privileges)

OPENAM-4713 (Can't use Common Tasks wizards when logged in as a delegated administrator)

OPENAM-4034 (AM REST needs delegation support)


Account Lockout


Understanding OpenAM 12.x, 13.x and OpenDJ 2.6.x, 3.x account lockout behaviors

The purpose of this article is to provide information to help you understand OpenAM and OpenDJ account lockout behaviors. Account Lockout can be performed in either OpenAM or the LDAP server itself, this includes a working example to lock a user’s account after 3 invalid password attempts and how to define a Password Policy in OpenDJ.

Background Information

The OpenAM Authentication Service can be configured to lock a user’s account after a defined number of log in attempts has failed. Account Lockout is disabled by default, but when configured properly, this feature can be useful in fending off brute force attacks against OpenAM login screens.

If your OpenAM environment includes an LDAP server (such as OpenDJ) as an authentication database, then you have options on how (and where) you can configure Account Lockout settings. This can be performed in either OpenAM (as mentioned above) or in the LDAP server, itself. But the behavior is different based on where this is configured. There are benefits and drawbacks towards configuring Account Lockout in either product and knowing the difference is essential.

Note

Configuring Account Lockout simultaneously in both products can lead to confusing results and should be avoided unless you have a firm understanding of how each product works.  See the scenario at the end of this article for a deeper dive on Account Lockout from an attribute perspective. 

The OpenAM Approach

You can configure Account Lockout in OpenAM either globally or for a particular realm. To access the Account Lockout settings for the global configuration:

  • OpenAM 13.5 and later console: navigate to: Configure > Authentication > Core Attributes > Account Lockout.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Authentication > Core > Account Lockout.

To access Account Lockout settings for a particular realm:

  • OpenAM 13 and later console: navigate to: Realms > [Realm Name] > Authentication > Settings > Account Lockout.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > All Core Settings > Account Lockout.

In either location you will see various parameters for controlling Account Lockout as follows (image for OpenAM 13 and later):

See How do I enable account lockout in AM/OpenAM (All versions)? for further information on the different types of account lockout.

Account Lockout is disabled by default; you need to enable Login Failure Lockout Mode to enable this feature. Once it is enabled, you configure the number of attempts before an account is locked and even if a warning message is displayed to the user before their account is locked.  You can configure how long the account is locked and even the duration between successive lockouts (which can increase if you set the duration multiplier).  You can configure the attributes to use to store the account lockout information in addition to the default attributes configured in the Data Store.

Enabling Account Lockout affects the following Data Store attributes: inetUserStatus and sunAMAuthInvalidAttemptsData. By default, the value of the inetUserStatus attribute is either Active or Inactive, but this can be configured to use another attribute and another attribute value. This can be configured in the User Configuration section of the Data Store configuration as follows:

These attributes are updated in the Data Store configuration for the realm. A benefit of implementing Account Lockout in OpenAM is that you can use any LDAPv3 directory, Active Directory, or even a relational database – but you do need to have a Data Store configured to provide OpenAM with somewhere to write these values. An additional benefit is that OpenAM is already configured with error messages that can be easily displayed when a user’s account is about to be locked or has become locked. Configuring Account Lockout within OpenAM, however, may not provide the level of granularity that you might need and as such, you may need to configure it in the authentication database (such as OpenDJ).

The OpenDJ Approach

OpenDJ can be configured to lock accounts as well. This is defined in a password policy and can be configured globally (the entire OpenDJ instance) or it may be applied to a subentry (a group of users or a specific user). Similar to OpenAM, a user’s account can be locked after a number of invalid authentication attempts have been made. And similar to OpenAM, you have several additional settings that can be configured to control the lockout period, whether warnings should be sent, and even who to notify when the account has been locked.

But while configuring Account Lockout in OpenAM may recognize invalid password attempts in your SSO environment, configuring it in OpenDJ will recognize invalid attempts for any application that is using OpenDJ as an authentication database. This is more of a centralized approach and can recognize attacks from several vectors.

Configuring Account Lockout in OpenDJ affects the following OpenDJ attributes:

  • pwdFailureTime (a multi-valued attribute consisting of the timestamp of each invalid password attempt).
  • pwdAccountLockedTime (a timestamp indicating when the account was locked).

Another benefit of implementing Account Lockout in OpenDJ is the ability to configure Account Lockout for different types of users. This is helpful when you want to have different password policies for users, administrators, or even service accounts. This is accomplished by assigning different password polices directly to those users or indirectly through groups or virtual attributes. A drawback to this approach, however, is that OpenAM doesn’t necessarily recognize the circumstances behind error messages returned from OpenDJ when a user is unable to log in. A scrambled password in OpenDJ, for instance, simply displays as an Authentication failed error message in the OpenAM login screen.

By default, all users in OpenDJ are automatically assigned a generic (rather lenient) password policy that is aptly named: Default Password Policy. The definition of this policy can be seen as follows:

dn: cn=Default Password Policy,cn=Password Policies,cn=config
objectClass: ds-cfg-password-policy
objectClass: top
objectClass: ds-cfg-authentication-policy
ds-cfg-skip-validation-for-administrators: false
ds-cfg-force-change-on-add: false
ds-cfg-state-update-failure-policy: reactive
ds-cfg-password-history-count: 0
ds-cfg-password-history-duration: 0 seconds
ds-cfg-allow-multiple-password-values: false
ds-cfg-lockout-failure-expiration-interval: 0 seconds
ds-cfg-lockout-failure-count: 0
ds-cfg-max-password-reset-age: 0 seconds
ds-cfg-max-password-age: 0 seconds
ds-cfg-idle-lockout-interval: 0 seconds
ds-cfg-java-class: org.opends.server.core.PasswordPolicyFactory
ds-cfg-lockout-duration: 0 seconds
ds-cfg-grace-login-count: 0
ds-cfg-force-change-on-reset: false
ds-cfg-default-password-storage-scheme: cn=Salted SHA-1,cn=Password Storage Schemes,cn=config
ds-cfg-allow-user-password-changes: true
ds-cfg-allow-pre-encoded-passwords: false
ds-cfg-require-secure-password-changes: false
cn: Default Password Policy
ds-cfg-require-secure-authentication: false
ds-cfg-expire-passwords-without-warning: false
ds-cfg-password-change-requires-current-password: false
ds-cfg-password-generator: cn=Random Password Generator,cn=Password Generators,cn=config
ds-cfg-password-expiration-warning-interval: 5 days
ds-cfg-allow-expired-password-changes: false
ds-cfg-password-attribute: userPassword
ds-cfg-min-password-age: 0 seconds

The value of the ds-cfg-lockout-failure-count attribute is 0; which means that user accounts are not locked by default – no matter how many incorrect attempts are made. This is one of the many security settings that you can configure in a password policy and while many of these mimic what is available in OpenAM, others go quite deeper.

You can use the OpenDJ dsconfig command to change the Default Password Policy as follows:

$ ./dsconfig set-password-policy-prop --policy-name "Default Password Policy" --set lockout-failure-count:3 --hostname localhost --port 4444 --trustAll --bindDN "cn=Directory Manager" --bindPassword ****** --no-prompt

Rather than modifying the Default Password Policy, a preferred method is to create a new password policy and apply your own specific settings to the new policy. This policy can then be applied to a specific set of users.

The syntax for using the OpenDJ dsconfig command to create a new password policy can be seen below:

$ ./dsconfig create-password-policy --set default-password-storage-scheme:"Salted SHA-1" --set password-attribute:userpassword --set lockout-failure-count:3 
  --type password-policy --policy-name "Example Corp User Password Policy" 
  --hostname localhost --port 4444 --trustAll --bindDN cn="Directory Manager" 
  --bindPassword ****** --no-prompt
Note

This example contains a minimum number of settings (default-password-storage-scheme, password-attribute, and lockout-failure-count). Consider adding additional settings to customize your password policy as desired.

You can now assign the password policy to an individual user by adding the following attribute as a subentry to the user’s object:

ds-pwp-password-policy-dn:  cn=Example Corp User Password Policy,cn=Password Policies, cn=config

This can be performed using any LDAP client where you have write permissions to a user’s entry. The following example uses the ldapmodify command in an interactive mode to perform this operation:

$ ./ldapmodify -D "cn=Directory Manager" -w ****** <ENTER>
dn: uid=bnelson,ou=People,dc=example,dc=com <ENTER>
changetype: modify <ENTER>
replace: ds-pwp-password-policy-dn <ENTER>
ds-pwp-password-policy-dn: cn=Example Corp User Password Policy,
  cn=Password Policies,cn=config <ENTER>
<ENTER>

Another method of setting this password policy is through the use of a dynamically created virtual attribute (that is, one that is not persisted in the OpenDJ database backend). The following definition automatically assigns this new password policy to all users that exist beneath the ou=people container (the scope of the virtual attribute):

dn: cn=Example Corp User Password Policy Assignment,cn=Virtual Attributes,cn=config
objectClass: ds-cfg-virtual-attribute
objectClass: ds-cfg-user-defined-virtual-attribute
objectClass: top
ds-cfg-base-dn: ou=people,dc=example,dc=com
cn: Example Corp User Password Policy Assignment
ds-cfg-attribute-type: ds-pwp-password-policy-dn
ds-cfg-enabled: true
ds-cfg-java-class: org.opends.server.extensions.UserDefinedVirtualAttributeProvider
ds-cfg-filter: (objectclass=sbacperson)
ds-cfg-value: cn=Example Corp User Password Policy,cn=Password Policies,cn=config
Note

You can also use filters to create very granular results on how password polices are applied.

Configuring Account Lockout in OpenDJ has more flexibility and as such may be considered to be more powerful than OpenAM in this area. The potential confusion, however, comes when attempting to unlock a user’s account when they have been locked out of both OpenAM and OpenDJ. This is described in the following example.

A Deeper Dive into Account Lockout

Consider an environment where OpenAM is configured with the LDAP authentication module and that module has been configured to use an OpenDJ instance as the authentication database:

 

OpenAM and OpenDJ have both been configured to lock a user’s account after 3 invalid password attempts. What kind of behavior can you expect? Let’s walk through each step of an Account Lockout process and observe the behavior on Account Lockout specific attributes.

Step 1:  Query Account Lockout Specific Attributes for the Test User

$ ./ldapsearch -D "cn=Directory Manager" -w ****** uid=testuser1 inetuserstatus \
  sunAMAuthInvalidAttemptsData pwdFailureTime pwdAccountLockedTime

dn: uid=testuser1,ou=test,dc=example,dc=com
inetuserstatus: Active

The user is currently active and Account Lockout specific attributes are empty.

Step 2:  Open the OpenAM Console and access the login screen for the realm where Account Lockout has been configured.

Step 3:  Enter an invalid password for this user

Step 4:  Query Account Lockout Specific Attributes for the Test User

$ ./ldapsearch -D "cn=Directory Manager" -w ****** uid=testuser1 inetuserstatus \
  sunAMAuthInvalidAttemptsData pwdFailureTime pwdAccountLockedTime

dn: uid=testuser1,ou=test,dc=example,dc=com
sunAMAuthInvalidAttemptsData:: PEludmFsaWRQYXNzd29yZD48SW52YWxpZENvdW50PjE8L0
  ludmFsaWRDb3VudD48TGFzdEludmFsaWRBdD4xMzk4MTcxNTAwMDE4PC9MYXN0SW52YWxpZEF0P
  jxMb2NrZWRvdXRBdD4wPC9Mb2NrZWRvdXRBdD48QWN0dWFsTG9ja291dER1cmF0aW9uPjA8L0Fj
  dHVhbExvY2tvdXREdXJhdGlvbj48L0ludmFsaWRQYXNzd29yZD4=
inetuserstatus: Active
pwdFailureTime: 20140422125819.918Z

You now see that there is a value for the pwdFailureTime. This is the timestamp of when the first password failure occurred. This attribute was populated by OpenDJ.

The sunAMAuthInvalidAttemptsData attribute is populated by OpenAM. This is a base64 encoded value that contains valuable information regarding the invalid password attempt. Run this through a base64 decoder and you will see that this attribute contains the following information:

<InvalidPassword><InvalidCount>1</InvalidCount><LastInvalidAt>1398171500018
  </LastInvalidAt><LockedoutAt>0</LockedoutAt><ActualLockoutDuration>0
  </ActualLockoutDuration></InvalidPassword>

Step 5:  Repeat Steps 2 and 3. (This is the second password failure.)

Step 6:  Query Account Lockout Specific Attributes for the Test User

$ ./ldapsearch -D "cn=Directory Manager" -w ****** uid=testuser1 inetuserstatus \
  sunAMAuthInvalidAttemptsData pwdFailureTime pwdAccountLockedTime

dn: uid=testuser1,ou=test,dc=example,dc=com
sunAMAuthInvalidAttemptsData:: PEludmFsaWRQYXNzd29yZD48SW52YWxpZENvdW50PjI8L0
  ludmFsaWRDb3VudD48TGFzdEludmFsaWRBdD4xMzk4MTcxNTUzMzUwPC9MYXN0SW52YWxpZEF0P
  jxMb2NrZWRvdXRBdD4wPC9Mb2NrZWRvdXRBdD48QWN0dWFsTG9ja291dER1cmF0aW9uPjA8L0Fj
  dHVhbExvY2tvdXREdXJhdGlvbj48L0ludmFsaWRQYXNzd29yZD4=
inetuserstatus: Active
pwdFailureTime: 20140422125819.918Z
pwdFailureTime: 20140422125913.151Z

There are now two values for the pwdFailureTime attribute – one for each password failure. The sunAMAuthInvalidAttemptsData attribute has been updated as follows:

<InvalidPassword><InvalidCount>2</InvalidCount><LastInvalidAt>1398171553350
  </LastInvalidAt><LockedoutAt>0</LockedoutAt><ActualLockoutDuration>0
  </ActualLockoutDuration></InvalidPassword>

Step 7:  Repeat Steps 2 and 3.  (This is the third and final password failure.)

OpenAM displays an error message indicating that the user’s account has been locked.

Step 8:  Query Account Lockout Specific Attributes for the Test User

$ ./ldapsearch -D "cn=Directory Manager" -w ****** uid=testuser1 inetuserstatus \ 
  sunAMAuthInvalidAttemptsData pwdFailureTime pwdAccountLockedTime

dn: uid=testuser1,ou=test,dc=example,dc=com
sunAMAuthInvalidAttemptsData:: PEludmFsaWRQYXNzd29yZD48SW52YWxpZENvdW50PjA8L0
  ludmFsaWRDb3VudD48TGFzdEludmFsaWRBdD4wPC9MYXN0SW52YWxpZEF0PjxMb2NrZWRvdXRBd
  D4wPC9Mb2NrZWRvdXRBdD48QWN0dWFsTG9ja291dER1cmF0aW9uPjA8L0FjdHVhbExvY2tvdXRE
  dXJhdGlvbj48L0ludmFsaWRQYXNzd29yZD4=
inetuserstatus: Inactive
pwdFailureTime: 20140422125819.918Z
pwdFailureTime: 20140422125913.151Z
pwdFailureTime: 20140422125944.771Z
pwdAccountLockedTime: 20140422125944.771Z

There are now three values for the pwdFailureTime attribute – one for each password failure. The sunAMAuthInvalidAttemptsData attribute has been updated as follows:

<InvalidPassword><InvalidCount>0</InvalidCount><LastInvalidAt>0</LastInvalidAt>
  <LockedoutAt>0</LockedoutAt><ActualLockoutDuration>0</ActualLockoutDuration>
  </InvalidPassword>

You will note that the counters have all been reset to zero. That is because the user’s account has been inactivated by OpenAM by setting the value of the inetuserstatus attribute to Inactive. Additionally, the third invalid password caused OpenDJ to lock the account by setting the value of the pwdAccountLockedTime attribute to the value of the last password failure.

Now that the account is locked out, how do you unlock it? The natural thing for an OpenAM administrator to do is to reset the value of the inetuserstatus attribute and they would most likely use the OpenAM Console to do this as follows:

The problem with this approach is that while the user’s status in OpenAM is now made active, the status in OpenDJ remains locked.

$ ./ldapsearch -D "cn=Directory Manager" -w ****** uid=testuser1 inetuserstatus \
  sunAMAuthInvalidAttemptsData pwdFailureTime pwdAccountLockedTime

dn: uid=testuser1,ou=test,dc=example,dc=com
sunAMAuthInvalidAttemptsData:: PEludmFsaWRQYXNzd29yZD48SW52YWxpZENvdW50PjA8L0
  ludmFsaWRDb3VudD48TGFzdEludmFsaWRBdD4wPC9MYXN0SW52YWxpZEF0PjxMb2NrZWRvdXRBd
  D4wPC9Mb2NrZWRvdXRBdD48QWN0dWFsTG9ja291dER1cmF0aW9uPjA8L0FjdHVhbExvY2tvdXRE
  dXJhdGlvbj48L0ludmFsaWRQYXNzd29yZD4=
inetuserstatus: Active
pwdFailureTime: 20140422125819.918Z
pwdFailureTime: 20140422125913.151Z
pwdFailureTime: 20140422125944.771Z
pwdAccountLockedTime: 20140422125944.771Z

Attempting to log in to OpenAM with this user’s account yields an authentication error that would make most OpenAM administrators scratch their head; especially after just resetting the user’s status.

The trick to fixing this is to clear the pwdAccountLockedTime and pwdFailureTime attributes and the way to do this is by modifying the user’s password. Once again, the ldapmodify command can be used as follows:

$ ./ldapmodify -D "cn=Directory Manager" -w ****** <ENTER>
dn: uid=testuser1,ou=test,dc=example,dc=com <ENTER>
changetype: modify <ENTER>
replace: userPassword <ENTER>
userPassword: newpassword <ENTER>
<ENTER>
$ ./ldapsearch -D "cn=Directory Manager" -w ****** uid=testuser1 inetuserstatus \
  sunAMAuthInvalidAttemptsData pwdFailureTime pwdAccountLockedTime

dn: uid=testuser1,ou=test,dc=example,dc=com
sunAMAuthInvalidAttemptsData:: PEludmFsaWRQYXNzd29yZD48SW52YWxpZENvdW50PjA8L0
  ludmFsaWRDb3VudD48TGFzdEludmFsaWRBdD4wPC9MYXN0SW52YWxpZEF0PjxMb2NrZWRvdXRBd
  D4wPC9Mb2NrZWRvdXRBdD48QWN0dWFsTG9ja291dER1cmF0aW9uPjA8L0FjdHVhbExvY2tvdXRE
  dXJhdGlvbj48L0ludmFsaWRQYXNzd29yZD4=
inetuserstatus: Active
pwdChangedTime: 20140422172242.676Z

This, however, requires two different interfaces for managing the user’s account. An easier method is to combine the changes into one interface. You can modify the inetuserstatus attribute using ldapmodify or if you are using the OpenAM Console, simply change the password while you are updating the user’s status.

There are other ways to update one attribute by simply modifying the other. This can range in complexity from a simple virtual attribute to a more complex yet powerful custom OpenDJ plugin. But in the words of Voltaire, “With great power comes great responsibility.”

So go forth and wield your new found power; but do it in a responsible manner.

Contributed by Bill Nelson (idmdude)

See Also

idmdude - Understanding OpenAM and OpenDJ Account Lockout Behaviors

How do I enable account lockout in AM/OpenAM (All versions)?

How do I unlock a user's account using the REST API in AM/OpenAM (All versions)?

FAQ: Passwords in DS/OpenDJ

OpenAM Administration Guide › Defining Authentication Services › Configuring Account Lockout

OpenDJ Administration Guide › Configuring Password Policy


How do I enable account lockout in AM/OpenAM (All versions)?

The purpose of this article is to provide information on enabling account lockout in AM/OpenAM and conversely, unlocking the user's account. It also discusses the different types of account lockout.

Overview

The following types of account lockout are available, which determine how user accounts are locked and unlocked:

  • Persistent (physical) lockout (if you use authentication chains)
  • Memory lockout (if you use authentication chains)
  • Account lockout node (if you use authentication trees in AM 6 and later)
  • Directory server-based account lockout
Note

It is not possible to have both the user status updated (persistent lockout) and the user account automatically unlocked (memory lockout) using the account lockout functionality in AM/OpenAM.

Persistent lockout

This is the default account lockout type when you use authentication chains. When a user is locked out with persistent lockout, their user status (the inetUserStatus attribute) is changed to Inactive in the user store (both the attribute and status value are configurable). The user is not unlocked automatically; the amadmin user must unlock them using the REST API (see How do I unlock a user's account using the REST API in AM/OpenAM (All versions)?) or the console:

  • AM 6 and later console: navigate to: Realms > [Realm Name] > Identities > [User Name] > User Status and select Active.
  • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Subjects > User > [User Name] > User Status and select the Active option.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Subjects > User > [User Name] > User Status and select the Active option.

See the Enabling account lockout section for further information on configuring this account lockout behavior.

Memory lockout

This lockout type locks the user in memory only, meaning AM/OpenAM stores account lockout in its own memory (which is not shared across instances) and does not change the user's status (the inetUserStatus attribute) in the user store. When a user is locked in memory, they must wait the specified number of minutes for their account to automatically unlock. The amadmin user can unlock a user account using the REST API (see How do I unlock a user's account using the REST API in AM/OpenAM (All versions)?) or by disabling the memory account lockout behavior, but this unlocks all users locked in memory. Similarly, if AM/OpenAM is restarted, all users locked in memory are unlocked.

See the Enabling account lockout section for further information on configuring this account lockout behavior.

Account lockout node

If you use authentication trees in AM 6 and later, you can use the Account lockout node to lock/unlock the user's profile account as described in Authentication and Single Sign-On Guide › Account lockout Node. See Best practice for migrating Authentication Chains to Trees in AM 6.x for further information.

You can also unlock users via REST or the the console as detailed above for persistent lockout; when a user is locked via the Account lockout node, their user status (the inetUserStatus attribute) is changed to Inactive in the user store.

Directory server based account lockout

If you use DS/OpenDJ as your user store, you should refer to: Administration Guide › Configuring Account Lockout for further information on configuring account lockout.

Additionally, if you want DS/OpenDJ to warn users of impending lockouts, you must use the LDAP authentication module in AM/OpenAM and enable LDAP Behera Password Policy Support within this module. See Authentication and Single Sign-On Guide › LDAP Authentication Module for further information on this authentication module.

Enabling account lockout

If you use authentication chains, you can enable account lockout and define the attributes that will result in account lockout (such as number of failed login attempts) at the global or realm level (navigation details / ssoadm commands given below).

The following table indicates which attributes must, or can, be set according to the account lockout type:

Attributes Persistent lockout Memory lockout
Login Failure Lockout Mode Must be set to enable account lockout. Must be set to enable account lockout.
Login Failure Lockout Count Optional. Optional.
Login Failure Lockout Interval Optional. Optional.
Email Address to Send Lockout Notification Optional. Optional.
Warn User After N Failures Optional. Optional.
Login Failure Lockout Duration N/A Must be set to a value greater than 0 to enable memory lockout. Setting this back to 0 disables memory lockout and re-enables persistent lockout. 
Lockout Duration Multiplier N/A Optional.
Lockout Attribute Name Optional. N/A
Lockout Attribute Value Optional. N/A
Invalid Attempts Data Attribute Name Optional. Optional.
Store Invalid Attempts in Data Store Optional. Optional.

See Authentication and Single Sign-On Guide › Account Lockout for further information on the available configuration attributes and the equivalent ssoadm attribute names.

Global level

You can configure account lockout at the global level using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Authentication > Core Attributes > Account Lockout and set the relevant fields.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Authentication > Core > Account Lockout and set the relevant fields.
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u [adminID] -f [passwordfile] -a iplanet-am-auth-login-failure-lockout-mode=true [attributes]
    replacing [adminID], [passwordfile] and [attributes] with appropriate values. You can specify multiple attribute names and values by using a space between them as a separator.

An example ssoadm command to set three account lockout attributes at the global level looks like this:

$ ./ssoadm set-attr-defs -s iPlanetAMAuthService -t organization -u amadmin -f pwd.txt -a iplanet-am-auth-login-failure-lockout-mode=true iplanet-am-auth-login-failure-count=3 iplanet-am-auth-login-failure-duration=10
Note

There is a known issue in AM 5 that prevents you configuring Account Lockout at a global level using the console: OPENAM-11036 (Cannot configure Account Lockout at a global level in AM 5 console). You can configure it using ssoadm or at a realm level instead.

Realm level 

You can configure account lockout at the realm level using either the console or ssoadm:

  • AM / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Authentication > Settings > Account Lockout and set the relevant fields.
  • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Authentication > All Core Settings > Account Lockout and set the relevant fields.
  • ssoadm: enter the following command:
    $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e [realmname] -u [adminID] -f [passwordfile] -a iplanet-am-auth-login-failure-lockout-mode=true [attributes]
    replacing [realmname], [adminID], [passwordfile] and [attributes] with appropriate values. You can specify multiple attribute names and values by using a space between them as a separator. 

An example ssoadm command to set three account lockout attributes at the realm level looks like this:

$ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e employees -u amadmin -f pwd.txt -a iplanet-am-auth-login-failure-lockout-mode=true iplanet-am-auth-login-failure-count=3 iplanet-am-auth-login-failure-duration=10

Checking persistent account lockout status

You can check the persistent account lockout status of a user by querying the inetUserStatus attribute using the ldapsearch command, for example:

$ ./ldapsearch --port 50389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org" "objectclass=*"

Example response, which shows the status of the inetUserStatus attribute:

dn: uid=demo,ou=people,dc=openam,dc=forgerock,dc=org
objectClass: person
objectClass: inetorgperson
objectClass: sunFederationManagerDataStore
objectClass: iplanet-am-auth-configuration-service
objectClass: kbaInfoContainer
objectClass: organizationalperson
objectClass: sunIdentityServerLibertyPPService
objectClass: inetuser
objectClass: sunAMAuthAccountLockout
objectClass: iPlanetPreferences
objectClass: devicePrintProfilesContainer
objectClass: forgerock-am-dashboard-service
objectClass: sunFMSAML2NameIdentifier
objectClass: iplanet-am-managed-person
objectClass: iplanet-am-user-service
objectClass: top
objectClass: oathDeviceProfilesContainer
uid: demo
mail: demo@test.com
sn: demo
userPassword: {SSHA}Os1Rlw0qGB+hrhRCQDBna+NlKQ+/BDNUoMYVlg==
cn: demo
givenName: demo
kbaInfo: { "answer": { "$crypto": { "value": { "algorithm": "SHA-256", "data": "
 JDz7McsAgRJkeMpCdPp3D702kA7GTPFRkjhd2qys+DJXmluzcVwaT0CXCrQtn0mf" }, "type": "s
 alted-hash" } }, "questionId": "2" }
inetUserStatus: Inactive
sunAMAuthInvalidAttemptsData:: PEludmFsaWRQYXNzd29yZD48SW52YWxpZENvdW50PjA8L0lud
 mFsaWRDb3VudD48TGFzdEludmFsaWRBdD4wPC9MYXN0SW52YWxpZEF0PjxMb2NrZWRvdXRBdD4wPC9M
 b2NrZWRvdXRBdD48QWN0dWFsTG9ja291dER1cmF0aW9uPjA8L0FjdHVhbExvY2tvdXREdXJhdGlvbj4
 8L0ludmFsaWRQYXNzd29yZD4=

See Also

How do I unlock a user's account using the REST API in AM/OpenAM (All versions)?

How do I lock a user's account if they do not authenticate to AM/OpenAM (All versions) within a specific period of time?

Administrator and user accounts in AM/OpenAM

Authentication and Single Sign-On Guide › Implementing Account Lockout

Authentication and Single Sign-On Guide › Account lockout Node

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12378 (Are Two Different Message responses for 401 responses when account locked in memory, or persistent)

OPENAM-11036 (Cannot configure Account Lockout at a global level in AM 5 console)

OPENAM-10393 (Account lockout messages need to be more configurable)

OPENAM-6362 (HOTP and OATH auth-modules do not set 'failureUserID' when throwing InvalidPasswordException, this breaks OpenAM account lockout)


How do I lock a user's account if they do not authenticate to AM/OpenAM (All versions) within a specific period of time?

The purpose of this article is to provide assistance on configuring AM/OpenAM to automatically lock a user's account if they do not log in to AM/OpenAM for a certain period of time due to inactivity.

Locking a user's account

Configuration

You can configure AM/OpenAM to automatically lock a user's account by creating a password policy in DS/OpenDJ with the following attributes:

  • idle-lockout-interval - this should be set to the maximum length of time that an account can be idle before it gets locked. You must also set the following attribute to allow the last login time to be tracked.
  • last-login-time-attribute - this should be set to the name of the attribute type that holds the last login time for a user. 

For example, you can create a custom password policy that includes these attributes using the dsconfig command as follows:

$ ./dsconfig create-password-policy --port 4444 --hostname ds1.example.com --bindDN "cn=Directory Manager" --bindPassword password --policy-name "Lock Users Policy" --set default-password-storage-scheme:"Salted SHA-1" --set password-attribute:userPassword --set last-login-time-attribute:ds-pwp-last-login-time --set last-login-time-format:yyyyMMddHHmmss --set idle-lockout-interval:"30 m" --type password-policy --trustAll --no-prompt

You then need to assign this password policy to all applicable users. See Administration Guide › Configuring Password Policy, Administration Guide › Configuring Password Policy › Assigning Password Policies and Configuration Reference › Password Policy for further information.

Note

The user must log in at least once for this feature to work. If they have never logged in, their account won't get locked regardless of how long the user has been inactive. You could consider automatically logging in as the user once the password policy has been assigned to add the last-login-time-attribute to their profile.

Locking a user's account

Once configured, a user's account will be locked unless they log in within the idle-lockout-interval specified. If their account gets locked, they will see a message such as the following:

Your account is locked. Please contact service desk to unlock your account

The exact message may vary depending on your configuration and AM/OpenAM version. This is the standard message if you are using the LDAP authentication module and have Behera password policy controls in place.

Unlocking a user's account

You can unlock a user's account by resetting or changing their password, or using the DS/OpenDJ manage-account tool. See Administration Guide › Implementing Account Lockout and Notification › Managing Accounts Manually and Reference › Tools Reference › manage-account for further information.

See Also

How do I enable account lockout in AM/OpenAM (All versions)?

Understanding OpenAM 12.x, 13.x and OpenDJ 2.6.x, 3.x account lockout behaviors

FAQ: Passwords in DS/OpenDJ

Administrator and user accounts in AM/OpenAM

Administration Guide › Configuring Password Policy 

Administration Guide › Configuring Password Policy › Assigning Password Policies

Configuration Reference › Password Policy

Administration Guide › Implementing Account Lockout and Notification

Administration Guide › Implementing Account Lockout and Notification › Managing Accounts Manually 

Reference › Tools Reference › manage-account

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8924 (When a user tries to change their password in OpenAM, they do not get a useful message when they violate a password policy in OpenDJ)


How do I unlock a user's account using the REST API in AM/OpenAM (All versions)?

The purpose of this article is to provide information on using the REST API to unlock user accounts in AM/OpenAM. The REST API can be used to unlock a user's account that has been locked using either persistent (physical) lockout or memory lockout (if you use authentication chains) or the Account lockout node (if you use authentication trees in AM 6 and later).

Background information

The way in which a user account can be unlocked using the REST API depends on how it has been locked in the first place. You can lock user accounts using persistent lockout, memory lockout or the Account lockout node as detailed in How do I enable account lockout in AM/OpenAM (All versions)?

Persistent lockout and Account lockout node

The ability to unlock a user's account that has been persistently locked or locked via the Account lockout node relies on resetting the inetUserStatus attribute to Active. When a user is persistently locked out or locked via the Account lockout node, their user status (the inetUserStatus attribute) is changed to Inactive in the user store (both the attribute and status value are configurable). 

See the Unlocking a user's account (physical lockout and Account lockout node) section for details on unlocking a user's account using the REST API.

Memory lockout

The ability to unlock a user's account that is locked via memory lockout relies on using the Store Invalid Attempts in Data Store option. When the Store Invalid Attempts in Data Store option is enabled, AM/OpenAM stores information about invalid authentication attempts in the user's profile. By default, this information is stored in the sunAMAuthInvalidAttemptsData attribute; however, you can store this information in a different attribute by setting the Invalid Attempts Data Attribute Name field to the required attribute (this must be a valid attribute in the user data store).

The purpose of the Store Invalid Attempts in Data Store option is primarily to allow other AM/OpenAM servers to determine the lockout state across a cluster; however, you can also delete the value of this attribute to manually unlock a user's account. Since memory lockout is being used, the inetUserStatus attribute is not changed and remains set to Active even when the user's account is locked.

In summary, you must set at least the following Account Lockout options to be able to use the REST API to unlock user accounts:

  • Login Failure Lockout Mode - enabled.
  • Login Failure Lockout Duration - set to a value greater than 0 to enable memory lockout.
  • Store Invalid Attempts in Data Store - enabled.

See the Unlocking a user's account (memory lockout) section for details on unlocking a user's account using the REST API.

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM/OpenAM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains a valid resource version (AM 5 and later).

See How do I avoid common issues with REST calls in AM/OpenAM (All versions)? for further information.

Unlocking a user's account (persistent lockout and Account lockout node)

The following example assumes you are using the default inetUserStatus attribute; if you have changed it, substitute your attribute for the inetUserStatus attribute in the curl command. 

The commands used vary between AM/OpenAM versions:

AM 5 and later

  1. Authenticate as an admin user. For example:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1"  http://host1.example.com:8080/openam/json/realms/root/authenticate
    
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
    
  2. Unlock the user's account (in this example, demo) using the following curl command:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -H "Accept-API-Version: resource=3.0" -d'{
        "inetUserStatus": "Active"
    }' http://host1.example.com:8080/openam/json/realms/root/users/demo
    Example response:
    {
      "username": "demo",
      "realm": "/",
      "uid": [
        "demo"
      ],
      "universalid": [
        "id=demo,ou=user,dc=openam,dc=forgerock,dc=org"
      ],
      "objectClass": [
        "iplanet-am-managed-person",
        "inetuser",
        "sunFederationManagerDataStore",
        "sunFMSAML2NameIdentifier",
        "devicePrintProfilesContainer",
        "inetorgperson",
        "sunIdentityServerLibertyPPService",
        "iPlanetPreferences",
        "pushDeviceProfilesContainer",
        "iplanet-am-user-service",
        "forgerock-am-dashboard-service",
        "organizationalperson",
        "top",
        "kbaInfoContainer",
        "sunAMAuthAccountLockout",
        "person",
        "oathDeviceProfilesContainer",
        "iplanet-am-auth-configuration-service"
      ],
      "dn": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
      ],
      "inetUserStatus": [
        "Active"
      ],
      "sn": [
        "demo"
      ],
      "cn": [
        "demo"
      ],
      "iplanet-am-user-auth-config": [
        "ldapService"
      ],
      "createTimestamp": [
        "20160721105610Z"
      ],
      "modifyTimestamp": [
        "20160727134147Z"
      ]
    }
    

Pre-AM 5 

The commands differ in earlier versions of OpenAM, but the responses are similar to the ones shown above:

  1. Authenticate as an admin user. For example:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate
  2. Unlock the user's account (in this example, demo) using the following curl command:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -d'{
        "inetUserStatus": "Active"
    }' http://host1.example.com:8080/openam/json/users/demo

Unlocking a user's account (memory lockout)

The following example assumes you are using the default sunAMAuthInvalidAttemptsData attribute; if you have changed it, substitute your attribute for the sunAMAuthInvalidAttemptsData attribute in the curl command. The commands used vary between AM/OpenAM versions:

AM 5 and later

  1. Authenticate as an admin user. For example:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1"  http://host1.example.com:8080/openam/json/realms/root/authenticate
    
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
    
  2. Unlock the user's account (in this example, demo) using the following curl command:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -H "Accept-API-Version: resource=3.0" -d'{
        "sunAMAuthInvalidAttemptsData": []
    }' http://host1.example.com:8080/openam/json/realms/root/users/demo
    Example response:
    {
      "username": "demo",
      "realm": "/",
      "uid": [
        "demo"
      ],
      "universalid": [
        "id=demo,ou=user,dc=openam,dc=forgerock,dc=org"
      ],
      "objectClass": [
        "iplanet-am-managed-person",
        "inetuser",
        "sunFederationManagerDataStore",
        "sunFMSAML2NameIdentifier",
        "devicePrintProfilesContainer",
        "inetorgperson",
        "sunIdentityServerLibertyPPService",
        "iPlanetPreferences",
        "pushDeviceProfilesContainer",
        "iplanet-am-user-service",
        "forgerock-am-dashboard-service",
        "organizationalperson",
        "top",
        "kbaInfoContainer",
        "sunAMAuthAccountLockout",
        "person",
        "oathDeviceProfilesContainer",
        "iplanet-am-auth-configuration-service"
      ],
      "dn": [
        "uid=demo,ou=people,dc=openam,dc=forgerock,dc=org"
      ],
      "inetUserStatus": [
        "Active"
      ],
      "sn": [
        "demo"
      ],
      "cn": [
        "demo"
      ],
      "iplanet-am-user-auth-config": [
        "ldapService"
      ],
      "createTimestamp": [
        "20160721105610Z"
      ],
      "modifyTimestamp": [
        "20160727134147Z"
      ]
    }
    

Pre-AM 5 

The commands differ in earlier versions of OpenAM, but the responses are similar to the ones shown above:

  1. Authenticate as an admin user. For example:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate
  2. Unlock the user's account (in this example, demo) using the following curl command:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -d'{
        "sunAMAuthInvalidAttemptsData": []
    }' http://host1.example.com:8080/openam/json/users/demo
    

See Also

How do I enable account lockout in AM/OpenAM (All versions)?

Minimum password length is 8 error in AM (All versions) when updating identities using the REST API

Authentication and Single Sign-On Guide › Account Lockout

Authentication and Single Sign-On Guide › Account lockout Node

Authentication and Single Sign-On Guide › Specifying Realms in REST API Calls

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11052 (Minimum password length is 8 error in AM 5.0 when updating identities using the REST API)


How do I change the search attribute used to search for users in AM/OpenAM console (All versions)?

The purpose of this article is to provide information on changing the search attribute used when searching for users in AM/OpenAM. The default search attribute is cn and is used when searching for users on the Identities page (previously the Subjects tab).

Changing the search attribute

You may need to change the search attribute being used to provide more meaningful searches, for example, you could change the search attribute to uid to search on user IDs. You can only have one search attribute as the Identities page is only designed to perform simple user searches; more sophisticated searches should be performed using an LDAP browser or a dedicated tool for managing users such as IDM/OpenIDM or DS/OpenDJ.

You can change the search attribute via the following ssoadm command (it cannot be changed in the console):

$ ./ssoadm set-attr-defs -s iPlanetAMAdminConsoleService -t organization -u [adminID] -f [passwordfile] -a iplanet-am-admin-console-user-search-key=[searchattribute]

replacing [adminID], [passwordfile] and [searchattribute] with appropriate values.

Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes. 

See Also

FAQ: Users in AM/OpenAM

Administrator and user accounts in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I make individual user profile attributes read-only in AM/OpenAM (All versions)?

The purpose of this article is to provide information on making individual user profile attributes read-only in AM/OpenAM. You would do this if you want to prevent end users from changing certain fields shown on the XUI User Profile page.

Making individual user profile attributes read-only (AM 6 and later)

Changes have been made in AM 6 to optimize XUI delivery using Webpack as detailed in the Release Notes › Major Improvements (General).

You can make individual user profile attributes read-only as follows:

  1. Follow the steps in UI Customization Guide › Downloading the XUI to obtain the XUI source.
  2. Edit the UserProfileTemplate.html file (located in the /am-external/openam-ui/openam-ui-ria/src/main/resources/templates/user directory) and add readonly=true to any attributes you want to make read-only. For example, the amendments would look like this to make First Name and Last Name read-only:
    <div class="panel-body">
        {{#user}}
            {{> form/_basicInput property="username" label="common.user.username" readonly=true}}
            {{> form/_basicInput property="givenName" label="common.user.givenName readonly=true"}}
            {{> form/_basicInput property="sn" label="common.user.sn" required="true readonly=true"}}
            {{> form/_basicInput type="email" property="mail" label="common.user.emailAddress"
            extraAttributes='data-validator="validEmailAddressFormat" data-validator-event="keyup"' }}
            {{> form/_basicInput type="tel" property="telephoneNumber" label="common.user.phoneNumber"
            extraAttributes='data-validator="validPhoneFormat" data-validator-event="keyup"'}}
        {{/user}}
    </div>
    
  3. Follow steps in UI Customization Guide › Testing and Deploying the XUI to test your changes, then rebuild and deploy.

The User Profile page now shows the First Name and Last Name fields have been grayed out to indicate the values in these fields are hard-coded :

Making individual user profile attributes read-only (AM 5.x and OpenAM 13.x)

The following process demonstrates making the First Name and Last Name on the User Profile page read-only in AM 5.x and OpenAM 13.x:

  1. Edit the UserProfileTemplate.html file (located in the /path/to/tomcat/webapps/openam/XUI/templates/user directory) and add readonly=true to any attributes you want to make read-only. For example, the amendments would look like this to make First Name and Last Name read-only:
    <div class="panel-body">
        {{#user}}
            {{> form/_basicInput property="username" label="common.user.username" readonly=true}}
            {{> form/_basicInput property="givenName" label="common.user.givenName readonly=true"}}
            {{> form/_basicInput property="sn" label="common.user.sn" required="true readonly=true"}}
            {{> form/_basicInput type="email" property="mail" label="common.user.emailAddress"
            extraAttributes='data-validator="validEmailAddressFormat" data-validator-event="keyup"' }}
            {{> form/_basicInput type="tel" property="telephoneNumber" label="common.user.phoneNumber"
            extraAttributes='data-validator="validPhoneFormat" data-validator-event="keyup"'}}
        {{/user}}
    </div>
    
  2. Clear your browser cache.

The User Profile page now shows the First Name and Last Name fields have been grayed out to indicate the values in these fields are hard-coded :

Note

You must make these changes in the openam.war file to make them permanent.

Making individual user profile attributes read-only (OpenAM 12.x)

The following process demonstrates making the First Name and Last Name on the User Profile page read-only in OpenAM 12.x:

  1. Edit the UserProfileTemplate.html file (located in the /path/to/tomcat/webapps/openam/XUI/templates/user directory) and add readonly to the input type tag for any attributes you want to make read-only. For example, the amendments would look like this to make First Name and Last Name read-only:
                    <div class="group-field-block col2">
                        <label for="givenName" class="light align-right">{{t "common.user.givenName"}}</label>
                        <div class="float-left separate-message">
                            <div class="group-input-span">
                                <input type="text" id="givenName" name="givenName" value="" autofocus readonly />
                                <span class="error"></span>
                            </div>
                            <div class="validation-message"></div>
                        </div>
                    </div>
    
                    <div class="group-field-block col2">
                        <label for="sn" class="light align-right">{{t "common.user.familyName"}}</label>
                        <div class="float-left separate-message">
                            <div class="group-input-span">
                                <input type="text" id="sn" name="sn" value="" readonly />
                                <span class="error"></span>
                            </div>
                            <div class="validation-message"></div>
                        </div>
                    </div>
           
                </div>
    
                <div class="clearfix">
    
                    <div class="group-field-block col2">
                        <label for="mail" class="light align-right">{{t "common.user.emailAddress"}}</label>
                        <div class="float-left separate-message">
                            <div class="group-input-span">
                                <input type="email" id="mail" name="mail" value="" />
                                <span class="error"></span>
                            </div>
                            <div class="validation-message"></div>
                        </div>
                    </div>
    
                    <div class="group-field-block col2">
                        <label for="telephoneNumber" class="light align-right">{{t "common.user.phoneNumber"}}</label>
                        <div class="float-left separate-message">
                            <div class="group-input-span">
                                <input type="tel" id="telephoneNumber" name="telephoneNumber" value="" />
                                <span class="error"></span>
                            </div>
                            <div class="validation-message"></div>
                        </div>
                    </div>
    
  2. Restart the web application container in which AM/OpenAM runs and clear your browser cache.

The User Profile page now shows the First Name and Last Name fields have been grayed out to indicate the values in these fields are hard-coded :

Note

You must make these changes in the openam.war file to make them permanent.

See Also

How do I make a whole user data store read-only to users in AM/OpenAM (All versions)?

FAQ: Customizing, branding and localizing XUI end user pages in AM/OpenAM

UI Customization Guide › Customizing the XUI Layout

Related Training

N/A

Related Issue Tracker IDs

OPENAM-517 (setting values "readOnly" and "userReadOnly" in the "any" parameter of the amUser.xml file cause attributes to be hidden in the console/idm/EndUser)


User Passwords


How do I change the data store minimum password length in AM/OpenAM (All versions)?

The purpose of this article is to provide information on changing the data store minimum password length in AM/OpenAM. The minimum password length defaults to 8; this is a data store setting that applies to password changes (when existing users reset their password or change their password) and is independent of any password length restrictions in DS/OpenDJ. This also includes forgotten password resets made via the REST API user self-service functionality (XUI).

Overview

You can change the data store minimum password length using ssoadm (in all versions) or Amster (in AM 5 and later):

This setting cannot be changed in the console.

Using Amster

You can change the data store minimum password length using Amster; you can do this globally or in a specific realm, where realm level takes precedence over the global level. 

Follow the steps in How do I update property values in AM (All versions) using Amster?with these values:

  • Entity: IdRepository
  • Property: minimumPasswordLength
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes. 

Using ssoadm

You can change the data store minimum password length using ssoadm; you can do this globally or in a specific realm, where realm level takes precedence over the global level:

  • ssoadm - Global: 
    1. Run the following command to create a data file (called DATA_FILE to match the next command), which is populated with the current sunIdRepoAttributeValidator property values to ensure you don't lose any existing changes:
      $ ./ssoadm get-attr-defs -s sunIdentityRepositoryService -t Organization -u [adminID] -f [passwordfile] | grep sunIdRepoAttributeValidator > DATA_FILE
      
      replacing [adminID] and [passwordfile] with appropriate values.
    2. Update the data file you just created by amending the sunIdRepoAttributeValidator=minimumPasswordLength property value. For example, if you want to increase the minimum password length to 10, you would change it to:
      sunIdRepoAttributeValidator=minimumPasswordLength=10
    3. Run the following command to update the sunIdRepoAttributeValidator property values:
      $ ./ssoadm set-attr-defs -s sunIdentityRepositoryService -t Organization -u [adminID] -f [passwordfile] -D DATA_FILE
      replacing [adminID] and [passwordfile] with appropriate values.
    4. Restart the web application container in which AM/OpenAM runs to apply these configuration changes.
  • ssoadm - Realm:
    1. Run the following command to create a data file (called DATA_FILE to match the next command), which is populated with the current sunIdRepoAttributeValidator property values to ensure you don't lose any existing changes:
      $ ./ssoadm get-realm-svc-attrs -s sunIdentityRepositoryService -e [realmname] -u [adminID] -f [passwordfile] | grep sunIdRepoAttributeValidator > DATA_FILE
      
      replacing [realmname], [adminID] and [passwordfile] with appropriate values.
    2. Update the data file you just created by amending the sunIdRepoAttributeValidator=minimumPasswordLength property value. For example, if you want to increase the minimum password length to 10, you would change it to:
      sunIdRepoAttributeValidator=minimumPasswordLength=10
    3. Run the following command to update the sunIdRepoAttributeValidator property values:
      $ ./ssoadm set-realm-svc-attrs -s sunIdentityRepositoryService -e [realmname] -u [adminID] -f [passwordfile] -D DATA_FILE
      replacing [realmname], [adminID] and [passwordfile] with appropriate values.
Note

When changing the data store minimum password length in OpenAM 13.5.x, AM 5 or AM 5.1, you may encounter an "Exception in thread "SystemTimer" java.lang.Error: java.lang.ExceptionInInitializerError" response. This error can be safely ignored since the operation performed by ssoadm still completes successfully. See java.lang.ExceptionInInitializerError when using ssoadm commands in AM 5, 5.1 and OpenAM 13, 13.5, 13.5.1 for further information.

See Also

Forgotten password reset or password change fails with Minimum password length is 8 error in AM/OpenAM (All versions)

How do I change what characters are permitted in user names in AM/OpenAM (All versions) for authentication purposes?

Setup and Maintenance Guide › Setting Up Realms › Changing Passwords using the REST API

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8999 (Incorrect messages are displayed when a user tries to change their password and it does not meet the minimum length)

OPENAM-6867 (changePassword REST endpoint is not returning LDAP issues that are related to a user mistake.)

OPENAM-6166 (Allow Forgotten Password functionality in OpenAM to use other user attributes besides uid and mail)


How do I assign password policies to a user when creating the user via the REST API in AM/OpenAM (All versions)?

The purpose of this article is to provide information on assigning password policies to a user when creating the user via the REST API in AM/OpenAM. These password policies are also enforced at the point you create the user to ensure the user's password complies with the password policy. This article assumes you are using DS/OpenDJ for your user store.

Caution

AM/OpenAM is not designed to be a fully featured user administration tool; the user functionality is intended to be used for validating connectivity to your identity repository. You should use a dedicated tool for managing users such as IDM/OpenIDM or DS/OpenDJ, depending on your use case.

Overview

There are two approaches to this depending on your use case:

  • Single password policy that applies to all users. This is a very simple process as follows:
    1. Create your password policy in DS/OpenDJ (either as a global policy or assigned to a specific branch, such as : dc=example,dc=com or ou=employees,dc=example,dc=com). See Administration Guide › Assigning Password Policies for further information.
    2. Create your users in AM/OpenAM via the REST API using the users/?_action=create endpoint as normal. The password policy is automatically assigned to the user because of the subtree the user is created on.
  • Multiple password policies with users having different policies. This process requires additional configuration but gives you more flexibility as you choose which password policy to assign to the user when you create them. See the Assigning password policies to a user section for further information.

If you want end users to receive a meaningful message when they change their password and it does not comply with the password policy, you must use the LDAP authentication module and enable LDAP Behera Password Policy Support within this module. See Authentication and Single Sign-On Guide › LDAP Authentication Module for further information on this authentication module. The default DataStore module does not report these messages to the end user. 

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM/OpenAM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains a valid resource version (AM 5 and later).

See How do I avoid common issues with REST calls in AM/OpenAM (All versions)? for further information.

Assigning password policies to a user

The following example process walks you through creating two different password policies and assigning one of them to a user using the REST API. This process includes steps to verify the password policies are working as expected:

  1. Create your password policies in DS/OpenDJ as described in Administration Guide › Configuring Password Policies. In this example, the following two password policies have been created: 
    dn: cn=Dictionary,cn=Password Policies,cn=config
    objectClass: ds-cfg-password-policy
    objectClass: top
    objectClass: ds-cfg-authentication-policy
    ds-cfg-default-password-storage-scheme: cn=SHA-1,cn=Password Storage Schemes,cn=config
    cn: Dictionary
    ds-cfg-java-class: org.opends.server.core.PasswordPolicyFactory
    ds-cfg-password-validator: cn=Dictionary,cn=Password Validators,cn=config
    ds-cfg-password-attribute: userPassword
    
    dn: cn=Repeated,cn=Password Policies,cn=config
    objectClass: ds-cfg-password-policy
    objectClass: top
    objectClass: ds-cfg-authentication-policy
    ds-cfg-default-password-storage-scheme: cn=SHA-1,cn=Password Storage Schemes,cn=config
    cn: Repeated
    ds-cfg-java-class: org.opends.server.core.PasswordPolicyFactory
    ds-cfg-password-validator: cn=Repeated Characters,cn=Password Validators,cn=config
    ds-cfg-password-attribute: userPassword
    
  2. Test the password policy is working on the DS/OpenDJ side by creating a user who does not meet the password policy conditions:
    1. Create an LDIF file (newuser.ldif) with a password that is in the dictionary and assign that Dictionary password policy to the user, for example:
      dn: uid=newuser,ou=People,dc=example,dc=com
      uid: newuser
      objectClass: person
      objectClass: organizationalPerson
      objectClass: inetOrgPerson
      objectClass: top
      cn: New User
      sn: User
      ou: People
      mail: newuser@example.com
      userPassword: password
      ds-pwp-password-policy-dn: cn=Dictionary,cn=Password Policies,cn=config
      
    2. Add the user with the Dictionary password policy using the ldapmodify command and observe that it fails:
      $ ./ldapmodify --port 1349 --hostname localhost --bindDN "cn=Directory Manager" --bindPassword password --defaultAdd newuser.ldif
      Processing ADD request for uid=newuser,ou=People,dc=example,dc=com
      
      ADD operation failed
      
      Result Code:  19 (Constraint Violation)
      
      Additional Information:  The password value for attribute userPassword was found to be unacceptable: The provided password contained a word from the server's dictionary
      
      In pre-DS 5, you need to include --filename in this command before newuser.ldif.
  3. Add the ds-pwp-password-policy-dn attribute to the data store configuration using the console (see How do I update LDAP user attributes using the REST API in AM/OpenAM (All versions)? for instructions on doing this via ssoadm): 
    • AM 6 and later console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] > User Configuration and add the ds-pwp-password-policy-dn attribute to the LDAP User Attributes list.
    • AM 5.x / OpenAM 13.x console: navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] and add the ds-pwp-password-policy-dn attribute to the LDAP User Attributes list.
    • Pre-OpenAM 13 console: navigate to: Access Control > [Realm Name] > Data Stores > [Data Store Name] and add the ds-pwp-password-policy-dn attribute to the LDAP User Attributes list.
  4. Restart the web application container in which AM/OpenAM runs to apply these configuration changes.
  5. Authenticate as an admin user. For example:
    • AM 5 and later:
      $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate
      
    • Pre-AM 5:
      $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate
    Example response:
    { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" } 
    
  6. Create a user with a password that complies with the password policy using one of the following curl commands where ds-pwp-password-policy-dn is set to the required password policy (this should be in the same realm as the one you updated in step 3). For example:
    • AM 5 and later:
      $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0" -H "If-None-Match: *" -d '{ "username": "newuser1", "userpassword": "secret1234", "ds-pwp-password-policy-dn": "cn=Dictionary,cn=Password Policies,cn=config" }' http://host1.example.com:8080/openam/json/realms/root/users/newuser1
      
    • Pre-AM 5:
      $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "If-None-Match: *" -d '{ "username": "newuser1", "userpassword": "secret1234", "ds-pwp-password-policy-dn": "cn=Dictionary,cn=Password Policies,cn=config" }' http://host1.example.com:8080/openam/json/users/newuser1
    Example response:
    {
      "username": "newuser1",
      "realm": "/",
      "uid": [
        "newuser1"
      ],
      "universalid": [
        "id=newuser1,ou=user,dc=example,dc=com"
      ],
      "objectClass": [
        "iplanet-am-managed-person",
        "inetuser",
        "sunFederationManagerDataStore",
        "sunFMSAML2NameIdentifier",
        "devicePrintProfilesContainer",
        "inetorgperson",
        "sunIdentityServerLibertyPPService",
        "iPlanetPreferences",
        "pushDeviceProfilesContainer",
        "iplanet-am-user-service",
        "forgerock-am-dashboard-service",
        "organizationalperson",
        "top",
        "kbaInfoContainer",
        "sunAMAuthAccountLockout",
        "person",
        "oathDeviceProfilesContainer",
        "iplanet-am-auth-configuration-service"
      ],
      "dn": [
        "uid=newuser1,ou=user,dc=example,dc=come"
      ],
      "inetUserStatus": [
        "Active"
      ],
      "sn": [
        "newuser1"
      ],
      "cn": [
        "newuser1"
      ],
      "modifyTimestamp": [
        "20161004155427Z"
      ],
      "createTimestamp": [
        "20160721105610Z"
      ]
    }
    
  7. Test that user creation fails with a password that violates the password policy by creating a user with a password such as aaaaaaaaa (which is against the second password policy of Repeat Characters in this example) and observe that it fails. For example:
    • AM 5 and later:
      $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0" -H "If-None-Match: *" -d '{ "username": "newuser2", "userpassword": "aaaaaaaaa", "ds-pwp-password-policy-dn": "cn=Repeated,cn=Password Policies,cn=config" }' http://host1.example.com:8080/openam/json/realms/root/users/newuser2
      
    • Pre-AM 5:
      $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "If-None-Match: *" -d '{ "username": "newuser2", "userpassword": "aaaaaaaaa", "ds-pwp-password-policy-dn": "cn=Repeated,cn=Password Policies,cn=config" }' http://host1.example.com:8080/openam/json/users/newuser2
    Example response:
    {"code":400,"reason":"Bad Request","message":"Bad Request"}
    
Note

In AM 5, 5.1, OpenAM 13, 13.5, you will get a Bad Request response if the user cannot be created because the password is against the password policy. A more meaningful message will be shown in the IdRepo logs if you use the LDAP authentication module since this handles the Behera messages. This is a known issue: OPENAM-9009 (When using REST endpoint "json/users/?_action=create" with password policy violation, AM returns HTTP 400 "bad request", reason "Bad Request" , Message "Bad Request" rather than a more meaningful error message), which is fixed in AM 5.5 and OpenAM 13.5.1.

See Also

FAQ: Users in AM/OpenAM

How do I change a user's password using the REST API in AM/OpenAM (All versions)?

How do I update LDAP user attributes using the REST API in AM/OpenAM (All versions)?

How do I enable account lockout in AM/OpenAM (All versions)?

Administrator and user accounts in AM/OpenAM

Data stores in AM/OpenAM

Administration Guide › Configuring Password Policy

Setup and Maintenance Guide › Creating Identities

Authentication and Single Sign-On Guide › Specifying Realms in REST API Calls

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9009 (When using REST endpoint "json/users/?_action=create" with password policy violation, AM returns HTTP 400 "bad request", reason "Bad Request" , Message "Bad Request" rather than a more meaningful error message)


How do I change a user's password using the REST API in AM/OpenAM (All versions)?

The purpose of this article is to provide information on changing a user's password in AM/OpenAM using the REST API.

Overview

To change a user's password, you must authenticate and include the returned token ID in the curl command. For example, you can authenticate as an admin user as follows:

  • AM 5 and later:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1"  http://host1.example.com:8080/openam/json/realms/root/authenticate
    
  • Pre-AM 5:
    $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" http://host1.example.com:8080/openam/json/authenticate

Example response:

{ "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" }
Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM/OpenAM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains a valid resource version (AM 5 and later).

See How do I avoid common issues with REST calls in AM/OpenAM (All versions)? for further information.

Changing a user's password

You (or the user) can change a user's password using one of the following curl commands. The user's old password is required unless you are an admin user changing a non-admin user's password.

AM 5 and later

You can use the following curl command where you supply the user's old password: 

$ curl -X POST -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0" -d '{ "currentpassword":"changeit", "userpassword":"newPassword" }' http://host1.example.com:8080/openam/json/realms/root/users/demo?_action=changePassword

An admin user can change the password for a non-admin user without supplying the old password by using a PUT request instead:

$ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0" -d '{ "userpassword":"newPassword" }' http://host1.example.com:8080/openam/json/realms/root/users/demo

Pre-AM 5

You can use the following curl command where you supply the user's old password: 

$ curl -X POST -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -d '{ "currentpassword":"changeit", "userpassword":"newPassword" }' http://host1.example.com:8080/openam/json/users/demo?_action=changePassword

Since OpenAM 12.0.3, admin users can change the password for a non-admin user without supplying the old password by using a PUT request instead:

$ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -d '{ "userpassword":"newPassword" }' http://host1.example.com:8080/openam/json/users/demo

See Also

FAQ: Users in AM/OpenAM

FAQ: REST API in AM/OpenAM

Setup and Maintenance Guide › Changing Passwords

Authentication and Single Sign-On Guide › Specifying Realms in REST API Calls

Related Training

N/A

Related Issue Tracker IDs

OPENAM-3877 (Changing password through new REST endpoint fails if default AuthN chain needs more than just the password to authenticate)

OPENAM-5695 (Allow admin users to update user's password without the old password)


Frequently Asked Questions


FAQ: Users in AM/OpenAM

The purpose of this FAQ is to provide answers to commonly asked questions regarding users in AM/OpenAM.

Frequently asked questions

Q. Can I use AM/OpenAM to manage users?

A. AM/OpenAM is not designed to be a fully featured user administration tool; the user functionality is intended to be used for validating connectivity to your identity repository. You should use a dedicated tool for managing users such as IDM/OpenIDM or DS/OpenDJ, depending on your use case.

Q. Why can’t I see a user on the Identities page (previously the Subjects tab)?

A. One possible reason is that you may have more than 100 users. Only the first 100 users are shown on the Identities page by default; therefore, you should search for a user if you have more than 100 users.

In AM / OpenAM 13.5, you can increase the number of users shown by editing the schema directly using an LDAP browser such as the DS/OpenDJ control panel (removed in DS 6) or Apache™ Directory Studio as follows:

  1. Navigate to the following DN:
    ou=1.0,ou=iPlanetAMAdminConsoleService,ou=services,dc=example,dc=com
  2. Search for "iplanet-am-admin-console-search-limit" in the editor box for the schema XML and change the default value from 100 to your desired value.

In OpenAM 13 and earlier, you can increase the number of users shown by setting the Maximum Results Returned from Search field to your desired value. See OpenAM Reference › Administration for further information. This field has been removed in OpenAM 13.5. 

Caution

Increasing the number of users shown on the Identities page may slow the loading time of users.

Q. How can I check how many users are being protected by AM/OpenAM?

A. You can query your LDAP user store to find the number of users. The following examples demonstrate two approaches, where the countentries option is used to return the total number of entries that match the search filter and displays the total number on the last line.

Using a user based objectclass

You can use a query such as the following if you are using the default schema objectClass of inetOrgPerson in DS/OpenDJ:

$ ./ldapsearch --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --baseDN dc=example,dc=com --countentries objectClass=inetOrgPerson

This approach will not work if you use the same objectClass for real people as well as non real person objects.

Using uids

You can use a query such as the following to return all users and all attributes:

$ ./ldapsearch --hostname ds1.example.com --port 1389 --bindDN “cn=Directory Manager” --bindPassword password --baseDN dc=example,dc=com --searchScope sub --countEntries “(uid=*)” \*

This approach will not work if you use a non-uid based RDN.

Q. Can I specify the exact DN/container that the user is to be stored on when creating a new user?

A. No, AM/OpenAM does not allow end-users to specify the exact DN/container for newly created users; AM/OpenAM will just utilize the configured LDAP people container name/value setting. The DN value provided for the /json/users REST endpoint is essentially ignored by the underlying code and the entry will be created based on the data store settings (which again is only able to work with a single container).

Q. What is the default search attribute used when searching for users on the Identities page?

A. The default search attribute is cn. This can be changed as described in How do I change the search attribute used to search for users in AM/OpenAM console (All versions)?

Q. What is the Universal ID shown against a user or group on the Identities page?

A. The Identities page displays identities from the configured data stores. As AM/OpenAM abstracts the underlying data store technology (for example, directory server, database, NoSQL database, external web service etc) away from the "identity" concept, no assumptions are made about the underlying data.

When AM/OpenAM displays the user or group "identity", it displays generic information such as the user's name or the group members. It also displays the Universal ID, which is not to be confused with the actual DN of the entry in your configured LDAP based data store. The Universal ID is used by AM/OpenAM to differentiate identities, and is in the following format:

id=[identity name],ou=[identity type],[realm DN]

Where:

  • [identity name] is the name of the identity.
  • [identity type] is the type, which can be user, group, role or filteredrole.
  • [realm DN] is the identifier of the realm the given identity belongs to (which contains the configuration store's root suffix).

Q. Why can the admin user (called amadmin by default) log in to AM/OpenAM when no other users can?

A. The admin user is stored in the configuration repository in AM/OpenAM, whereas other users are stored in your identity repository. If there are connection issues to your identity repository, these will prevent other users logging in but the admin user will still be able to log in.

See Login to AM/OpenAM console (All versions) fails for amadmin user for further information if the amadmin user cannot log in.

Q. Why can't I log into a sub-realm with amadmin?

A. amadmin is only available in the top level realm; sub-realms use the same identity repository as the top level realm by default, but because this user isn't in the identity repository they are not available in sub-realms. You can use the demo user in sub-realms as this user is stored in the identity repository. 

Q. How can I be certain that a user is logging in to the top level realm?

A. You can specify the top level realm in your URL by setting realm = /, for example:

  • AM 5 and later:
    http://host1.example.com:8080/openam/XUI/?realm=/#login
  • Pre-AM 5:
    http://host1.example.com:8080/openam/XUI/#login/&realm=/

See AM Authentication and Single Sign-On Guide › Using Authentication › Authenticating From a Browser or OpenAM 13 Administration Guide › Defining Authentication Services › Authenticating To OpenAM for optional ways of specifying the Realm in XUI Login URLs.

Q. Can I prevent the default anonymous user logging in to the top level realm?

A. The default anonymous user is used in conjunction with the Anonymous Authentication module. It is safe to deactivate this user if you do not use this module and this will prevent them logging in to the top level realm.

See How do I deactivate the default anonymous user in AM/OpenAM (All versions)? for further information.

Q. What happens to users' sessions when I deactivate a realm?

A. Users who are currently logged in and have a valid session will be unaffected; their session will remain active. However, other users will not be able to authenticate to that realm once it is deactivated. This is also true if you are using SAML federation and AM/OpenAM is the IdP. If AM/OpenAM is acting as the SP, SAML based SSO will fail as AM/OpenAM will be unable to process assertions issued by the IdP.

You cannot end all user sessions by deactivating a realm.

Q. Can I warn a user that their session is about to expire?

A. No, there is no way of warning a user that their session will expire. The session will automatically expire once it has timed out.

Q. Is it possible to create read-only users in AM/OpenAM?

A. You cannot configure this on a per user basis but you can make a whole data store read-only in AM/OpenAM. See How do I make a whole user data store read-only to users in AM/OpenAM (All versions)? for further information.

There is an RFE, which may address this in the future: OPENAM-5714 (Add support for more granular delegation privileges).

Q. Can I create an admin user who has similar access rights to the amAdmin user?

A. Yes you can. You can create admin users with different access rights (privileges) according to your needs. See How do I create an admin user in AM/OpenAM (All versions) with amadmin privileges? for details on how you assign these privileges to a user and Setup and Maintenance Guide › Reference › Realm Privileges Configuration Reference for details on the different privileges that are available.

There is an RFE for additional privileges: OPENAM-5714 (Add support for more granular delegation privileges).

See Also

Login to AM/OpenAM console (All versions) fails for amadmin user

How do I unlock a user's account using the REST API in AM/OpenAM (All versions)?

How do I configure user level session timeouts in AM/OpenAM (All versions)?

How do I obtain the user's session ID in AM/OpenAM (All versions) when browser cookies are disabled?

How do I understand what the user data store is used for in AM/OpenAM (All versions)?

How do I create a user data store in AM/OpenAM (All versions) using ssoadm?

Administrator and user accounts in AM/OpenAM

Related Training

ForgeRock Access Management Core Concepts (AM-400)


Known Issues


Login to AM/OpenAM console (All versions) fails for amadmin user

The purpose of this article is to provide assistance if login to the AM/OpenAM console fails for the amadmin user. The amadmin user is stored in the configuration data store rather than the user data store.

Symptoms

The amadmin user cannot log into the console. You may see one of the following errors when you try to log in depending on the root cause:

Browser

One of the following error(s) is shown in the browser, even though your credentials are correct:

User name/password combination is invalid.
Login/password combination is invalid.
Authentication service is not initialized. Contact your system administrator.
Unable to login to OpenAM
Service Unavailable

The service is currently unavailable. It may be temporarily overloaded or under going maintenance. Please try again later.

Authentication debug log

The following error is shown in your Authentication debug log; no error is shown in the browser:

amAuth:12/15/2016 09:27:03:209 AM UTC: Thread[http-nio-8080-exec-8,5,main] 
LoginState: getting identity Got IdRepException in IdUtils.getIdentity 
Message:Illegal universal identifier amAdmin.

IdRepo debug log

The following error is shown in your IdRepo debug log; the "Authentication service is not initialized" error may also be seen in the browser:

amSDK:12/15/2016 09:35:51:166 AM UTC: Thread[localhost-startStop-1,5,main]: TransactionId[b3fea1eb-aaad-4d20-9b66-941b90e78ad8-2]
ERROR: JCEEncryption:: failed to decrypt data
javax.crypto.BadPaddingException: Given final block not properly padded

Session debug log

The following error is shown in your Session debug log and an authentication failed error may also be seen in the browser:

CTS: Operation failed:
Result Code: Object Class Violation
Diagnostic Message: Entry coreTokenId=-3581527715699050299,ou=famrecords,ou=openam-session,ou=tokens,dc=example,dc=com violates the Directory Server schema configuration because it includes attribute coreTokenMultiString01 which is not allowed by any of the objectclasses defined in that entry
Matched DN: 
   at org.forgerock.openam.cts.impl.LdapAdapter.create(LdapAdapter.java:110)
   at org.forgerock.openam.sm.datalayer.impl.tasks.CreateTask.performTask(CreateTask.java:48)
   at org.forgerock.openam.sm.datalayer.api.AbstractTask.execute(AbstractTask.java:41)
   at org.forgerock.openam.sm.datalayer.impl.SeriesTaskExecutor$AuditRequestContextPropagatingTask.execute(SeriesTaskExecutor.java:209)
   at org.forgerock.openam.sm.datalayer.impl.SimpleTaskExecutor.execute(SimpleTaskExecutor.java:59)
   at org.forgerock.openam.sm.datalayer.impl.SeriesTaskExecutorThread.run(SeriesTaskExecutorThread.java:85)

Recent Changes

Upgraded to, or installed AM 5 or later.

Created a new authentication chain and set it as the default for the top level realm.

Enabled secure cookies.

Changed the federation signing key.

Changed the default cookie domain in AM / OpenAM 13.5 or upgraded to AM / OpenAM 13.5

Enabled host-based cookies in OpenAM 12.0.0, 12.0.1, 12.0.2 or 13.0.

Upgraded to OpenAM 12.0.4 or 13.0. 

Causes

The cause varies depending on what recent changes you have made:

AM 5 and later

When installing or upgrading to AM 5 or later from a previous version, missing schemas for the external CTS will prevent you from logging in (and you will see the CTS: Operation failed error in the Session debug log).

Additionally, the Core Token Service (CTS) token store is no longer optional as of AM 5 as it is now the authoritative source for sessions. See Release Notes › What's New › Cloud for further information on this change. As a consequence of this change, the amadmin user will not be able to log into the console if the CTS store is down or misconfigured. This is a known issue: OPENAM-10382 (If we set up External CTS wrongly then OpenAM fails catastrophically on start up.); the misconfiguration aspect will be addressed in a future release per OPENAM-10383 (Validation of External CTS store using OpenAM GUI)

Authentication chain

If you have created a new authentication chain, set it as the default for the top level realm and use a login URL such as:

http://host1.example.com:8080/openam/XUI/#login

The amadmin user cannot log in as this URL format (openam/XUI/#login) directs them to the authentication chain specified in the Organization Authentication Configuration setting. The amadmin user needs to log in via the DataStore module. See Authentication and Single Sign-On Guide › Configuring the Default Authentication Tree or Chain for further information.

Secure cookies

If you have enabled AM/OpenAM to set cookies in secure mode, the browser will only return the session cookie if a secure protocol such as HTTPS is used; the cookie will not be returned over non-SSL connections. Although you have successfully authenticated, the cookie containing the session token is not passed to AM/OpenAM, which prevents login from succeeding. 

Federation signing key

The default 'test' certificate alias used for SAML2 and OAuth signing keys is also used by the XUI and for REST authentication. If you change the signing key for federation but do not change the certificate alias used for authentication, you will not be able to log into the console with XUI enabled or make REST calls.

Cookie domain

As of OpenAM 13.5, the cookie domain defaults to the full FQDN. Login will not succeed unless the cookie domain is set correctly.

See FAQ: Cookies in AM/OpenAM (Q. What does the cookie domain default to?) for further information about this change.

Host-based cookies

There is a known issue in OpenAM 12.0.0, 12.0.1, 12.0.2 and 13.0 where the cookie domains property is incorrectly set when host-based cookies are used in the XUI. The empty cookie domains server property prevents the session cookie being set, which prevents the login succeeding: OPENAM-5264 (Can't login to OpenAM with no cookies set in the platform service).

Encryption key

There is a known issue in OpenAM 12.0.4 and 13.0 that causes the "ERROR: JCEEncryption:: failed to decrypt data" message in the IdRepo debug log. See JCEEncryption:: failed to decrypt data error when accessing the admin console in OpenAM 12.x or 13.x for further information on this cause.

Additionally, this error can happen in other versions of AM/OpenAM when the encryption key is corrupt, which means the directory manager's password (which is stored in the bootstrap file) cannot be decrypted. The encryption key is specified in the AM_ENC_KEY property when you configure AM/OpenAM.

Solution

The solution depends on the cause:

AM 5 and later

Authentication chain

You should force the amadmin user to log in to the console (/openam/console) using one of the following URLs:

  • Use the /openam/console URL, for example:
    http://host1.example.com:8080/openam/console
  • Append the login URL with the DataStore module, for example:
    http://host1.example.com:8080/openam/XUI/#login/&module=DataStore
  • Append the login URL with the adminconsoleservice service, for example:
    http://host1.example.com:8080/openam/XUI/#login/&service=adminconsoleservice 
    The adminconsoleservice service uses the authentication chain defined for the administrator (Administrator Authentication Configuration).

If you changed the default authentication chain in the top level realm by mistake, you can use one of the above URLs to log in and revert the authentication chain.

Secure cookies

You can either use a secured HTTPS connection to access AM/OpenAM or disable Secure cookies as detailed in: Login to AM/OpenAM (All versions) fails with valid username/password after enabling Secure cookies.

Federation signing key

You can resolve this issue by updating the authentication certificate alias to match the alias of the new signing key as described in Unable to login to OpenAM console 12.x and 13.x or access REST API after changing the Federation Signing Key.

See How do I change the Signing Key for Federation in OpenAM 12.x and 13.x? for further information. 

Cookie domain

You should ensure the cookie domain is set to the full FQDN of the server in AM / OpenAM 13.5. If you have a site configuration, you should use the FQDN of the first server in your deployment.

See Reference › Configuration Reference › Platform for further information on setting the cookie domain.

Host-based cookies

You can upgrade to a later version of AM/OpenAM which fixes this issue or set the cookie domains to "" using ssoadm as detailed in: OpenAM 12.0.0, 12.0.1, 12.0.2 and 13.0 login fails with User name/password combination is invalid error if you use host-based cookies.

Encryption key

You can resolve this issue in one of two way depending on the cause as detailed in: JCEEncryption:: failed to decrypt data error when accessing the admin console in OpenAM 12.x or 13.x.

See Also

How do I change the amadmin password in AM/OpenAM (All versions)?

How do I change the amadmin and dsameuser passwords at the same time in AM/OpenAM (All versions)?

FAQ: Users in AM/OpenAM

Administrator and user accounts in AM/OpenAM

Authentication and Single Sign-On Guide › Reference › Core

Authentication and Single Sign-On Guide › Implementing Authentication › Configuring Authentication Chains

AM 5 Release Notes

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11398 (OpenAM ACI installation instruction does not work for OpenDJ productionMode)

OPENAM-11116 (Admin console should still be accessible even if CTS is not available.)

OPENAM-10966 (Missing step for upgrade from AM 13 to 14 - CTS)

 OPENAM-10451 (Could not get OpenDJ 2.6.4 to work with OpenAM 14.0.0M10 for External CTS setup)

OPENAM-10383 (Validation of External CTS store using OpenAM GUI)

OPENAM-10382 (If we set up External CTS wrongly then OpenAM fails catastrophically on start up.)

OPENAM-8214 (JCEEncryption errors are recorded during/after upgrading to 13)

OPENAM-5264 (Can't login to OpenAM with no cookies set in the platform service)


Account lockout fails when an authentication chain contains a custom module in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if user accounts are not locked in accordance with the account lockout settings in AM/OpenAM when you have an authentication chain that contains one or more custom modules.

Symptoms

User account is not locked after a repeated number of failed login attempts.

The following message is shown when the user subsequently attempts to log in with invalid credentials. 

{ "code": 401, "reason": "Unauthorized", "message": "Authentication Failed" }

Expected messages

When account lockout is working in an authentication chain, you would expect to see the following message after x number of failed logins: 

{ "code": 401, "reason": "Unauthorized", "message": "Authentication Failed Warning: You will be locked out after 1 more failure(s)." }

And then the following message after another attempt:

{ "code": 401, "reason": "Unauthorized", "message": "Your account has been locked." }

Recent Changes

Added a custom authentication module to the chain.

Causes

The account lockout functionality works based on invalid password exceptions rather than invalid login exceptions. This means all login modules must throw an InvalidPasswordException instead of an AuthLoginException to trigger account lockout.

Solution

This issue can be resolved by updating your custom authentication modules to throw an InvalidPasswordException. For example, by changing:

throw new AuthLoginException(<parameters>);

To:

throw new InvalidPasswordException(<parameters>);

See Also

How do I enable account lockout in AM/OpenAM (All versions)?

How do I unlock a user's account using the REST API in AM/OpenAM (All versions)?

How do I lock a user's account if they do not authenticate to AM/OpenAM (All versions) within a specific period of time?

Authentication and Single Sign-On Guide › The Sample Authentication Logic

Authentication and Single Sign-On Guide › Implementing Account Lockout

Authentication and Single Sign-On Guide › Account Lockout

Related Training

N/A

Related Issue Tracker IDs

OPENAM-14192 (Addition needed for sample custom auth code to mention account lockout)

OPENAM-6362 (HOTP and OATH auth-modules do not set 'failureUserID' when throwing InvalidPasswordException, this breaks OpenAM account lockout)


Dynamic user profile creation fails with The password value for attribute userPassword was found to be unacceptable error in AM (All versions) and OpenAM 13.x

The purpose of this article is to provide assistance if dynamic user profile creation fails with "an ldap exception 19: The password value for attribute userPassword was found to be unacceptable" or "The password did not meet the password policy requirements" error. This issue also occurs if AM/OpenAM is acting as the Service Provider (SP) and auto-federation is configured to use dynamic account creation; you will see "SPACSUtils.processResponse : error code=-1 com.sun.identity.plugin.session.SessionException: Login failed with unknown reason" error as well in this scenario.

Symptoms

User profiles are not created as expected after successful authentication.

An error similar to one of the following is shown in the Authentication debug logs when dynamic user profile creation fails:

  • The password value for attribute userPassword was found to be unacceptable:
    ERROR: Cannot create user profile for: new_user
    amAuth:05/06/2018 11:31:22:288 PM BST: Thread[default task-1,5,main]: TransactionId[780c49b3-8b87-4eb4-9407-cc8fa553843b-2411231]
    Stack trace: 
    Message:Plug-in org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo encountered an ldap exception 19: The password value for attribute userPassword was found to be unacceptable: The provided password did not contain <details of password policy>
       at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.handleErrorResult(DJLDAPv3Repo.java:2508)
       at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.create(DJLDAPv3Repo.java:688)
       at com.sun.identity.idm.server.IdServicesImpl.create(IdServicesImpl.java:427)
       at com.sun.identity.idm.AMIdentityRepository.createIdentity(AMIdentityRepository.java:463)
       at com.sun.identity.authentication.service.LoginState.createUserIdentity(LoginState.java:5448)
       at com.sun.identity.authentication.service.LoginState.createUserProfile(LoginState.java:1925)
       at com.sun.identity.authentication.service.LoginState.getCreateUserProfile(LoginState.java:2553)
       at com.sun.identity.authentication.service.LoginState.searchUserProfile(LoginState.java:2394)
       at com.sun.identity.authentication.service.AMLoginContext.runLogin(AMLoginContext.java:553)
       at com.sun.identity.authentication.server.AuthContextLocal.submitRequirements(AuthContextLocal.java:586)
       at com.sun.identity.authentication.AuthContext.submitRequirements(AuthContext.java:1235)
       at com.sun.identity.authentication.AuthContext.submitRequirements(AuthContext.java:1221)
    
  • The password did not meet the password policy requirements:
    amAuth:05/06/2018 11:31:22:288 PM BST: Thread[http-nio-8081-exec-1,5,main]: TransactionId[177135ec-ef6e-455f-a2bf-ed4f46a31ae6-1692]
    Stack trace: 
    Message:The password did not meet the password policy requirements.
       at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.handleErrorResult(DJLDAPv3Repo.java:2485)
       at org.forgerock.openam.idrepo.ldap.DJLDAPv3Repo.create(DJLDAPv3Repo.java:681)
       at com.sun.identity.idm.server.IdServicesImpl.create(IdServicesImpl.java:427)
       at com.sun.identity.idm.AMIdentityRepository.createIdentity(AMIdentityRepository.java:462)
       at com.sun.identity.authentication.AuthContext.submitRequirements(AuthContext.java:1218)
       at com.sun.identity.plugin.session.impl.FMSessionProvider.createSession(FMSessionProvider.java:247)
    

If AM/OpenAM is acting as the SP, federation will fail and the user is returned to the login page after attempting to federate.

The following errors are shown in the Federation debug log when this happens: 

libSAML2:05/06/2018 11:31:22:292 PM EDT: Thread[default task-28,5,main]: TransactionId[f9aee006-bdf8-45df-bae5-b3ff46f54607-6629766]
SPACSUtils.processResponse : error code=-1
com.sun.identity.plugin.session.SessionException: Login failed with unknown reason.
   at com.sun.identity.plugin.session.impl.FMSessionProvider.createSession(FMSessionProvider.java:275)
   at com.sun.identity.saml2.profile.SPACSUtils.processResponse(SPACSUtils.java:1220)
   at org.apache.jsp.saml2.jsp.spAssertionConsumer_jsp._jspService(spAssertionConsumer_jsp.java:317)
   at org.apache.jasper.runtime.HttpJspBase.service(HttpJspBase.java:70)
   at javax.servlet.http.HttpServlet.service(HttpServlet.java:790)
libSAML2:05/06/2018 11:31:22:293 PM EDT: Thread[default task-1,5,main]: TransactionId[780c49b3-8b87-4eb4-9407-cc8fa553843b-2411231]
ERROR: spAssertionConsumer.jsp: SSO failed. 
com.sun.identity.saml2.common.SAML2Exception: Login failed with unknown reason.
   at com.sun.identity.saml2.profile.SPACSUtils.processResponse(SPACSUtils.java:1241)
   at org.apache.jsp.saml2.jsp.spAssertionConsumer_jsp._jspService(spAssertionConsumer_jsp.java:317)
   at org.apache.jasper.runtime.HttpJspBase.service(HttpJspBase.java:70)
   at javax.servlet.http.HttpServlet.service(HttpServlet.java:790)

Recent Changes

Configured dynamic user profile creation.

Configured password policies in DS/OpenDJ.

Causes

AM/OpenAM generates passwords for dynamically created user profiles; these are not configurable and do not adhere to any password policies configured in DS/OpenDJ. You will see this issue when the password policy in DS/OpenDJ requires a different format to the one used by AM/OpenAM when it generates passwords.

Solution

You can workaround this issue by disabling the DS/OpenDJ password policy validation for administrators, which allows AM/OpenAM to create passwords during dynamic user profile creation.

You can disable password policy validation using dsconfig, for example:

$ ./dsconfig set-password-policy-prop --policy-name "Default Password Policy" --set skip-validation-for-administrators:true --no-prompt

See Also

How does AM/OpenAM (All versions) use account mapping to identify the end user from a SAML Assertion?

How do I configure the SAML2 Authentication module for Auto Federation in AM (All versions) and OpenAM 13.x?

Authentication and Single Sign-On Guide › User Profile

SAML v2.0 Guide › Configuring How Remote Accounts Map To Local Accounts

Reference › dsconfig

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11521 (OpenAM should not generate a password when using auto federation and dynamic profile creation)


Login to AM/OpenAM (All versions) fails with valid username/password after enabling Secure cookies

The purpose of this article is to provide assistance if login to AM/OpenAM fails for all users (including amadmin) even though they are using valid credentials. This issue can affect both the XUI and Classic UI when you are using a non-SSL connection and you have enabled Secure cookies.

Symptoms

When logging into AM/OpenAM using an HTTP connection, login fails:

  • If you are using the Classic UI, login fails without an error and you are redirected back to the AM/OpenAM login page.
  • If you are using the XUI, login fails but you remain on the login page and a "Login/password combination is invalid." message is displayed.

This issue can affect both administrators (preventing access to the console) and users (preventing access to pages such as the User profile). Often it will seem to only affect administrators, with users still able to log in. This happens because users are often connecting to a HTTPS connection, whereas the administrator is attempting to use an internal non-secured network.

An error similar to the following is shown in the restAuthenticationFilter debug log:

restAuthenticationFilter:07/26/2015 12:41:11:165 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Filter init param, context-factory-class, not set. Falling back to the DefaultServerContextFactory.
restAuthenticationFilter:07/26/2015 12:41:11:173 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Filter init param, audit-api-class, not set. Falling back to the NoOp Audit Api.
restAuthenticationFilter:07/26/2015 12:41:11:183 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Created module, className: org.forgerock.openam.jaspi.modules.session.OpenAMSessionModule
restAuthenticationFilter:07/26/2015 12:41:11:585 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Finished initialising the DefaultRuntimeInjector
restAuthenticationFilter:07/26/2015 12:41:11:586 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Filter init param, runtime-injector-class, not set. Falling back to the DefaultRuntimeInjector.
restAuthenticationFilter:07/26/2015 12:41:11:586 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Initialising the JaspiRuntime
restAuthenticationFilter:07/26/2015 12:41:11:603 PM EDT: Thread[http-bio-8080-exec-7,5,main]
OpenAMSessionModule has successfully authenticated the client
restAuthenticationFilter:07/26/2015 12:41:11:603 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Setting principal name, null, and 0 context values on to the request.
restAuthenticationFilter:07/26/2015 12:41:11:604 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Successfully validated request.
restAuthenticationFilter:07/26/2015 12:41:11:918 PM EDT: Thread[http-bio-8080-exec-7,5,main]
Successfully secured response.
restAuthenticationFilter:07/26/2015 12:41:11:992 PM EDT: Thread[http-bio-8080-exec-8,5,main]
OpenAMSessionModule has failed to authenticated the client, passing to Auth Modules
restAuthenticationFilter:07/26/2015 12:41:11:993 PM EDT: Thread[http-bio-8080-exec-8,5,main]
Auditing authentication result
restAuthenticationFilter:07/26/2015 12:41:11:995 PM EDT: Thread[http-bio-8080-exec-8,5,main]
Authentication has failed.
restAuthenticationFilter:07/26/2015 12:41:11:998 PM EDT: Thread[http-bio-8080-exec-8,5,main]
Access Denied
org.forgerock.jaspi.exceptions.JaspiAuthException: Access Denied
	at org.forgerock.jaspi.runtime.context.ContextHandler.handleCompletion(ContextHandler.java:131)
	at org.forgerock.jaspi.runtime.context.JaspiServerAuthContext.validateRequest(JaspiServerAuthContext.java:244)
	at org.forgerock.jaspi.runtime.JaspiRuntime.processMessage(JaspiRuntime.java:160)
	at org.forgerock.jaspi.JaspiRuntimeFilter.doFilter(JaspiRuntimeFilter.java:131)
...

You can use your browser's developer tools to view the HTTP Headers; you will notice that the first POST call to authenticate (/json/authenticate) is successful, whereas the second POST call to retrieve the ID (json/users?_action=idFromSession) fails with a 401 Unauthorized response:

{"code":401,"reason":"Unauthorized","message":"Access Denied"}

Recent Changes

Enabled Secure cookies (com.iplanet.am.cookie.secure=true) but did not implement secured (HTTPS) connections for all communications with AM/OpenAM. This could occur for example, if you were testing SSL or had only partially implemented SSL for AM/OpenAM.

Causes

If you have enabled AM/OpenAM to set cookies in secure mode, the browser will only return the session cookie if a secure protocol such as HTTPS is used; the cookie will not be returned over non-SSL connections. Although you have successfully authenticated, the cookie containing the session token is not passed to AM/OpenAM, which prevents login from succeeding. 

Solution

This issue can be resolved by either using a secured HTTPS connection to access AM/OpenAM or by disabling Secure cookies. The approach you take depends on your plans for SSL.  

  • If you have enabled SSL in AM/OpenAM, you can access AM/OpenAM using a secured HTTPS connection, where the login URL for the console would be similar to this:
    https://host1.example.com:8443/openam/XUI/#login/
  • If you have not enabled SSL, you should disable Secure cookies. Given that the console is unaccessible, you must do this via ssoadm by entering the following command:
    $ ./ssoadm update-server-cfg -u [adminID] -f [passwordfile] -s [server] -a com.iplanet.am.cookie.secure=false
    
    replacing [adminID], [passwordfile] and [server] with appropriate values, where [server] is 'default' or the server name depending on how you configured SSL.
Note

You must restart the web application container in which AM/OpenAM runs to apply these configuration changes. 

See Also

How do I enable SSL in AM/OpenAM (All versions) post-install?

How do I enable SSL in AM/OpenAM (All versions) for an existing installation?

Login to AM/OpenAM console (All versions) fails for amadmin user

Installation Guide › Securing Installations

Related Training

N/A

Related Issue Tracker IDs

OPENAM-9515 (XUI does not enable Secure cookie flags for SSO tracking cookie on 13.5.0)


Subsequent attempts to use ssoadm fail in AM/OpenAM (All versions)

The purpose of this article is to provide assistance if the first use of ssoadm in AM/OpenAM is successful but subsequent attempts fail with a "FATAL ERROR: Cannot obtain Application SSO token".

Symptoms

The first attempt to use ssoadm is successful, whereas subsequent attempts give the following response:

Logging configuration class "com.sun.identity.log.s1is.LogConfigReader" failed
com.sun.identity.security.AMSecurityPropertiesException: AdminTokenAction:  FATAL ERROR: Cannot obtain Application SSO token.
Check AMConfig.properties for the following properties
	com.sun.identity.agents.app.username
	com.iplanet.am.service.password

Restarting the web application container in which AM/OpenAM runs allows you to successfully use ssoadm once more before getting the above response.

Recent Changes

Changed the dsameuser password.

Causes

The dsameuser is used by ssoadm to authenticate with AM/OpenAM. The first authentication attempt to ssoadm uses the dsameuser password from the bootstrap file (local configuration) and subsequent authentication attempts use the dsameuser password from the SpecialRepo userstore (global configuration). 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. 

Solution

This issue can be resolved by ensuring your dsameuser has the same password in your global and local configurations.

See How do I change the dsameuser password in AM/OpenAM (All versions)? for further information on changing your dsameuser password.

See Also

How do I change the dsameuser password in AM/OpenAM (All versions)?

ssoadm fails in AM/OpenAM (All versions) with FATAL ERROR: Cannot obtain Application SSO token

FAQ: Installing and using ssoadm in AM/OpenAM

How do I enable message level debugging for ssoadm in AM/OpenAM (All versions)?

Using ssoadm in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

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


Minimum password length is 8 error in AM (All versions) when updating identities using the REST API

The purpose of this article is to provide assistance if you encounter a "Minimum password length is 8" error when updating identities using the REST API in AM, even though the user's password meets this requirement. This issue also occurs when unlocking a user's account.

Symptoms

The following error is shown when updating identities using the REST API even though the user's password is at least 8 characters:

{"code":404,"reason":"Not Found","message":"Minimum password length is 8."}

For example, if you use a REST call such as:

  • To unlock a user's account:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -H "Accept-API-Version: resource=3.0" -d'{
        "inetUserStatus": "Active"
    }' http://host1.example.com:8080/openam/json/realms/root/users/demo
  • To update a user's email address:
    $ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -H "Accept-API-Version: resource=3.0" -d'{
        "mail": "demo@example.com" 
    }' http://host1.example.com:8080/openam/json/realms/root/realms/employees/users/demo

Recent Changes

Installed, or upgraded to AM 5 or later.

Causes

The Default Protocol Version setting for a new install defaults to LATEST, but this setting does not work as expected per known issue: OPENAM-11052 (Minimum password length is 8 error in AM 5.0 when updating identities using the REST API).

See Development Guide › REST API Versioning for further information on REST versioning.   

Solution

The following are suggested workarounds to resolve this issue; either include the Accept-API-Version header in your REST call or set the Default Protocol Version to Oldest.

Include Accept-API-Version header

You can include the Accept-API-Version header in your REST call, for example:

$ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-type: application/json" -H "Accept-API-Version: resource=3.0" -d'{
    "inetUserStatus": "Active"
}' http://host1.example.com:8080/openam/json/realms/root/users/demo

Set Default Protocol Version

You can set the Default Protocol Version using either the console or ssoadm:

  • Console: navigate to: Configure > Global Services > REST APIs > Default Protocol Version and select OLDEST. 
  • ssoadm: enter the following command:
    $ ./ssoadm set-attr-defs -s RestApisService -t Global -u [adminID] -f [passwordfile] -a openam-rest-apis-default-protocol=Oldest
    replacing [adminID] and [passwordfile] with appropriate values.

See Also

FAQ: REST API in AM/OpenAM

Using the REST API in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11052 (Minimum password length is 8 error in AM 5.0 when updating identities using the REST API)


Your account has been locked error when authentication fails in OpenAM 13.5.1

The purpose of this article is to provide assistance if you encounter a "Your account has been locked" error when authentication fails in OpenAM 13.5.1, even though the user's account is not actually locked.

Symptoms

The user sees one of the following messages in the browser when they cannot authenticate:

Your account has been locked
This user is not active. Contact your system administrator

The following error is shown in the Authentication debug log when this happens:

amAuth:02/12/2018 10:07:29:742 AM GMT: Thread[http-nio-8080-exec-5,5,main]: TransactionId[ab90253e-462e-4225-8a20-97d329775296-384]
Exception : Your account has been locked.|user_inactive.jsp
amAuth:02/12/2018 10:07:29:743 AM GMT: Thread[http-nio-8080-exec-5,5,main]: TransactionId[ab90253e-462e-4225-8a20-97d329775296-384]
Error retrieving SSOToken :
com.iplanet.sso.SSOException: Session state is invalid. AQIC5wM2LY4Sfcxwo1cOJAMRkbIsn0bS8Pm1IB623MLBCnM.*AAJTSQACMDIAAlNLABMxOTM5OTEyMDI1MjY3NzE4OTc0AAJTMQACMDE.* 
   at com.iplanet.sso.providers.dpro.SSOProviderImpl.createSSOToken(SSOProviderImpl.java:220)
   at com.iplanet.sso.providers.dpro.SSOProviderImpl.createSSOToken(SSOProviderImpl.java:184)
   at com.iplanet.sso.providers.dpro.SSOProviderImpl.createSSOToken(SSOProviderImpl.java:236)
   at com.iplanet.sso.SSOTokenManager.createSSOToken(SSOTokenManager.java:369)
   at com.sun.identity.authentication.service.LoginState.getSSOToken(LoginState.java:1862)
   at com.sun.identity.authentication.service.LoginState.logFailed(LoginState.java:4405)
   at com.sun.identity.authentication.service.LoginState.logFailed(LoginState.java:4352)
   at com.sun.identity.authentication.service.AMLoginContext.runLogin(AMLoginContext.java:753)
   at com.sun.identity.authentication.server.AuthContextLocal.submitRequirements(AuthContextLocal.java:617)
   at org.forgerock.openam.core.rest.authn.core.wrappers.AuthContextLocalWrapper.submitRequirements(AuthContextLocalWrapper.java:115)
   at org.forgerock.openam.core.rest.authn.core.LoginProcess.next(LoginProcess.java:173)
   at org.forgerock.openam.core.rest.authn.RestAuthenticationHandler.processAuthentication(RestAuthenticationHandler.java:262)
   at org.forgerock.openam.core.rest.authn.RestAuthenticationHandler.authenticate(RestAuthenticationHandler.java:167)
   at org.forgerock.openam.core.rest.authn.RestAuthenticationHandler.continueAuthentication(RestAuthenticationHandler.java:114)
   at org.forgerock.openam.core.rest.authn.http.AuthenticationServiceV1.authenticate(AuthenticationServiceV1.java:145)
...
Caused by: com.iplanet.dpro.session.SessionException: Session state is invalid. AQIC5wM2LY4Sfcxwo1cOJAMRkbIsn0bS8Pm1IB623MLBCnM.*AAJTSQACMDIAAlNLABMxOTM5OTEyMDI1MjY3NzE4OTc0AAJTMQACMDE.* 
...

The user is actually unlocked despite the error (inetUserStatus = Active in DS/OpenDJ). You can check the physical account lockout status of a user in the DS/OpenDJ user store by querying the inetUserStatus attribute using the ldapsearch command as demonstrated in How do I enable account lockout in AM/OpenAM (All versions)? (Checking physical account lockout status).

Note

amadmin can log in because they are stored in the configuration data store rather than a user store.

Recent Changes

Upgraded to, or installed OpenAM 13.5.1.

Added an additional user store(s) to a realm.

Causes

This is known issue OPENAM-10233 (Authentication failing when multiple datastores in realm).

A recent change to fix OPENAM-9849 (isActive check should fail if the user is inactive in any of the configured data stores) did not take account of multiple user stores; this meant a user was treated as inactive if they were not found in the first user store; they were subsequently not searched for in the other user store(s). Users who exist in all user stores can authenticate.

Solution

This issue can be resolved by upgrading to OpenAM 13.5.2 or later; you can download this from BackStage.

Workaround

You can workaround this issue using one of the following approaches:

  • Ensure users exist in all user stores.
  • Remove any additional user stores to leave only one user store.

See Also

How do I remove the embedded DS/OpenDJ (All versions) after migrating to an external instance?

How do I enable account lockout in AM/OpenAM (All versions)?

How do I understand what the user data store is used for in AM/OpenAM (All versions)?

FAQ: Users in AM/OpenAM

Administrator and user accounts in AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11791 (Authenticating with two or more datastore in OpenAM 13.5.1 , will result in "Your account has been locked" error message)

OPENAM-10233 (Authentication failing when multiple datastores in realm)

OPENAM-7871 (Document the use of multiple identity repository in the same realm)


Copyright and TrademarksCopyright © 2018 - 2019 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...