How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated May 10, 2022

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. 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 for your user store.


1 reader recommends this article

Caution

AM 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 or DS, 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 (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 Assign Password Policies for further information.
    2. Create your users in AM 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 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 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.

See How do I avoid common issues with REST calls in AM (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 as described in Configure 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=Salted SHA-512,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=Salted SHA-512,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 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:
      • DS 7 and later: $ ./ldapmodify --port 1349 --hostname localhost --bindDN uid=admin --bindPassword password --defaultAdd newuser.ldif
      • Pre-DS 7: $ ./ldapmodify --port 1349 --hostname localhost --bindDN "cn=Directory Manager" --bindPassword password --defaultAdd newuser.ldif

Example response:  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

  1. 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 (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.
    • Pre-AM 6 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.
  2. Restart the web application container in which AM runs to apply these configuration changes.
  3. 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?authIndexType=service&authIndexValue=adminconsoleserviceExample response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/openam/console", "realm": "/" }
  4. Create a user with a password that complies with the password policy using the following curl command 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:$ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0,protocol=1.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/newuser1Example 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"   ] }
  5. 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:$ curl -X PUT -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0,protocol=1.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/newuser2Example response: {"code":400,"reason":"Bad Request","message":"Bad Request"}
Note

In AM 5 and 5.1, 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.

See Also

FAQ: Users in AM

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

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

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

Administrator and user accounts in AM

Data stores in AM

Passwords

Creating Identities

Related Training

N/A

Related Issue Tracker IDs

N/A


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