How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated May 10, 2022

The purpose of this article is to provide information on changing the characters that are permitted in user names in AM for authentication purposes when you are using authentication modules and chains. AM checks that the user name does not contain special characters when authenticating. This information does not apply if you are using authentication trees.


3 readers recommend this article

Overview

Special characters are defined in the identity store, and also the LDAP and/or DataStore authentication modules. The default special characters are * ( ) & ! ( defined using the following property value: *|(|)|&|!). You must change the characters in the identity store and also in the respective module(s) if you use either or both of these modules in your authentication chain.

The properties used to define the special characters are as follows:

  • Identity store: the list of special characters is defined in the usernameInvalidChars property.
  • LDAP and/or DataStore authentication modules: the list of special characters is defined in the iplanet-am-auth-ldap-invalid-chars property.
Warning

Special characters (& and * in particular) are also used in different contexts, such as building filters to look up values in LDAP or for privilege evaluation. Removing the default characters from these properties may lead to unexpected behavior (in particular, it is likely to break any modules related to LDAP) and is therefore not recommended. If you choose to remove these default characters, you should test your changes in a pre-production environment first.

See the following sections for details on changing these properties:

Changing invalid characters in the identity store

The list of special characters in the identity store is defined in the usernameInvalidChars property, which has a default value of *|(|)|&|!, where the invalid characters are separated by |.

You can change this list of characters using either Amster or ssoadm; it cannot be changed in the console. You can do this globally or in a specific realm, where realm level takes precedence over the global level:

Amster

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

  • Entity: IdRepository
  • Property: usernameInvalidChars

You can pass either the --global or --realm [Realm] parameters to indicate where the change should take place.

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_FILEreplacing [adminID] and [passwordfile] with appropriate values.
    2. Update the data file you just created by amending the sunIdRepoAttributeValidator=usernameInvalidChars property value. For example, if you want to allow ! in user names, you would change it to: sunIdRepoAttributeValidator=usernameInvalidChars=*|(|)|&
    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_FILEreplacing [adminID] and [passwordfile] with appropriate values.
    4. Restart the web application container in which AM runs to apply these configuration changes.
  • 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_FILEreplacing [realmname], [adminID] and [passwordfile] with appropriate values.
    2. Update the data file you just created by amending the sunIdRepoAttributeValidator=usernameInvalidChars property value. For example, if you want to allow ! in user names, you would change it to: sunIdRepoAttributeValidator=usernameInvalidChars=*|(|)|&
    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_FILEreplacing [realmname], [adminID] and [passwordfile] with appropriate values.
Note

When changing this list of characters using ssoadm in 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.

Changing invalid characters in authentication modules

The list of special characters in the LDAP and DataStore authentication modules is defined in the iplanet-am-auth-ldap-invalid-chars property, which has the same default value. If you change the value in the identity store, and use either or both of these modules in your authentication chain, you should also update this property in the respective module(s) to match.

You can change this list of characters using ldapmodify or ssoadm; it cannot be changed in the console; you can do this globally for all modules of a specific type or for an individual module, where module level takes precedence over the global level:

ldapmodify 

  • All modules of type LDAP:
    1. Create a ldif file to set the iplanet-am-auth-ldap-invalid-chars property for all LDAP type modules. For example: $ cat add.ldif dn: ou=default,ou=OrganizationConfig,ou=1.0,ou=iPlanetAMAuthLDAPService,ou=services,dc=openam,dc=forgerock,dc=org changetype: modify add: sunKeyValue sunKeyValue: iplanet-am-auth-ldap-invalid-chars=[chars]replacing dc=openam,dc=forgerock,dc=org and [chars] with appropriate values, where [chars] equals the characters that are invalid, separated by |.
    2. Apply the changes using the following ldapmodify command depending on your version:
      • DS 7 and later: $ ./ldapmodify --hostname ds1.example.com --port 1389 --bindDN uid=admin --bindPassword password add.ldif
      • Pre-DS 7: $ ./ldapmodify --hostname ds1.example.com --port 1389 --bindDN "cn=Directory Manager" --bindPassword password add.ldif
  • All modules of type DataStore:
    1. Create a ldif file to set the iplanet-am-auth-ldap-invalid-chars property for all DataStore type modules. For example: $ cat add.ldif dn: ou=default,ou=OrganizationConfig,ou=1.0,ou=sunAMAuthDataStoreService,ou=services,dc=openam,dc=forgerock,dc=org changetype: modify add: sunKeyValue sunKeyValue: iplanet-am-auth-ldap-invalid-chars=[chars]replacing dc=openam,dc=forgerock,dc=org and [chars] with appropriate values, where [chars] equals the characters that are invalid, separated by |.
    2. Apply the changes using the following ldapmodify command depending on your version:
      • DS 7 and later: $ ./ldapmodify --hostname ds1.example.com --port 1389 --bindDN uid=admin --bindPassword password add.ldif
      • Pre-DS 7: $ ./ldapmodify --hostname ds1.example.com --port 1389 --bindDN "cn=Directory Manager" --bindPassword password add.ldif

ssoadm

  • All modules of type LDAP - enter the following command to change this property for all LDAP type modules: $ ./ssoadm set-attr-defs -s iPlanetAMAuthLDAPService -t Organization -u [adminID] -f [passwordfile] -a 'iplanet-am-auth-ldap-invalid-chars=[chars]'replacing [adminID], [passwordfile] and [chars] with appropriate values, where [chars] equals the characters that are invalid, separated by |.
  • All modules of type DataStore - enter the following command to change this property for all DataStore type modules: $ ./ssoadm set-attr-defs -s sunAMAuthDataStoreService -t Organization -u [adminID] -f [passwordfile] -a 'iplanet-am-auth-ldap-invalid-chars=[chars]'replacing [adminID], [passwordfile] and [chars] with appropriate values, where [chars] equals the characters that are invalid, separated by |.
  • A specific module - enter the following command to change this property in a specific authentication module: $ ./ssoadm update-auth-instance -m [modulename] -e [realmname] -u [adminID] -f [passwordfile] -a 'iplanet-am-auth-ldap-invalid-chars=[chars]'replacing [modulename], [realmname], [adminID], [passwordfile] and [chars] with appropriate values, where [chars] equals the characters that are invalid, separated by |.​

See Also

Authentication fails in AM (All versions) when the user name contains special characters

Related Training

N/A

Related Issue Tracker IDs

N/A


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