Guide showing you how to customize the ForgeRock® Access Management user interface.

You can perform the steps of this procedure and edit the XUI source code, or you can find the files as deployed inside the .war file. The examples in the procedure use the source code paths, but you can find the referenced files in the /path/to/tomcat/webapps/openam/XUI directory of a deployed AM .war file.

Perform the following steps to apply a theme to the XUI:

1. Copy your custom Bootstrap theme to a directory in openam-ui-ria/src/resources/themes. A custom Bootstrap theme should consist of one or more CSS files, and optionally, media and font files.

   As an example, the dark theme is available in the openam-ui-ria/src/resources/themes/dark directory.

2. Edit the openam-ui-ria/src/js/config/ThemeConfiguration.js file^[2]:

   1. Locate the themes element, and under it create a new element with the name of your theme. The following example adds a theme called myTheme:

      return {
          themes: {
              // There must be a theme named "default".
              "default": { ...
              },
              "fr-dark-theme": { ...
              },
              "myTheme": {}
          },
          mappings: [...]
      };

   2. In the new theme element, create a stylesheets array containing the theme's two CSS files, followed by the required css/structure.css file.

      return {
          themes: {
              // There must be a theme named "default".
              "default": { ...
              },
              "fr-dark-theme": { ...
              },
              "myTheme": {
                  stylesheets: [
                      "themes/myTheme/css/bootstrap.min.css",
                      "themes/myTheme/css/myTheme.css",
                      "css/structure.css"
                  ]
              }
          },
          mappings: [...]
      };

      Note that you must specify paths relative to the openam-ui-ria/src/resources directory.

      If required, specify additional settings specific to the new theme, such as the logos to use or the footer information. For information on the available settings, see "XUI Configuration Parameters".

   3. Locate the mappings array, and create a new element under it to map your new theme to realms and authentication chains.

      Elements in the mappings array are evaluated in order from top to bottom. The first theme that matches the current realm and/or authentication chain is applied. Any subsequent mappings, even if true, are ignored once a match is found.

      If no match is found, the default theme is applied.

      1. Create a theme element, and set the value to the name of your new theme:

         return {
             themes: { ...
             },
             mappings: [{
                 theme: "myTheme"
             }]
         };

      2. (Optional) Create a realms array, and include the realms the theme will apply to:

         return {
             themes: { ...
             },
             mappings: [{
                 theme: "myTheme",
                 realms: ["/", "/test-realm", /^\/a/]
             }]
         };

         You can use a regular expression to specify the realms the theme should apply to. For example /^\/a/ will apply the theme to all realms that start with /a, including /ab and /a/c.

         If you do not include a realms array, the theme is applied to all realms.

      3. (Optional) Create an authenticationChains array, and include any authentication service (chains or trees) the theme applies to when used:

         return {
             themes: { ...
             },
             mappings: [{
                 theme: "myTheme",
                 realms: ["/", "/test-realm", /^\/a/],
                 authenticationChains: ["auth-chain-one", "Example-Tree"]
             }]
         };

         If you specify both realms and authentication services, the theme is only applied when both criteria are true.

3. (Optional) Compile the XUI project using the yarn build command.

4. (Optional) Start the developent XUI server to test the changes by following the steps detailed in "To Test XUI Pages in a Development Server".

5. Log in as a user to see the new theme applied:

   XUI with the Dark Theme

   
   
   

6. (Optional) 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 XUI pages will use the rebuilt files.

This procedure demonstrates how to customize the layout of XUI pages by copying the relevant files into a theme, editing the source, and making changes to the CSS.

1. Download the XUI source code as explained in "Downloading the XUI".

2. Modify the XUI source as follows:

   1. Copy the src/resources/themes/dark directory to a new directory with a suitable name for the theme that contains your customizations, for example, myTheme.

      Tip

      You can modify the original files, but it is recommended to create a new theme containing your changes.

   2. Edit the openam-ui-ria/src/js/config/ThemeConfiguration.js file, which contains the configuration the XUI uses when applying a theme, and make a copy of the "fr-dark-theme" section, named after the directory you created in the previous step ("myTheme").

      In this example, in the footer element, change the email address to Feedback@example.com, and add a new element called icon that points to an icon to display in the footer.

      Alter the path property to point to the name of the directory you created in the themes directory earlier, including a trailing slash. For example myTheme/.

      The new section will resemble the following:

      "myTheme": {
          // An ordered list of URLs to stylesheets that will be applied to every page.
          stylesheets: [
              "themes/myTheme/css/bootstrap.min.css",
              StructureStyle,
              "themes/myTheme/css/theme-dark.css"
          ],
          // A path that is prepended to every relative URL when fetching resources (including images, stylesheets and
          // HTML template files). Must include a trailing forward slash.
          path: "myTheme/",
          settings: {
              loginLogo: {
                  src: "themes/myTheme/images/login-logo-white.png",
                  title: "ForgeRock",
                  alt: "ForgeRock",
                  height: "228px",
                  width: "220px"
              },
              footer: {
                  // A contact email address.
                  mailto:"Feedback@example.com",
                  // The footer icon.
                  icon : "images/logo-horizontal.png"
              }
          }
      }

      Important

      Specify resource paths within the theme configuration as relative to the openam-ui-ria/src/resources/ directory.

   3. Edit the mappings section of the ThemeConfiguration.js file to apply the new theme to the required contexts.

      For example, to apply the theme to the top-level realm, use:

      mappings: [
          { theme: "myTheme", realms: ["/"] }
      ]

      For more information about the format of the ThemeConfiguration.js file, see "XUI Configuration Parameters".

   4. Copy the openam-ui-ria/src/resources/templates/common/FooterTemplate.html file into the same path but within the myTheme directory, for example:

      $ cp openam-ui-ria/src/resources/templates/common/FooterTemplate.html openam-ui-ria/src/resources/themes/myTheme/templates/common/FooterTemplate.html

      This template contains the HTML code for the footer. This example creates a table in the footer that holds an image, the altered email address, and some text.

   5. Edit the new FooterTemplate.html file as follows:

      <div class="container">
          <p>
              <table align="center">
                  <td>
                      <img src="{{theme.settings.footer.icon}}" alt="Horizontal ForgeRock Logo" align="middle" class="footer_image">
                  </td>
                  <td>
                      <b>ForgeRock XUI at Example.com</b>
                      <br/>
                      <a href="mailto: {{theme.settings.footer.mailto}}">Send us Feedback!</a>
                  </td>
              </table>
          </p>
      </div>

      The file contains variables expressed in double curly brackets ({{}}); they are the paths defined in the ThemeConfiguration.js file.

      Also, the image has the footer_image class applied to simplify applying a CSS style to it in the next step.

   6. Copy and edit any additional files that require customization from the templates and partials directories to the equivalent path in your themes directory.

   7. Edit the /am-external/openam-ui/openam-ui-ria/src/resources/themes/myTheme/css/theme-dark.css file to specify the height of the image, add padding to the footer_image class.

      For example:

      .footer_image {
          height: 3em;
          padding-right: 1em;
      }

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

   Tip

   If you receive errors during the build, you may be missing the required components locally. Try running yarn install, and then try again.

4. (Optional) Test the XUI pages by following the steps detailed in "To Test XUI Pages in a Development Server".

   You can now see the customized template in the login page:

   Example of a Customized Template

   
   
   

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 XUI pages will use the rebuilt files.

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 \
    --port 1389 \
    --hostname openam.example.com \
    --bindDN "cn=Directory Manager" \
    --bindPassword password \
    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.

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 1389 \
     --bindDn "cn=Directory Manager" --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 openam.example.com --port 50389 --bindDn "cn=Directory Manager" --bindPassword forgerock --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 XUI to show the new attribute in the user profile, you need to download the XUI source, edit it, and then rebuild the XUI.

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

1. Download the XUI source as explained in "Downloading the XUI".

2. Modify the XUI as follows:

   1. Edit the openam-ui-ria/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 XUI 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 XUI pages, remember to edit all the translation.json files in your installation.

   2. Edit the openam-ui-ria/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-ria/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 XUI by running the yarn build command.

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

   The XUI 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 XUI pages will use the rebuilt files.