Customizing AM/OpenAM

This book provides information on customizing AM/OpenAM including customizing the XUI.


How do I modify the prompt text shown when authenticating to a tree in AM 5.5.x and 6.x?

The purpose of this article is to provide assistance if you want to customize the prompt text displayed when authenticating to a tree. This article focuses on changing the User Name and Password prompts.

Background information

Collector nodes provide a callback mechanism where input is collected. A typical example is the username collector, which provides a single text-based callback.

The two main collectors of interest when customizing the login process are the Username Collector Node and the Password Collector Node; each of the collector nodes have a corresponding properties file, which contains the callback.[name] property. This property defines the prompt text.

The collector nodes' property files are located in the auth-nodes-<version>.jar file in the WEB-INF/lib directory of the AM WAR file. You can find these files in the following path within the jar file: org/forgerock/openam/auth/nodes.

Note

Authentication nodes do not have customizable HTML files in the same way that authentication modules do. An RFE exists for this: OPENAM-14467 (RFE: Ability to customise Authentication Tree's).

Modifying the prompt text

The following example demonstrates changing the user name and password prompts:

  1. Unpack the AM WAR file and extract the auth-nodes-<version>.jar file from the WEB-INF/lib directory.
  2. Navigate to the org/forgerock/openam/auth/nodes path within the extracted jar.
  3. If you want localized versions: copy the UsernameCollectorNode.properties and PasswordCollectorNode.properties files to UsernameCollectorNode_xx.properties and PasswordCollectorNode_xx.properties respectively, where _xx corresponds to the required locale, for example _en for English.
  4. Edit the UsernameCollectorNode.properties file (or the UsernameCollectorNode_xx.properties files if you have localized versions) to update the callback.username property to the prompt of your choice, for example:
    callback.username=Your User Name
  5. Edit the PasswordCollectorNode.properties file (or the PasswordCollectorNode_xx.properties files if you have localized versions) to update the callback.password property to the prompt of your choice, for example:
    callback.password=Your Password
  6. Repack the auth-nodes-<version>.jar with your changes.
  7. Add your customization to the AM WAR file:
    • Replace the existing jar file in the WEB-INF/lib directory with your customized jar file.
    • Repack the AM WAR file and deploy as normal.
  8. Restart the web application container in which AM runs.
  9. Test your changes. 

The resulting login page looks like this after a restart:

Followed by the Password Collector Node:

See Also

Best practice for migrating Authentication Chains to Trees in AM 6.x

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

How do I customize authentication tree nodes using source code in AM 5.5.x and 6?

Authentication and Single Sign-On Guide › Configuring Authentication Trees

Related Training

N/A

Related Issue Tracker IDs

OPENAM-14467 (RFE: Ability to customise Authentication Tree's)

OPENAM-12978 (API Explorer - Create Page Node Example Value is inadequate)


How do I modify the text on the XUI Login page for one or more realms in AM/OpenAM (All versions)?

The purpose of this article is to provide assistance if you want to customize the text on the XUI Login page for one or more realms in AM/OpenAM if you are authenticating to a chain.

Overview

Before starting your customizations, it is recommended that you set the following advanced server property to false:

org.forgerock.openam.core.resource.lookup.cache.enabled = false

This setting allows AM/OpenAM to immediately pick up changes to the files as you customize them

See FAQ: Customizing, branding and localizing XUI end user pages in AM/OpenAM (Q. Why are my theme changes being ignored?) for further information on setting this property.

Assumptions

The following instructions assume you are using the default configuration suffix (dc=openam,dc=forgerock,dc=org) and are changing English text. You should be aware of the following if either or both of these assumptions are not true of your deployment:

  • Configuration Suffix: where the instructions refer to creating an openam or openam_en directory, the openam prefix refers to the RDN of the configuration suffix dc=openam,dc=forgerock,dc=org.
  • Localization: where the instructions refer to creating an openam_en directory, the _en refers to the English locale. If you want to customize the Login page for a different language, you should create an openam_xx directory that corresponds to your locale of choice. The default directories for supported locales can be found by navigating to the /path/to/tomcat/webapps/openam/config/auth directory.

Depending on your deployment, you may need to make both of these changes by substituting the example directory names openam and openam_en in the instructions to match your RDN and Locale. For example, if you have changed the default configuration suffix to dc=acme,dc=com and you want to change the French language text for the login page in the employees realm, you would create a directory named acme_fr/services/employees/html directory:

/path/to/tomcat/webapps/openam/config/auth/acme_fr/services/employees/html
Note

It is best practice to make your changes in both the openam directory and the openam_en directory as this ensures all users will see your changes regardless of their locale. Customizations in the openam directory are seen by users whose locale does not match one of the available locales. However, depending on your requirements, it may be sufficient to just make changes in the openam directory.

Modifying the text on the Login page for one or more realms

You can customize the Login page for the top level realm, an individual realm or all / the majority of realms depending on where you make your changes:

  1. Create a directory in the path that AM/OpenAM will use to look up your customized files. Navigate to the /path/to/tomcat/webapps/openam/config/auth directory and create one or more directories as follows depending on where you want your customizations to apply:
    • openam directory:
      Location Directory to create Resulting path
      Top level realm openam/html /path/to/tomcat/webapps/openam/config/auth/openam/html
      Individual realm openam/services/realmname/html /path/to/tomcat/webapps/openam/config/auth/openam/services/realmname/html
      All or the majority of realms openam/services/html /path/to/tomcat/webapps/openam/config/auth/openam/services/html
    • openam_en directory:
      Location Directory to create Resulting path
      Top level realm openam_en/html /path/to/tomcat/webapps/openam_en/config/auth/openam/html
      Individual realm openam_en/services/realmname/html /path/to/tomcat/webapps/openam_en/config/auth/openam/services/realmname/html
      All or the majority of realms openam_en/services/html /path/to/tomcat/webapps/openam_en/config/auth/openam/services/html
    If you choose to make changes that affect all or the majority of realms, these customizations will affect all realms that do not have a corresponding realmname/html directory.
Note

The realmname directory must all be in lower case for the realm customizations to be located.

  1. Copy the contents of the /path/to/tomcat/webapps/openam/config/auth/default and/or /path/to/tomcat/webapps/openam/config/auth/default_en directory to your new /html directories.
  2. Edit the .xml file applicable to the authentication module for which you want to customize the login page; such as, the DataStore.xml file for the Data Store authentication module. You can change the header or prompt text shown, add additional HTML fields and even add script blocks, which will be executed when the page loads.
  3. Restart the web application container in which AM/OpenAM runs.

You can have a combination of customizations, for example, you can have a login page for the top level realm, one for the customers realm and a separate one for all other realms by changing the relevant .xml file in all three places.

Example changes in the DataStore.xml file

The following example DataStore.xml file has been updated to change the prompts for user name and password, and also the header text shown:

<ModuleProperties moduleName="DataStore" version="1.0" >
    <Callbacks length="2" order="1" timeout="120" header="Sign in to OpenAM top level realm" >
        <NameCallback>
            <Prompt>Your Username:</Prompt>
        </NameCallback>
        <PasswordCallback echoPassword="false" >
            <Prompt>Your Password:</Prompt>
        </PasswordCallback>
    </Callbacks>
</ModuleProperties>

The resulting login page looks like this after a restart (in OpenAM 13.x): 

See Also

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

How do I configure login page session timeouts in AM/OpenAM (All versions) when using authentication modules?

How do I add a new custom XUI page in AM 5.x and OpenAM 13.x?

How do I change the title shown on the browser tab in AM 5.x and OpenAM 13.x?

UI Customization Guide › Customizing the User Interface

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

Related Training

ForgeRock Access Management Core Concepts (AM-400)

ForgeRock Access Management Customization and APIs (AM-421)

Related Issue Tracker IDs

N/A


How do I add a new custom XUI page in AM 5.x and OpenAM 13.x?

The purpose of this article is to provide information on adding a new custom XUI page. Custom XUI pages can be used to extend the functionality in AM/OpenAM.

Adding an new custom UI page

The XUI uses require.js for modular JavaScript® loading, backbone.js for model/view binding and handlebars.js for templating.

The following steps demonstrate creating a XUI page in AM/OpenAM that includes some sample text.

  1. Create a routes file to introduce a new route to your view, for example:
    /path/to/tomcat/webapps/openam/XUI/config/routes/CustomAMRoutesConfig.js
    And define a route in this file, for example:
    define("config/routes/CustomAMRoutesConfig", [
    ], function() {
    
        var obj = {
            "helloWorldView" : {
                view: "org/forgerock/openam/ui/custom/HelloWorldView",
                role: "ui-user",
                url: "helloWorld/"
            }
        };
    
        return obj;
    });
    
  2. Update the AppConfiguration.js file (located in the /path/to/tomcat/webapps/openam/XUI/config/ directory) to add the new routes file to your Application Configuration; find the section that includes paths to the routes (~line 31) and add a new route: 
    { "routes": "config/routes/CustomAMRoutesConfig" }
    
  3. Create a view file, for example:
    /path/to/tomcat/webapps/openam/XUI/org/forgerock/openam/ui/custom/HelloWorldView.js
    
    And add your view code to this file, for example:
    define("org/forgerock/openam/ui/custom/HelloWorldView", [
        "org/forgerock/commons/ui/common/main/AbstractView",
        "org/forgerock/commons/ui/common/main/Configuration",
        "org/forgerock/commons/ui/common/util/UIUtils"
    
     ], function(AbstractView) {
    
        var HelloWorldView = AbstractView.extend({
            template: "templates/custom/HelloWorld.html",
            baseTemplate: "templates/common/DefaultBaseTemplate.html",
            events: {
    
            }
    
        });
        return new HelloWorldView();
    });
    
  4. Create a template file, for example:
    /path/to/tomcat/webapps/openam/XUI/templates/custom/HelloWorld.html
    And add some sample text to this file:
    <h2>Hello World!</h2>
    <p>
    Some sample text. 
    </p>
    
    
  5. Clear your browser cache and restart the web application container in which AM/OpenAM runs to apply these changes. 

That's it. You should now be able to view the new view by navigating to #helloWorld/ after logging in, for example:

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

See Also

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

How do I modify the text on the XUI Login page for one or more realms in AM/OpenAM (All versions)?

How do I customize the fields for User Self-Service pages in AM (All versions) and OpenAM 13.x?

How do I change the title shown on the browser tab in AM (All versions) and OpenAM 13.x?

Related Training

ForgeRock Access Management Core Concepts (AM-400)

ForgeRock Access Management Customization and APIs (AM-421)

Related Issue Tracker IDs

N/A


How do I change the title shown on the browser tab in AM 5.x and OpenAM 13.x?

The purpose of this article is to provide assistance on changing the title shown on the browser tab in AM/OpenAM. This article includes instructions on changing this at the global level and realm level.

Changing the browser tab title (global level)

You can modify this title at the global level by editing the title field in the index.html file (located in the /path/to/tomcat/webapps/openam/XUI directory). For example, you could change this to Admin Console as follows:

    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>Admin Console</title>
    </head>

This change affects all realms and takes effect immediately. The resulting tab title would look like this:

Changing the browser tab title (realm level)

You can either modify this title at the realm level so it is dynamic and uses the realm name or you can set it for individual realms.

Dynamic

You can make the realm title dynamic by using the {{realm}} variable as shown below:

  1. Edit the LoginHeaderTemplate.html file (located in the /path/to/tomcat/webapps/openam/XUI/templates/common directory). You need to add the following code snippet to the end of this file, where document.title is set to the desired tab title and includes the {{realm}} variable, for example:
    <script language="javascript" type="text/javascript">
       document.title = "Realm: {{realm}}";
    </script>
    
  2. Clear your browser cache.

The resulting tab title would look like this for the /employees realm:

Individual realms

You can set the tab title for a specific realm as follows, where this example is customizing the title for the /employees realm:

  1. Create a directory in the /path/to/tomcat/webapps/openam/XUI directory that is named the same as your realm. In this example, your resulting path would look like this:
    /path/to/tomcat/webapps/openam/XUI/employees
  2. Copy the templates and partials directories (located in the /path/to/tomcat/webapps/openam/XUI directory) to the new realm directory you created in step 1.
  3. Edit the LoginHeaderTemplate.html file in your new realm directory (located in the /path/to/tomcat/webapps/openam/XUI/employees/templates/common directory in this example). You need to add the following code snippet to the end of this file, where document.title is set to the desired tab title (Employees in this example):
    <script language="javascript" type="text/javascript">
       document.title = "Employees";
    </script>
    
  4. Add the realm to the ThemeConfiguration.[hash].js file in AM 6 and later (where [hash] is an alphanumeric value generated each time the XUI is rebuilt) or the ThemeConfiguration.js file in AM 5.x and OpenAM 13.x. These files are located in the /path/to/tomcat/webapps/openam/XUI/config/ directory. You must create a theme that corresponds to the realm customization and also add a realm mapping per UI Customization Guide › Customizing the User Interface › Theming the XUI:
    • Add a new theme after the default theme (this example is a copy of the fr-dark-theme with the addition of the path parameter to identify the directory you created in step 1 and the icon parameter to prevent a missing image in the tab title:
              "employees-theme": {
                  // An ordered list of URLs to stylesheets that will be applied to every page.
                  stylesheets: ["themes/dark/css/bootstrap.min.css", "css/structure.css", "themes/dark/css/theme-dark.css"],
                  path: "employees/",
                  icon: "../favicon.ico",
                  settings: {
                      loginLogo: {
                          src: "themes/dark/images/login-logo-white.png",
                          title: "ForgeRock",
                          alt: "ForgeRock",
                          height: "228px",
                          width: "220px"
                      }
                  }
              },
      
    • Add a realm mapping at the end within the mappings [ ] section that maps the new theme you created to your realm:
      { theme: "employees-theme", realms: ["/employees"] }
      
  5. Clear your browser cache.

The resulting tab title would look like this (note this example also has the dark theme applied): 

See Also

How do I add a new custom XUI page in AM (All versions) and OpenAM 13.x?

How do I modify the text on the XUI Login page for one or more realms in AM/OpenAM (All versions)?

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

UI Customization Guide › Customizing the User Interface

Related Training

ForgeRock Access Management Core Concepts (AM-400)

ForgeRock Access Management Customization and APIs (AM-421)

Related Issue Tracker IDs

OPENAM-11141 (HTML page title is not localised)


How do I customize the fields for User Self-Service pages in AM (All versions) and OpenAM 13.x?

The purpose of this article is to provide information on customizing the User Self-Service pages (XUI) in AM/OpenAM. This information will help you add and remove fields from the User Registration, Password Reset and Forgotten Username pages.

Overview

Each of the user self-service pages are associated with a template.

The basic process to add and remove fields from these pages is the same; you just need to make the changes to the appropriate template. Customizing the User Registration page includes an extra step to configure the user attributes the user can set during registration. These attributes must exist in the AM/OpenAM identity repository; if they do not, you can add them as detailed in Setup and Maintenance Guide › Customizing Profile Attributes before following these steps.

If you have added a new field, you also need to update the translation.json file. This file is located in the /path/to/tomcat/webapps/openam/XUI/locales/en directory by default. However, depending on where AM/OpenAM is retrieving the requested locale from, you may need to create a new locale folder. For example, if the locale in your browser is set to en-US and AM/OpenAM is retrieving the requested locale from the "Accept-Language" HTTP header in the web browser, you must create an en-US directory in the XUI/locales directory, copy the contents from the en directory to this new directory and modify the translation.json file in the en-US directory.

Note

You should take backups of any files you plan to change to ensure you can revert your changes if needed.

The details for where the template files are located and how you retrieve them differ according to your version:

There is also a worked example which shows how you would add and remove fields from the User Registration page; this example applies to all versions.

Customizing the User Self-Service pages (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).

The following templates are located in the /am-external/openam-ui/openam-ui-ria/src/main/resources/templates/user/process directory once you have obtained the source:

  • User Registration page - registration/userDetails-initial.html
  • Password Reset page - reset/userQuery-initial.html
  • Forgotten Username page - username/userQuery-initial.html

You can customize these pages as follows (worked examples are shown below to give more details):

  1. Follow the steps in UI Customization Guide › Downloading the XUI to obtain the XUI source.
  2. Edit the required template file (located in the /am-external/openam-ui/openam-ui-ria/src/main/resources/templates/user/process directory):
    • To remove an existing field: Remove the div element associated with the field you want to remove.
    • To add a new field: Add a div element for the new field based on the other fields in the template.
  3. Follow steps in UI Customization Guide › Testing and Deploying the XUI to test your changes, then rebuild and deploy.
  4. If you have added a new field: Update the translation.json file to add a mapping for the new field if it does not already exist. Navigate to the "user" : { section and skip past the page specific translations (such as userQuery, passwordReset etc) until you reach the list of fields that include the following:
    "user" : {
                "userQuery" : {
    ...
    
      "username" : "Username",
      "emailAddress" : "Email address",
      "givenName" : "First Name",
      "sn" : "Last Name",
      ...
    }
    
    Add the new field in the same format with the label you want displayed.
  5. If you are updating the User Registration page: Update the user attributes the user can set during registration. These attributes must exist in the identity repository and correspond to the fields you have added or removed. You can update these attributes using either the console, Amster or ssoadm:
    • Console: navigate to: Configure > Global Services > User Self Service > User Registration > Valid Creation Attributes and add the additional user attributes / delete any that have been removed.
    • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
      • Entity: UserSelfService
      • Property: userRegistrationValidUserAttributes
    • ssoadm: enter the following command:
      $ ./ssoadm set-attr-defs -s selfService -t organization -u [adminID] -f [passwordfile] -a selfServiceUserRegistrationValidUserAttributes=[userAttribute] selfServiceUserRegistrationValidUserAttributes=[userAttribute] selfServiceUserRegistrationValidUserAttributes=[userAttribute] ...
      replacing [adminID], [passwordfile] and [userAttribute] with appropriate values.
Caution

You must include the selfServiceUserRegistrationValidUserAttributes attribute for each required attribute, including any that already exist. The ones you add with this command will overwrite any that have already been set.

  1. Clear your browser cache and restart the web application container in which AM runs to apply these changes. 

Customizing the User Self-Service pages (AM 5.x and OpenAM 13.x)

The following templates are located in the /path/to/tomcat/webapps/openam/XUI/templates/user/process directory:

  • User Registration page - registration/userDetails-initial.html
  • Password Reset page - reset/userQuery-initial.html
  • Forgotten Username page - username/userQuery-initial.html

You can customize these pages as follows (worked examples are shown below to give more details):

  1. Edit the required template file:
    • To remove an existing field: Remove the div element associated with the field you want to remove.
    • To add a new field: Add a div element for the new field based on the other fields in the template.
  2. If you have added a new field: Update the translation.json file to add a mapping for the new field if it does not already exist. Navigate to the "user" : { section and skip past the page specific translations (such as userQuery, passwordReset etc) until you reach the list of fields that include the following:
    "user" : {
                "userQuery" : {
    ...
    
      "username" : "Username",
      "emailAddress" : "Email address",
      "givenName" : "First Name",
      "sn" : "Last Name",
      ...
    }
    
    Add the new field in the same format with the label you want displayed.
  3. If you are updating the User Registration page: Update the user attributes the user can set during registration. These attributes must exist in the identity repository and correspond to the fields you have added or removed. You can update these attributes using either the console, Amster (AM 5.x) or ssoadm:
    • AM 5.x / OpenAM 13.5 console: navigate to: Configure > Global Services > User Self Service > User Registration > Valid Creation Attributes and add the additional user attributes / delete any that have been removed.
    • OpenAM 13 console: navigate to: Configuration > Global > User Self Service > User Registration > Valid Creation Attributes and add the additional user attributes / delete any that have been removed.
    • Amster: follow the steps in How do I update property values in AM (All versions) using Amster?with these values:
      • Entity: UserSelfService
      • Property: userRegistrationValidUserAttributes
    • ssoadm: enter the following command:
      $ ./ssoadm set-attr-defs -s selfService -t organization -u [adminID] -f [passwordfile] -a selfServiceUserRegistrationValidUserAttributes=[userAttribute] selfServiceUserRegistrationValidUserAttributes=[userAttribute] selfServiceUserRegistrationValidUserAttributes=[userAttribute] ...
      replacing [adminID], [passwordfile] and [userAttribute] with appropriate values.
Caution

You must include the selfServiceUserRegistrationValidUserAttributes attribute for each required attribute, including any that already exist. The ones you add with this command will overwrite any that have already been set.

  1. Clear your browser cache and restart the web application container in which AM/OpenAM runs to apply these changes. 

Example changes to the User Registration page

This worked example removes the First Name field from the User Registration page and adds a Title field:

  1. Edit the registration/userDetails-initial.html file.
  2. Remove the First Name field by removing the following div element:
        <div class="form-group">
            <label class="sr-only separator" for="input-givenName">
                <span>{{t 'common.user.givenName'}}</span>
            </label>
            <input type="text" placeholder="{{t 'common.user.givenName'}}" id="input-givenName" name="user.givenName" class="form-control input-lg" />
        </div>
    
    
  3. Add the Title field by adding a new div element as follows:
        <div class="form-group">
            <label class="sr-only separator" for="input-title">
                <span>{{t 'common.user.title'}}</span>
            </label>
            <input type="text" placeholder="{{t 'common.user.title'}}" id="input-title" name="user.title" class="form-control input-lg" />
        </div>
    
  4. Update the translation.json file to add a new mapping for the Title field. This mapping should be in the list of fields within the "user" : { section (seen once you have skipped past the page specific translations such as userQuery, passwordReset etc). For example, append the Title field at the end of this list of fields as follows:
    "user" : {
                "userQuery" : {
    ...
    
      "username" : "Username",
      "emailAddress" : "Email address",
      "givenName" : "First Name",
      "sn" : "Last Name",
      ...
      ...
      "title" : "Title",
    },
    
  5. Update the valid creation attributes. For example using the ssoadm command: 
    $ ./ssoadm set-attr-defs -s selfService -t organization -u amadmin -f pwd.txt -a selfServiceUserRegistrationValidUserAttributes=mail selfServiceUserRegistrationValidUserAttributes=inetUserStatus selfServiceUserRegistrationValidUserAttributes=sn selfServiceUserRegistrationValidUserAttributes=username selfServiceUserRegistrationValidUserAttributes=userPassword selfServiceUserRegistrationValidUserAttributes=kbaInfo
    selfServiceUserRegistrationValidUserAttributes=title
  6. Clear your browser cache and restart the web application container in which AM/OpenAM runs to apply these changes. 

See Also

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

How do I add a new custom XUI page in AM 5.x and OpenAM 13.x?

How do I change the title shown on the browser tab in AM 5.x and OpenAM 13.x?

User Self-Service in AM/OpenAM

User Self Service Guide › Implementing User Self Service

Related Training

ForgeRock Access Management Core Concepts (AM-400)

ForgeRock Access Management Customization and APIs (AM-421)

Related Issue Tracker IDs

N/A


Frequently Asked Questions


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

The purpose of this FAQ is to provide answers to commonly asked questions regarding customizing, branding and localizing XUI end user pages in AM/OpenAM. It also includes information on other customizations such as error messages and forgotten password emails.

Frequently asked questions

Q. How do I customize user-facing pages in the XUI?

A. As of OpenAM 13 you can use themes to alter the appearance of user-facing XUI pages. The XUI is built with the Bootstrap framework, and supports Bootstrap themes to customize the look and feel of the user interface. You can apply themes to specific realms, and also to specific authentication chains within those realms. These themes apply to all user-facing XUI pages (Login, User profile, User Self-Service and UMA). Additionally, you can make changes to template files to change how pages display and function.

See UI Customization Guide › Customizing the User Interface for further information on customizing the user-facing pages.

In OpenAM 12.x, the XUI interface is still evolving and theming is handled differently as described in OpenAM 12 Installation Guide › Configuring the XUI.

Note

For production deployments, you should unzip the AM/OpenAM .war file, add your customizations and then rezip the .war file before deploying.

Q. Why are my theme changes being ignored?

A. This is likely a cache issue. You should completely clear your browser cache after making any changes.

During the customization process, you can set the org.forgerock.openam.core.resource.lookup.cache.enabled advanced server property to false. This setting allows AM/OpenAM to immediately pick up changes to the files located in the /path/to/tomcat/webapps/openam/config/auth/ directory as you customize them. These files include the authentication module (callback) XML files and legacy UI template files.

You can set this advanced property using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Deployment > Servers > [Server Name] > Advanced and add the org.forgerock.openam.core.resource.lookup.cache.enabled property and set it to false.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > [Server Name] > Advanced and add the org.forgerock.openam.core.resource.lookup.cache.enabled property and set it to false.
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s [serverName] -u [adminID] -f [passwordfile] -a org.forgerock.openam.core.resource.lookup.cache.enabled=false
    replacing [serverName], [adminID] and [passwordfile] with appropriate values.
Note

Before using AM/OpenAM in production, you should set this property back to the default setting of true to improve performance.

Q. How can I ensure end users see the latest file rather than a cached version?

A. In AM 6 and later, file names include a .[hash] suffix, where [hash] is an alphanumeric value generated each time the XUI is rebuilt. This hash ensures the latest version is always loaded. However, this doesn't apply to translations or CSS files per known issue: OPENAM-14096 (No Cache Busting in XUI for i18n or CSS).

Pre-AM 6

If you are customizing files such as .html, .css or .js, you can ensure updated files are loaded in the browser instead of earlier cached versions by changing the urlArgs value in the index.html file (located in the /path/to/tomcat/webapps/openam/XUI directory) at the same time. For example, in AM 5, you could add -1 to the default of 14.0.0:

        <script type="text/javascript">
            var require = {
                urlArgs : "v=14.0.0-1",
                deps : ['main']
            };
        </script>

This value is appended to files as a parameter when they are called, which ensures the new files are loaded rather than a cached version. You can see this in the browser using developer tools, for example:

DataStore1.html?v=14.0.0-1

 Index.html has a cache time of max-age=300, so users should see any changes quite quickly.

Q. What troubleshooting steps should I take if my theme is not applied as expected?

A. The first troubleshooting step you should take is to check that you don't have any typos in your theme configuration files. For JSON files, you can use a JSON validator in your IDE or text editor to verify the JSON syntax, or use http://jsonlint.com.

In AM / OpenAM 13.x, you should also check the following:

  • Ensure your Bootstrap theme follows standard conventions and complies with the Bootstrap framework.
  • Check the order of elements in the mappings array in the ThemeConfiguration.[hash].js file in AM 6 and later (where [hash] is an alphanumeric value generated each time the XUI is rebuilt) or the ThemeConfiguration.js file in AM 5.x and OpenAM 13.x. These files are located in the /path/to/tomcat/webapps/openam/XUI/config/ directory. Mappings are evaluated in order starting at the top; the first theme that matches the current realm and/or authentication chain is applied and all subsequent mappings are ignored even if they are true.

Q. How do I customize the Login page?

A. You can customize the login page by amending the associated template files. The default login page with a DataStore authentication module uses the DataStore1.html, NavigationTemplate.html, LoginBaseTemplate.html and FooterTemplate.html template files. For example, you can add additional HTML fields to the DataStore1.html file or script blocks, which will be executed when the page loads to extend the functionality further. To customize login pages for other authentication modules, you need to create a new file based on DataStore1.html. For example, you would create LDAP1.html for the LDAP authentication module by copying DataStore1.html and amending as needed.

See How do I modify the text on the XUI Login page for one or more realms in AM/OpenAM (All versions)? for information on customizing the text on the login page, which uses a different file.

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 customize these templates files by following the steps in UI Customization Guide › Customizing the User Interface to download, rebuild and deploy the XUI project. Once you have downloaded the XUI source, you can edit the following template files as required:

  • DataStore1.html file is located in the /am-external/openam-ui/openam-ui-ria/src/main/resources/templates/openam/authn directory.
  • The other template files are located in the /am-external/openam-ui/openam-ui-ria/src/main/resources/templates/common directory.

Pre-AM 6

The DataStore1.html file is located in the /path/to/tomcat/webapps/openam/XUI/templates/openam/authn directory where AM/OpenAM is deployed and the other template files are located in the /path/to/tomcat/webapps/openam/XUI/templates/common directory where AM/OpenAM is deployed.

You can change these template files as needed and restart the web application container in which AM/OpenAM runs.

Q. Aren't the authentication module XML files legacy?

A. No, the authentication module XML files (located in the /path/to/tomcat/webapps/openam/config/auth/ directory where AM/OpenAM is deployed) are not legacy. Although these files do affect the content seen by the end-user using the classic UI, they also affect the pages when XUI is used.

Q. How do I change the user naming attribute value for the User Profile page?

A. The uid value is used by default for the Username field on the User Profile page. If you have made changes to your data store configuration (such as replacing uid with cn) or you use Active Directory® for your data store (which does not use uid), you can map the uid attribute to the one you use to ensure the user name is shown correctly on the User Profile page:

Navigate to: Realms > [Realm Name] > Data Stores > [Data Store Name] > Attribute Name Mapping and specify your mapping, for example:

uid=cn

Q. How do I customize error / user messages displayed in AM/OpenAM?

A. You should amend the text in the translation.json file to customize the displayed user messages. The file containing the English text is located in the /path/to/tomcat/webapps/openam/XUI/locales/en directory where AM/OpenAM is deployed. However, depending on where AM/OpenAM is retrieving the requested locale from, you may need to create a new locale folder. For example, if the locale in your browser is set to en-US and AM/OpenAM is retrieving the requested locale from the "Accept-Language" HTTP header in the web browser, you must create an en-US directory in the XUI/locales directory, copy the contents from the en directory to this new directory and modify the translation.json file in the en-US directory.

See UI Customization Guide › Localizing the XUI for further information on using this file to translate AM/OpenAM text. 

Authentication Failed message

The Authentication Failed message displayed in a red popup when logging in is the response from the REST /json/authenticate endpoint:

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

This means you cannot change it via the translation.json file.

This message comes from amAuth.properties (errorCode: 107) within the openam-core-*.jar file. You can extract this file from the jar, customize the message and place the updated amAuth.properties file in the /path/to/tomcat/webapps/openam/WEB-INF/classes directory. You will need to restart the web application container in which AM/OpenAM runs for it to take affect. 

Note

You cannot localize the Authentication Failed message per known issue:  OPENAM-4201 (XUI returning messages based on localised responses from REST authentication interface).

Q. How do I include the user's email address or username in the forgotten password email?

A. Allowing the username to be sent via the change password functionality requires custom coding. There is a RFE to include this option: OPENAM-10464 (Allow OpenAM to include the username/email of the user whose password is being reset in the forgotten password reset link).

If you require this functionality, you can customize the following Forgotten Password Service Config Provider Class that is used by the forgotten password function:

org.forgerock.openam.selfservice.config.flows.ForgottenPasswordConfigProvider

The org.forgerock.openam.selfservice.config.flows.ForgottenUsernameConfigProvider class described in User Self Service Guide › Advanced Configuration sends the username by passing the %username% function; you can use this as the basis for customizing the forgotten password class. You should be able to make similar customizations to make the email address available in the forgotten password email as well.

Note

This change is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

Q. How do I customize the self-registration or forgotten password pages in AM / OpenAM 13.x?

A. You can configure which fields are shown on the following user self-service pages as described in How do I customize the fields for User Self-Service pages in AM (All versions) and OpenAM 13.x?

  • User Registration
  • Password Reset
  • Forgotten Username

See Custom Stages to User Self-Service for information on adding custom plugins or stages to further extend the functionality; although this blog post mainly references OpenIDM, it is a common self-service so the same steps are applicable.

Q. How do I customize the Authorization Consent page (oauth2/authorize endpoint)?

A. This depends on what version of AM/OpenAM you are using:

AM 6.5

As of AM 6.5, you can customize this page (and other user-facing pages) on a per realm basis using the logo_uri, client_uri and policy_uri parameters (RFC 7591). See OAuth 2.0 Guide › Advanced for further information.

Pre-AM 6.5

The OAuth Authorization Consent page is rendered by a template (authorize.ftl). This template is located inside the openam-oauth2-x.x.x.jar (OpenAM 13.5 and later) or the oauth2-restlet-1x.0.x.jar (pre-OpenAM 13.5), which is in the WEB-INF/lib directory within openam.war.

Extract a version of the authorize.ftl file from the templates/page directory within the jar file and copy it to the /path/to/tomcat/webapps/openam/WEB-INF/classes/templates/pages directory where AM/OpenAM is deployed. You can then edit this file to customize the Authorization Consent page, ensuring you do not change any of the tags. Any changes you make in this way apply to all realms.

Q. How do I customize other OAuth 2.0 pages?

A. Similar to the Authorization Consent page, it depends on what version of AM/OpenAM you are using:

AM 6.5

As of AM 6.5, you can customize user-facing pages on a per realm basis using the logo_uri, client_uri and policy_uri parameters (RFC 7591). See OAuth 2.0 Guide › Advanced for further information.

Pre-AM 6.5

The other OAuth 2.0 pages are rendered by template files (*.ftl). These template files are located inside the openam-oauth2-x.x.x.jar (OpenAM 13.5 and later) or the oauth2-restlet-1x.0.x.jar (pre-OpenAM 13.5), which is in the WEB-INF/lib directory within openam.war.

Extract a version of the required *.ftl file from the templates/ directory within the jar file and copy it to the corresponding /path/to/tomcat/webapps/openam/WEB-INF/classes/templates/ directory where AM/OpenAM is deployed. You can then edit this file to customize the page, ensuring you do not change any of the tags. Any changes you make in this way apply to all realms.

Q. How do I change or remove the link associated with the ForgeRock logo on the Login page in OpenAM 12.x?

A. In OpenAM 12.x, the ForgeRock logo is a link that returns you to the top level realm login page.

You can change or remove this link functionality as follows: 

  1. Edit the LoginBaseTemplate.html file (located in the /path/to/tomcat/webapps/openam/XUI/templates/common directory where OpenAM is deployed) and update the following line:
    <a href="#" title="{{theme.settings.logo.title}}">
    
  2. You can change this link as follows depending on what you're trying to achieve:
    • Remove link:
      <a title="{{theme.settings.logo.title}}">
      
    • Change link:
      <a href="http://www.newlink.com" title="{{theme.settings.logo.title}}">
      
  3. Clear the browser cache and retest; you should now see your changes.

Q. How should I call a realm level login page?

A. The correct format for the URL with the realm parameter depends on your version:

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

See AM Authentication and Single Sign-On Guide › Specifying the Realm in the Login URL or OpenAM 13.5 Administration Guide › Specifying the Realm in the Login URL for further information.

Note

There is a known issue with including the realm in the URL: OPENAM-6470 (ThemeManager.js doesn't need to strip "/" anymore when loading theme for realm). This is fixed in OpenAM 12.0.4. As a workaround in earlier versions, you can remove the first letter from your sub-realm name in themeConfig.json.

Q. Is JavaScript® required for logging into AM/OpenAM?

A. Yes it is, the console and login pages packaged with AM/OpenAM are JavaScript based, so a browser needs JavaScript enabled to render these pages correctly. You could create a custom interface using the REST API if a non-JavaScript based UI was required.

Q. Why do country specific locale pages display the default en language?

A. If you have created a translation.json file for a new locale (for example zh), the appropriate customizations are shown when your locale is zh. However, by default, any country specific locales within that locale (for example zh-HK), fall back to the default en customizations rather than the expected zh customizations.

To ensure the correct customizations are shown for country specific locales, you need to add a new config option (with the i18nLoad option set to specific) to the index.html file (located in the /path/to/tomcat/webapps/openam/XUI directory). The updated section should now look like this:

        <script type="text/javascript">
            var require = {
                urlArgs : "v=13.5.0",
                config : {
                   'org/forgerock/commons/ui/common/main/i18nManager': {
                      i18nLoad: 'specific'
                   }
                },
                deps : ['main']
            };
        </script>

See  OPENAM-7123 (Allow country-specific localization in XUI) for further information.

Q. How does AM/OpenAM choose the language shown in user-facing XUI pages?

A. AM/OpenAM chooses which language to show content in (and loads the associated translation file) based on the user's locale. The user's locale is derived in the following order:

  1. The locale query string parameter in the URL, for example, &locale=fr
  2. The locale set in the user’s browser, which is a 2 or 5 character long language or locale, for example en or en-US.
  3. The Default locale, which is set to en by default. This is used when neither a query string parameter or browser language is set. 

Default locale

You can change the default locale using either the console or ssoadm:

  • AM / OpenAM 13.5 console: navigate to: Configure > Server Defaults > General > System > Default Locale and specify the default locale.
  • Pre-OpenAM 13.5 console: navigate to: Configuration > Servers and Sites > Default Server Settings > General > System > Default Locale and specify the default locale.
  • ssoadm: enter the following command:
    $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.iplanet.am.locale=[locale]
    replacing [adminID], [passwordfile] and [locale] with appropriate values.

See UI Customization Guide › Customizing the User Interface › Localizing the XUI for further details. This section explains how to localize the text that is generated for the user-facing XUI pages.

Q. Can I make pages responsive for use on mobile devices?

A. AM / OpenAM 13.x has a responsive design by default. In OpenAM 12.x, you need to customize the XUI files to make the CSS responsive. There is a known limitation regarding pages that include tables; these cannot be made fully responsive due to the particular library that was used in OpenAM 12.

Q. Can I customize the JSP files in XUI?

A. No, you cannot. The JSP files are specific to the Classic UI and do not affect the appearance of the XUI.

Q. Can I use the Classic UI instead of the XUI?

A. Although you can use the Classic UI, it is not recommended because the XUI has a more modern REST architecture. Additionally, the Classic UI is deprecated in OpenAM 13 and likely to be removed in a future release.

See Also

Understanding and customizing the XUI in OpenAM 12.x

How do I add a new custom XUI page in AM 5.x and OpenAM 13.x?

Customizing AM/OpenAM

Related Training

ForgeRock Access Management Core Concepts (AM-400)

ForgeRock Access Management Customization and APIs (AM-421)

Related Issue Tracker IDs

OPENAM-8452 (Cannot access Sub Realm with DNS Alias set (XUI) with 404 Not Found)

OPENAM-8342 (AuthorizeTemplate ignores custom theme)

OPENAM-7282 (Forgotten password submit button is disabled when using autocomplete)


Source Code


How do I update and recompile the iOS authenticator app with custom branding in AM (All versions)?

The purpose of this article is to provide information on updating and recompiling the iOS® authenticator app in AM so that it can be published to the Apple® App Store. Changes include renaming the app and rebranding changes, such as updating the Splashscreen video, updating the app icon and changing default colours.

Warning

ForgeRock support covers the use of the official binary builds made available and downloaded from our customer portal: BackStage. We will support builds made from source providing no changes have been made to the core code of the product, the product was built from a tag that matches an official release, for example, 6 and said product was built using the ForgeRock build scripts provided as part of the source. In the event that a customer experiences an issue with a ForgeRock product built from source where ForgeRock believe the issue is as a result of the build process, ForgeRock reserves the right to ask the customer to attempt to reproduce the issue on an official ForgeRock binary build. Customers who are running custom builds or who need further clarification should contact their ForgeRock sales representative.

Overview

This article explains how to clone the iOS ForgeRock Authenticator app source code and create your own version of the app that you can publish to the Apple App Store. There is also a section that provides links relevant to setting up Push notifications.

High level steps

  1. Create a new iOS App Bundle ID
  2. Obtain Authenticator source, prepare a project and open in Xcode
  3. Launch the App on an iPhone®
  4. Rename the project
  5. Rename the scheme
  6. Update the CocoaPods configuration
  7. Rename the ForgeRock-Authenticator directory
  8. Rename the Entitlements file
  9. Update the Build settings and rebuild
  10. Update the Test Build settings
  11. Update the Splashscreen video
  12. Update App Permission Request dialogs
  13. Update Localizable.strings
  14. Update About.strings
  15. Update the App icon
  16. Update the Default Account icon
  17. Update the Default colors
  18. Publish your App

These steps were completed using Xcode Version 10.0 (10A255).

Note

Before updating the Authenticator app, please make sure Xcode® is installed and up-to-date.

Create a new iOS App Bundle ID

  1. Log in to your paid Apple Developer account (http://developer.apple.com/account).
  2. Select Certificates, Identifiers & Profiles.
  3. Select App IDs (under Identifiers in the menu on the left).
  4. Select the “+” (Add) icon.
  5. Complete the Registering an App ID form:
    1. Enter an App ID description, for example “ACME Authenticator”.
    2. Select Explicit App ID and enter a bundle ID, for example “com.acme.authenticator”.
    3. Leave default selections for App Services (we will enable “Push Notifications” later in this article):

  1. Select “Register”, then “Done” to complete creation of your new iOS App Bundle ID. 

Obtain Authenticator source, prepare a project and open in Xcode

Note

To clone the source code with a SSH URL, you must have created a SSH key and added it to your Bitbucket profile.

  1. Git clone the ForgeRock Authenticator iOS repository:
    $ git clone ssh://git@stash.forgerock.org:7999/openam/forgerock-authenticator-ios.git
  2. Install CocoaPods. See CocoaPods - Getting Started for further information.
  3. Prepare the project to be opened in Xcode:
    1. Navigate to the project’s root directory on the command line and download the project’s dependencies:
      $ cd forgerock-authenticator-ios
      $ pod install
      
    2. Open the project in Xcode:
      $ open ForgeRock.xcworkspace/
  4. Select the “ForgeRock” folder from the “Project Navigator View” in Xcode to view the app’s configuration in the main Xcode view.
  5. Update the App Identity settings:
    1. Bundle identifier, this should be the same as set in step 5b in the previous section, for example “com.acme.authenticator”.
    2. Version, for example “1.0.0”.
    3. Build, for example “1”.
  6. Update the App Signing settings:
    1. Enable “Automatically manage signing”; this is enabled for the official ForgeRock app.
    2. Team, this should refer to your Apple developer account.
    3. Provisioning profile, you should have a provisioning profile.
    4. Signing certificate, you should have a signing certificate.

Before making further changes, now would be a good time to verify that you are able to run the code on a physical device as detailed in Launch the App on an iPhone.

Dependency versions

Downloading the project's dependencies captures the versions in the Podfile.lock file (located in the project's root directory). This ensures that the same versions will be downloaded if the pod install command is re-run.

To update to a newer version of a dependency, you can use a combination of pod outdated to identify dependencies that are outdated and pod update to update them. See CocoaPods install vs update documentation for further details. If you make changes to third-party dependencies, you must also update the LIBRARIES file.

Launch the App on an iPhone

  1. Connect an iPhone to the laptop running Xcode.
  2. Accept the dialog displayed on your iPhone asking if you would like to trust your computer. 
  3. Select your phone from the devices dropdown in the top-left of Xcode.
  4. Select the “Play” icon.

Rename the project

  1. Select the “ForgeRock” folder from the “Project Navigator View” in Xcode to view the app’s configuration in the main Xcode view.
  2. Select the "File inspector" on the right hand-side; the name of your project should be in there under "Identity and Type":

  1. Change the name of your project to a new name, for example to “ACME”.
  2. Review the contents that will be renamed by Xcode and select “Rename”:

See How do I completely rename an Xcode project (i.e. inclusive of folders)? for further information on these steps.

Rename the scheme

  1. Click on the scheme for your OLD product (in the top bar near the "Stop" icon), then select "Manage schemes":

  1. Click on the OLD name in the scheme to make it editable and change the name:

See How do I completely rename an Xcode project (i.e. inclusive of folders)? for further information on these steps. 

Update the CocoaPods configuration

  1. Close Xcode.
  2. Open the Podfile (located in the project's root directory) in a text editor and update as follows:
    • Rename the target “ForgeRock”, for example to “ACME”.
    • Rename the target “ForgeRockTests”, for example to “ACMETests”:

  1. Navigate to the project’s root directory on the command line and and run the pod install command again to apply the CocoaPods changes:
    $ cd [project_root_dir]
    $ pod install
  2. Remove the ForgeRock.xcworkspace directory (also in the project’s root directory):
    $ rm -rf ForgeRock.xcworkspace
  3. Open the updated project in Xcode:
    $ open ACME.xcworkspace/

 

Rename the ForgeRock-Authenticator directory

  1. Close Xcode.
  2. Rename the directory using Git in order to preserve the history:
    $ git mv ForgeRock-Authenticator ACME-Authenticator
  3. Re-open the project in Xcode:
    $ open ACME.xcworkspace/
  4. Dismiss any warnings regarding missing files.
  5. Select “Authenticator” from the “Project Navigator View” in Xcode; it should be shown in red.
  6. Navigate to the Utilities pane under "Identity and Type" where you will see the "Name" entry.
  7. Select the folder icon to show a new dialog and update the location:

Rename the Entitlements file

  1. Rename the ForgeRock.entitlements file (located in the project's root directory), for example to ACME.entitlements:

Update the Build settings and rebuild

  1. Select the project from the “Project Navigator View” in Xcode.
  2. Select “General”, scroll down to the “Linked Frameworks and Libraries” section and remove the “libPods-ForgeRock.a” entry:

  1. Select "Build Settings", followed by “Packaging” and update the “Info.plist File” path, for example to “ACME-Authenticator/ACME-Info.plist”:

  1. Navigate to "Signing" and update the following:
    1. “Code Signing Entitlements” path, for example to “ACME.entitlements”.
    2. “Prefix header”, for example to “ACME-Authenticator/ACME-Prefix.pch”:

  1. Rebuild the project:
    1. Command + Shift + K to clean.
    2. Command + B to build.

Before making further changes, now would be a good time to verify that you are able to run the code on a physical device as detailed in Launch the App on an iPhone.

Update the Test Build settings

  1. Select the project from the “Project Navigator View” in Xcode.
  2. Select the “ACMETests” target in the main view.
  3. Select "Build Settings", followed by “Bundle Loader” and update the following:
    1. “Debug” path, for example to “$(BUILT_PRODUCTS_DIR)/ACME.app/ACME”.
    2. “Release” path, for example to “$(BUILT_PRODUCTS_DIR)/ACME.app/ACME”:

  1. Select “Build Phases”, followed by “Link Binary with Libraries” and remove the “libPods-ForgeRockTests.a” entry:

Update the Splashscreen video

  1. Replace the splashvideo.mp4 file (located in the [project_root_dir]/ACME-Authenticator directory) with the updated video file. Keeping the same filename means you do not have to update other project files.

Update App Permission Request dialogs

  1. Replace references to ForgeRock within the ACME-Info.plist file (located in the [project_root_dir]/ACME-Authenticator directory). For example, change them to ACME:

Update Localizable.strings

  1. Replace references to ForgeRock within the Localizable.strings file (located in the [project_root_dir]/ACME-Authenticator/en.lproj directory). For example, change them to ACME:

Update About.strings

  1. Replace relevant references to ForgeRock within the About.strings (located in the [project_root_dir]/ACME-Authenticator/Settings.bundle/en.lproj directory). For example, change them to ACME:

Note

ForgeRock and other copyright attributions should not be changed.

Update the App icon

  1. Generate a new set of icon files and a Contents.json file. These can be generated from a single source image using an online service such as https://appicon.co/.
  2. Replace the contents of the [project_root_dir]/ACME-Authenticator/Images.xcassets/AppIcon.appiconset/ directory with the set of icon files and a Contents.json file:

 

Update the Default Account icon

  1. Replace the forgerock-logo.png file (located in the [project_root_dir]/ACME-Authenticator directory) with an updated icon. If you want to change the name of this file, for example to acme-logo.png, then you must also update the references to it in the following files (using a text editor to find and replace is likely the easiest approach):
    • FRAUIUtils.m (located in the [project_root_dir]/ACME-Authenticator directory).
    • Main.storyboard (located in the [project_root_dir]/ACME-Authenticator directory)
    • project.pbxproj (located in the [project_root_dir]/ACME.xcodeproj directory):

Optional

You can delete the following files (located in the [project_root_dir]/ACME-Authenticator directory) from Xcode and the file system if you want as they are not used:

  • forgerock-logo-text.png 
  • forgerock-logo-opaque.png 

Update the Default colors

  1. Update colors in the following files (located in the [project_root_dir]/ACME-Authenticator directory); colors to update are specified in brackets:
    • FRANotificationsTableViewController.m (seaGreen and dashboardRed)
    • FRACircleProgressView.m (lightGrey)
    • FRAOathMechanismTableViewCellController.m (seaGreen and dashboardRed)
  2. Update colors and layout defined in the Main.storyboard file (located in the [project_root_dir]/ACME-Authenticator directory) if necessary.
Note

Any changes made to the Main.storyboard file will result in merge conflicts when rebasing over later changes to the official app; ForgeRock's development approach allows edits to this file by only one developer at a time.

Publish your App

Once you have completed all your changes and rebuilt the app, you can submit your app to the Apple App Store. The following links provide useful Apple resources on the next steps:

Set up Push notifications

Refer to the following articles for further information on setting up Push notifications:

See Also

FAQ: Source code in AM/OpenAM

Xcode Help

CocoaPods Guides


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

This content has been optimized for printing.

Loading...