Customizing Identity Stores

Perform the following steps to update the identity repository schema for the custom attribute, and then update AM to use the custom attribute and object class.

If you intend to use an existing attribute that is already allowed on user profile entries, you can skip this procedure.

1. Prepare the attribute type object class definitions in LDIF format. For example:

   $ cat custom-attr.ldif
   dn: cn=schema
   changetype: modify
   add: attributeTypes
   attributeTypes: ( temp-custom-attr-oid NAME 'customAttribute' EQUALITY case
    IgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstrings
    Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE userApplications )
   -
   add: objectClasses
   objectClasses: ( temp-custom-oc-oid NAME 'customObjectclass' SUP top AUXILIARY
     MAY customAttribute )

   In the example, the attribute type is called customAttribute and the object class is called customObjectclass.

2. Add the schema definitions to the directory.

   $ /path/to/opendj/bin/ldapmodify \
   --hostname 'id.example.com' \
   --port 1636 \
   --useSsl \
   --usePkcs12TrustStore /path/to/opendj/config/keystore \
   --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
   --bindDN uid=admin \
   --bindPassword str0ngAdm1nPa55word \
   /path/to/custom-attr.ldif
   Processing MODIFY request for cn=schema
   MODIFY operation successful for DN cn=schema

3. In the AM console, browse to Realms > Realm Name > Identity Stores > Identity Store Name > User Configuration.

4. Add the object class, for example customObjectclass, to the LDAP User Object Class list.

5. Add the attribute type, for example customAttribute, to the LDAP User Attributes list.

6. Save your work.

7. Add the attribute type to the profile attribute whitelist.

   The profile attribute whitelist controls the information returned to non-administrative users when accessing json/user endpoints. For example, the whitelist controls the attributes shown in the user profile page.

   Common profile attributes are whitelisted by default, but you need to add any custom attribute you want your non-administrative users to see.

   The whitelist can be set by realm, in the user self-service service, or globally. To modify it:

   • Globally: Navigate to Configure > Global Services > User Self-Service > Profile Management, and edit the Self readable attributes field.

   • By realm: Navigate to Realms > Realm Name > Services > User Self-Service > Profile Management, and edit the Self readable attributes field.

     Note that you need to add the user self-service service to the realm if you have not done so already, but you do not need to configure anything other than the whitelist.

Perform the following steps to update AM configuration store to give users write permission to the custom attribute.

This procedure assumes you use an LDAP browser, for example Apache Directory Studio. Alternatively, you can follow "To Allow Users to Update the New Attribute Using the Command Line" if you use the command line.

1. Connect to the AM configuration store. You can see the configuration store details by navigating to Deployment > Servers > Directory Configuration > Server.

2. Search for ou=SelfWriteAttributes. You should find DNs similar to the following:

   • dn:ou=SelfWriteAttributes,ou=Policies,ou=default,ou=OrganizationConfig,ou=1.0,ou=iPlanetAMPolicyService,ou=services,o=sunamhiddenrealmdelegationservicepermissions,ou=services,dc=openam,dc=forgerock,dc=org

   • dn:ou=SelfWriteAttributes,ou=default,ou=default,ou=OrganizationConfig,ou=1.0,ou=sunEntitlementIndexes,ou=services,o=sunamhiddenrealmdelegationservicepermissions,ou=services,dc=openam,dc=forgerock,dc=org

3. In the entry under iPlanetAMPolicyService, edit the sunKeyValue attribute to add the custom attribute to the list of self-writable attributes. For example, <Value>customAttribute</Value>.

4. In the entry under sunEntitlementIndexes, edit the sunKeyValue attribute to add the custom attribute to the list of self-writable attributes. The following is an example of the custom attribute as the first element of the list: \"attributes\": [\n \"customAttribute\",\n ....

5. Restart AM or the web container where it runs.

Perform the following steps to update the AM configuration store to give users write permission to the custom attribute.

This procedure assumes you use the command line. Alternatively, you can follow "To Allow Users To Update the New Attribute Using an LDAP Browser" if you use an LDAP browser.

1. Search for the value of sunKeyValue in ou=SelfWriteAttributes by running the following command:

   $ /path/to/opendj/bin/ldapsearch --hostname openam.example.com --port 1636 \
     --bindDn uid=admin --bindPassword forgerock \
     --baseDn "dc=openam,dc=forgerock,dc=org" "(ou=SelfWriteAttributes)" sunKeyValue
   
   dn: ou=SelfWriteAttributes,ou=Policies,ou=default,ou=OrganizationConfig,ou=1.0,ou=iPlanetAMPolicyService,ou=services,o=sunamhiddenrealmdelegationservicepermissions,ou=services,dc=openam,dc=forgerock,dc=org
   sunKeyValue:: eG1scG9saWN5PTw........
   
   dn: ou=SelfWriteAttributes,ou=default,ou=default,ou=OrganizationConfig,ou=1.0,ou=sunEntitlementIndexes,ou=services,o=sunamhiddenrealmdelegationservicepermissions,ou=services,dc=openam,dc=forgerock,dc=org
   sunKeyValue: serializable={"eCondition":{"className":"com.sun.....

   Note that the command returns two DNs, and the value of sunKeyValue in the first one is base64-encoded.

2. Decode the base64 string of the iPlanetAMPolicyService DN. For example:

   $ ./base64 decode --encodedData eG1scG9saWN5PTw........
   xmlpolicy=<?xml version="1.0" encoding="UTF-8"?>
   <Policy name="SelfWriteAttributes" createdby="cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org" lastmodifiedby="cn=dsameuser,ou=DSAME Users,dc=openam,dc=forgerock,dc=org" creationdate="1528296269883" lastmodifieddate="1528296269883" referralPolicy="false" active="true" >
    <Rule name="user-read-rule">
     <ServiceName name="sunAMDelegationService" />
     <ResourceName name="sms://*dc=openam,dc=forgerock,dc=org/sunIdentityRepositoryService/1.0/application/*" />
     <AttributeValuePair>
      <Attribute name="MODIFY" />
      <Value>allow</Value>
     </AttributeValuePair>
    </Rule>
    <Subjects name="Subjects" description="">
     <Subject name="delegation-subject" type="AuthenticatedUsers" includeType="inclusive">
     </Subject>
    </Subjects>
    <Conditions name="AttrCondition" description="">
     <Condition name="condition" type="UserSelfCheckCondition">
      <AttributeValuePair><Attribute name="attributes"/><Value>givenname</Value><Value>sn</Value><Value>cn</Value><Value>userpassword</Value><Value>mail</Value><Value>telephonenumber</Value><Value>postaladdress</Value><Value>preferredlocale</Value><Value>iplanet-am-user-password-reset-options</Value><Value>iplanet-am-user-password-reset-question-answer</Value><Value>description</Value><Value>oath2faEnabled</Value><Value>sunIdentityServerDeviceKeyValue</Value><Value>sunIdentityServerDeviceStatus</Value>
      </AttributeValuePair>
     </Condition>
    </Conditions>
   </Policy>

3. Create a file with the decoded string. Then, add the custom attribute to the <AttributeValuePair> list. For example:

   $ vi to-encode.xml
   ....
      <Attribute name="attributes"/><Value>customAttribute</Value><Value>givenname</Value>...</AttributeValuePair>
   ....

4. Base64-encode the content of the file. For example:

   $ ./base64 encode -f to-encode.xml
   EG1scG9saWN5PTw22.....

5. Create an LDIF file, for example, change.ldif, containing the following:

   • The LDIF properties and rules required to modify the value of the sunKeyValue attribute for both DNs.

   • The newly base64-encoded string as the value of the sunKeyValue attribute of the iPlanetAMPolicyService DN. The string already contains the custom attribute.

   • The value of the sunKeyValue attribute of the sunEntitlementIndexes DN. You must add the custom attribute inside the attributes list.

   The following excerpt is an example of LDIF file:

   dn: ou=SelfWriteAttributes,ou=Policies,ou=default,ou=OrganizationConfig,ou=1.0,ou=iPlanetAMPolicyService,ou=services,o=sunamhiddenrealmdelegationservicepermissions,ou=services,dc=openam,dc=forgerock,dc=org
   changetype: modify
   replace: sunKeyValue
   sunKeyValue: EG1scG9saWN5PTw22.....
   
   dn: ou=SelfWriteAttributes,ou=default,ou=default,ou=OrganizationConfig,ou=1.0,ou=sunEntitlementIndexes,ou=services,o=sunamhiddenrealmdelegationservicepermissions,ou=services,dc=openam,dc=forgerock,dc=org
   changetype: modify
   replace: sunKeyValue
   sunKeyValue: serializable={"eCondition":{"className": ...  \"properties\": {\"attributes\": [\n    \"customAttribute\",\n    \"givenname\",\n    \"sn\",\n  ... \"values\": []\n}"}}

6. Apply the changes in the LDIF file to the LDAP configuration store, as follows:

   $ /path/to/opendj/bin/ldapmodify \
   --hostname 'id.example.com' \
   --port 1636 \
   --useSsl \
   --usePkcs12TrustStore /path/to/opendj/config/keystore \
   --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
   --bindDn uid=admin \
   --bindPassword str0ngAdm1nPa55word \
   --filename change.ldif
   # MODIFY operation successful for DN ou=SelfWriteAttributes,ou=Policies,ou=default,ou=OrganizationConfig,ou=1.0,ou=iPlanetAMPolicyService,ou=services,o=sunamhiddenrealmdelegationservicepermissions,ou=services,dc=openam,dc=forgerock,dc=org
   # MODIFY operation successful for DN ou=SelfWriteAttributes,ou=default,ou=default,ou=OrganizationConfig,ou=1.0,ou=sunEntitlementIndexes,ou=services,o=sunamhiddenrealmdelegationservicepermissions,ou=services,dc=openam,dc=forgerock,dc=org

7. Restart AM or the web container where it runs.

To allow the UI to show the new attribute in the user profile, you need to download the UI source, edit it, and then rebuild the UI.

Perform the following steps to configure the UI to show the new attribute:

1. Download the UI source as explained in Downloading the UI.

2. Modify the UI as follows:

   1. Edit the openam-ui-user/src/resources/locales/en/translation.json file and add a new line with the description for the custom attribute. This description will show in the UI user's profile page. For example:

      ...
      "profile": "Profile",
      "username" : "Username",
      "emailAddress" : "Email address",
      "givenName" : "First Name",
      "customAttribute" : "My Custom Attribute",
      "sn" : "Last Name",
      "changePassword" : "Change password",
      ...
      

      Note that the example adds the custom attribute under the common.user JSON path.

      Tip

      If you have translated the UI pages, remember to edit all the translation.json files in your installation.

   2. Edit the openam-ui-user/src/resources/templates/user/UserProfileTemplate.html file and add a new line for the custom attribute. Consider the following points:

      • property must contain the name of the custom attribute created in the LDAP. For example, customAttribute.

      • label must contain the path to the label created in the translation.json file. In this case, common.user.customAttribute.

      For example:

      {{#user}}
        {{> form/_basicInput property="username" label="common.user.username" readonly=true}}
        {{> form/_basicInput property="givenName" label="common.user.givenName"}}
        {{> form/_basicInput property="sn" label="common.user.sn" required="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"'}}
        {{> form/_basicInput property="customAttribute" label="common.user.customAttribute"}}
      {{/user}}

   3. Edit the openam-ui-user/src/js/org/forgerock/openam/ui/user/UserModel.js file and add the custom attribute on the ServiceInvoker.restCall function.

      Consider the following constraints when modifying this file:

      • The file does not support tab indentation. You must use space indentation.

      • The file does not support lines longer than 120 characters. If the line you are modifying exceeds this limit, break it in multiple lines.

      For example:

      return ServiceInvoker.restCall(_.extend(
      {
          type: "PUT",
          data: JSON.stringify(
              _.chain(this.toJSON())
              .pick(["givenName", "sn", "mail", "postalAddress", "telephoneNumber", "customAttribute"])
              .mapValues((val) => {
                  ...
      }

3. Rebuild the UI by running the yarn build command.

4. Test the UI pages by following the steps detailed in "To Test UI Pages in a Development Server".

   The UI user profile page now shows the custom attribute, and users are able to read and write its values:

   User Custom Attribute

   
   
   

5. Once you are satisfied with the changes, deploy the output in the build directory to the /path/to/tomcat/webapps/openam/XUI/ directory of your AM instances.

   There is no need to restart the AM instance. Subsequent visits to the UI pages will use the rebuilt files.