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

Preface

This guide covers concepts, configuration, and usage procedures for customizing the ForgeRock Access Management user interface.

This guide is written for anyone wanting to apply their own look and feel to the end-user facing pages provided by Access Management.

About ForgeRock Identity Platform™ Software

ForgeRock Identity Platform™ is the only offering for access management, identity management, user-managed access, directory services, and an identity gateway, designed and built as a single, unified platform.

The platform includes the following components that extend what is available in open source projects to provide fully featured, enterprise-ready software:

  • ForgeRock Access Management (AM)

  • ForgeRock Identity Management (IDM)

  • ForgeRock Directory Services (DS)

  • ForgeRock Identity Gateway (IG)

  • ForgeRock Identity Message Broker (IMB)

Chapter 1. Introducing the User Interface

When you deploy AM to protect your web-based applications, users can be redirected to AM pages for login and logout.

The end user pages have ForgeRock styling and branding by default. You likely want to change at least the images to reflect your organization. You might want different customizations for different realms. This chapter addresses how to get started customizing AM end user pages for your organizations and supported locales.

You may want to change the default styling and branding as well as customize different realms.

While customizing the UI, you can set the advanced server property, org.forgerock.openam.core.resource.lookup.cache.enabled, to false to allow AM immediately to pick up changes to the files as you customize them. This includes the XML callback files for authentication modules used by the XUI.

You can set advanced server properties in the AM console under Deployment > Servers > Server Name > Advanced. Before using AM in production, set org.forgerock.openam.core.resource.lookup.cache.enabled back to the default setting, true.

Chapter 2. Customizing the User Interface

This chapter covers customizing the default user interface, known as the XUI.

Note

Any customizations made to the XUI need to be reapplied when redeploying an AM instance.

2.1. Theming the XUI

This section explains how to 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.

Only user-facing XUI pages support themes. The AM administration console cannot be themed.

You can apply themes to specific realms, and also to specific authentication chains within those realms. AM includes a default theme, and an inverted dark theme.

Procedure 2.1. To Apply a Theme to the XUI

This procedure demonstrates adding a custom Bootstrap theme to the XUI.

  1. Copy your custom Bootstrap theme to a directory in /path/to/tomcat/webapps/openam/XUI/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: /path/to/tomcat/webapps/openam/XUI/themes/dark/.

  2. Edit the /XUI/config/ThemeConfiguration.[hash].js file, where [hash] is an alphanumeric value generated each time the XUI is rebuilt, to reference the CSS files in the theme, and to map the theme to realms and authentication chains:

    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/dark/css/bootstrap.min.css",
                      "themes/dark/css/theme-dark.css",
                      "css/structure.css"
                  ]
              }
          },
          mappings: [ ... ]
      };

      Note that you must specify paths relative to the XUI 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 Section 3.2, "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) Optionally, 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) Optionally, create an authenticationChains array, and include the authentication chains the theme will apply to when used:

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

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

  3. Save your work.

    The next time a user logs in to the XUI they will see the new theme applied:

    Figure 2.1. XUI with the Dark Theme
    XUI with the dark theme applied.

2.2. Customizing the XUI Layout

This section explains how to alter the layout of user-facing XUI pages as well as how to rebuild and redeploy them.

To customize the layout and functionality of the XUI you must rebuild and deploy the XUI project. To alter styles, see Section 2.1, "Theming the XUI".

The build process for XUI uses the Webpack resource bundler to manage dependencies, optimize deliverables, and package the output.

Tip

For information on building the XUI as part of a Maven workflow for deployment inside a WAR file, see How do I customize the XUI using source code in AM (All versions) and OpenAM 12.x, 13.x? in the ForgeRock Knowledge Base.

ForgeRock provides the source code for the XUI as a Maven project located in the am-external repository.

The Maven project for the XUI contains a package.json configuration file, which specifies the available commands for building and testing the XUI. The following commands are available:

yarn build

Performs a one-time production-ready build of the XUI. Outputs to the build directory.

yarn test

Compiles and executes XUI unit tests in the src/test directory, and continuously watches for source changes to trigger re-testing.

Run this command in a separate terminal window when developing to continuously run unit tests against the code.

yarn profile

Performs a one-time build of the XUI, in production mode, with profiling enabled.

Generates a report in the build directory named report.html detailing the structure of the bundles and chunks that are created as part of a production build.

yarn start

Starts the XUI in development mode, with automatic rebuilds and reloads enabled.

The start script launches a dedicated Webpack development server to serve the XUI during development. For more information, see Procedure 2.3, "To Test XUI Pages in a Development Server".

The package.json file also lists the dependencies the XUI uses, and the required versions. Dependencies are locked to specific versions, for example, "lodash": "4.1.0" specifies an explicit version without using ^ or ~ characters.

After making changes to the XUI, such as editing the JavaScript or templates, you must rebuild the project, as follows:

Procedure 2.2. To Rebuild the XUI

Perform the following steps to get the source and rebuild the XUI:

  1. To download the project containing the XUI from the am-external repository:

    1. If you do not already have a ForgeRock BackStage account, get one from https://backstage.forgerock.com. You cannot clone the am-external repository without a BackStage account.

      The BackStage account used must be added to a subscription. For more information, see Getting access to product support in the ForgeRock Knowledge Base.

    2. Clone the am-external repository:

      $ git clone https://myBackStageID@stash.forgerock.org/scm/openam/am-external.git

      Tip

      URL encode your BackStage ID if it contains special characters. For example : becomes %3A and @ becomes %40.

      Enter your BackStage password when prompted to do so.

    3. Check out the release/6.0.0 branch:

      $ cd am-external
      $ git checkout releases/6.0.0

      The XUI project is located in the am-external/openam-ui/openam-ui-ria/ folder.

  2. If you do not already have them, install the following prerequisites:

  3. Use the yarn command to download the dependencies to the project:

    $ yarn
    yarn install v1.5.1
    [1/4] 🔍 Resolving packages...
    [2/4] 🚚 Fetching packages...
    [3/4] 🔗 Linking dependencies...
    [4/4] 📃 Building fresh packages...
    ✨ Done in 9.08s.
  4. Make any changes to the XUI as required.

    The JavaScript source code is available in src/main/js/. Fonts, images, partials, and other resources are provided in src/main/resources/.

  5. Rebuild the project using the yarn build.

    For information on testing the XUI pages before deploying them to an instance, see Procedure 2.3, "To Test XUI Pages in a Development Server".

  6. Deploy the output in the build directory to the /path/to /tomcat/webapps/openam/XUI/ directory in your Access Management instances.

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

Procedure 2.3. To Test XUI Pages in a Development Server

You can run the XUI project on a dedicated development server for testing customizations. The XUI in the development server connects to a separate instance of AM running on a different port, but using the same base domain. Any HTTP requests the XUI makes out to AM are proxied to port 8080, by default.

Tip

You can override the default setting for the the port AM is running on by using an OPENAM_PORT environment variable.

By separating the XUI from the core AM server, the XUI behaves as it would in production, except with the addition of development tooling, such as automatic browser refreshes when XUI code is changed.

To run the XUI on a development server:

  1. Configure and start an AM instance. For example, http://openam.example.com:8080/openam.

  2. Start an XUI development server by using the yarn start command.

    The development server starts on this first available port counting up from port 8080, which is usually port 8081. Ensure you can access the development server using the same domain as the AM instance, for examplehttp://xui.example.com:8081.

  3. In a web browser, navigate to the full URL of your AM instance, but use the port number of the XUI development server.

    For example, navigate to http://openam.example.com:8081/openam/XUI/#login.

    Changes made to the XUI project are rebuilt and redeployed to the development server automatically, and the browser refreshed to show the changes, or any errors that have occurred.

    Note

    The XUI development server assumes the AM instaces has a deployment URI of /openam. The deployment URI and port numbers can be edited in the config/webpack/development.js file in the XUI project.

2.3. Localizing the XUI

This section explains how to localize the text that is generated for the user-facing XUI pages.

The text the XUI displays comes from from translation.json files located in locale-specific directories.

To customize the English text, edit /path/to/tomcat/webapps/openam/XUI/locales/en/translation.json under the directory where AM is deployed.

To prepare a translation for a new locale, copy the provided /path/to/tomcat/webapps/openam/XUI/locales/en directory to /path/to/tomcat/webapps/openam/XUI/locales/locale, and edit the duplicate by changing the values, and taking care not to change the JSON structure or to render it invalid.

The locale should be specified as per rfc5646 - Tags for Identifying Languages. For example, en-GB.

Chapter 3. Reference

This reference chapter covers the languages and locales supported by AM, as well as configuration parameters for AM's user interface, named the XUI.

3.1. Localization

This section lists languages and locales supported by AM.

The XUI interface pages are localized for the following languages:

  • English

You can localize the XUI for other languages as you require. For more information, see Section 2.3, "Localizing the XUI".

3.2. XUI Configuration Parameters

The configuration of the XUI is based on settings in the ThemeConfiguration.[hash].js file, where [hash] is an alphanumeric value generated each time the XUI is rebuilt, to help resolve caching issues.

This file is found in the /path/to/webapps/openam/XUI/config/ directory. The file contains a full configuration for the mandatory default theme. Additional themes should use a duplicate of the default theme's configuration. Any parameters that are not configured will inherit values from the mandatory default theme.

The available parameters for each theme in the file are as follows:

  • themes: Title; also represents an array of theme objects.

    • name: Theme title.

      • stylesheets: An ordered array of URLs to CSS stylesheet files that are applied to every page. It is highly recommended to include the variable StructureStyle as one of the entries to provide default styles for layout and structure.

        For example: ["themes/dark/css/bootstrap.min.css", StructureStyle, "themes/dark/css/theme-dark.css"]

      • path: A relative path to a directory containing templates or partials directories, used for customizing the default layout of XUI pages.

        For more information, see Section 2.2, "Customizing the XUI Layout".

      • icon: URL to a resource to use as a favicon.

      • settings: Configuration settings for the theme. Missing parameters inherit their value from the mandatory default theme.

        • logo: Parameters for the logo displayed on user profile pages.

          • src: Filename of the logo.

          • title: HTML title attribute of the logo.

          • alt: HTML alt attribute of the logo.

          • height: Logo height in CSS notation. For example: 75px or 10%.

          • width: Logo width in CSS notation. For example: 150px or 25%.

        • loginLogo: Parameters for the logo displayed on login pages.

          • src: Filename of the logo.

          • title: HTML title attribute of the logo.

          • alt: HTML alt attribute of the logo.

          • height: Logo height in CSS notation. For example: 75px or 10%.

          • width: Logo width in CSS notation. For example: 150px or 25%.

        • footer: Parameters to display in the footer of each XUI page.

          • mailto: Email address.

          • phone: Telephone number.

For more information, see Section 2.1, "Theming the XUI".

Appendix A. Getting Support

For more information or resources about AM and ForgeRock Support, see the following sections:

A.1. Accessing Documentation Online

ForgeRock publishes comprehensive documentation online:

  • The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.

    While many articles are visible to community members, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.

  • ForgeRock product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.

A.2. Using the ForgeRock.org Site

The ForgeRock.org site has links to source code for ForgeRock open source software, as well as links to the ForgeRock forums and technical blogs.

If you are a ForgeRock customer, raise a support ticket instead of using the forums. ForgeRock support professionals will get in touch to help you.

A.3. Getting Support and Contacting ForgeRock

ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.forgerock.com.

ForgeRock has staff members around the globe who support our international customers and partners. For details, visit https://www.forgerock.com, or send an email to ForgeRock at info@forgerock.com.

Glossary

Access control

Control to grant or to deny access to a resource.

Account lockout

The act of making an account temporarily or permanently inactive after successive authentication failures.

Actions

Defined as part of policies, these verbs indicate what authorized identities can do to resources.

Advice

In the context of a policy decision denying access, a hint to the policy enforcement point about remedial action to take that could result in a decision allowing access.

Agent administrator

User having privileges only to read and write agent profile configuration information, typically created to delegate agent profile creation to the user installing a web or Java agent.

Agent authenticator

Entity with read-only access to multiple agent profiles defined in the same realm; allows an agent to read web service profiles.

Application

In general terms, a service exposing protected resources.

In the context of AM policies, the application is a template that constrains the policies that govern access to protected resources. An application can have zero or more policies.

Application type

Application types act as templates for creating policy applications.

Application types define a preset list of actions and functional logic, such as policy lookup and resource comparator logic.

Application types also define the internal normalization, indexing logic, and comparator logic for applications.

Attribute-based access control (ABAC)

Access control that is based on attributes of a user, such as how old a user is or whether the user is a paying customer.

Authentication

The act of confirming the identity of a principal.

Authentication chaining

A series of authentication modules configured together which a principal must negotiate as configured in order to authenticate successfully.

Authentication level

Positive integer associated with an authentication module, usually used to require success with more stringent authentication measures when requesting resources requiring special protection.

Authentication module

AM authentication unit that handles one way of obtaining and verifying credentials.

Authorization

The act of determining whether to grant or to deny a principal access to a resource.

Authorization Server

In OAuth 2.0, issues access tokens to the client after authenticating a resource owner and confirming that the owner authorizes the client to access the protected resource. AM can play this role in the OAuth 2.0 authorization framework.

Auto-federation

Arrangement to federate a principal's identity automatically based on a common attribute value shared across the principal's profiles at different providers.

Bulk federation

Batch job permanently federating user profiles between a service provider and an identity provider based on a list of matched user identifiers that exist on both providers.

Circle of trust

Group of providers, including at least one identity provider, who have agreed to trust each other to participate in a SAML v2.0 provider federation.

Client

In OAuth 2.0, requests protected web resources on behalf of the resource owner given the owner's authorization. AM can play this role in the OAuth 2.0 authorization framework.

Client-based sessions

AM sessions for which AM returns session state to the client after each request, and require it to be passed in with the subsequent request. For browser-based clients, AM sets a cookie in the browser that contains the session information.

For browser-based clients, AM sets a cookie in the browser that contains the session state. When the browser transmits the cookie back to AM, AM decodes the session state from the cookie.

Conditions

Defined as part of policies, these determine the circumstances under which which a policy applies.

Environmental conditions reflect circumstances like the client IP address, time of day, how the subject authenticated, or the authentication level achieved.

Subject conditions reflect characteristics of the subject like whether the subject authenticated, the identity of the subject, or claims in the subject's JWT.

Configuration datastore

LDAP directory service holding AM configuration data.

Cross-domain single sign-on (CDSSO)

AM capability allowing single sign-on across different DNS domains.

CTS-based sessions

AM sessions that reside in the Core Token Service's token store. CTS-based sessions might also be cached in memory on one or more AM servers. AM tracks these sessions in order to handle events like logout and timeout, to permit session constraints, and to notify applications involved in SSO when a session ends.

Delegation

Granting users administrative privileges with AM.

Entitlement

Decision that defines which resource names can and cannot be accessed for a given identity in the context of a particular application, which actions are allowed and which are denied, and any related advice and attributes.

Extended metadata

Federation configuration information specific to AM.

Extensible Access Control Markup Language (XACML)

Standard, XML-based access control policy language, including a processing model for making authorization decisions based on policies.

Federation

Standardized means for aggregating identities, sharing authentication and authorization data information between trusted providers, and allowing principals to access services across different providers without authenticating repeatedly.

Fedlet

Service provider application capable of participating in a circle of trust and allowing federation without installing all of AM on the service provider side; AM lets you create Java Fedlets.

Hot swappable

Refers to configuration properties for which changes can take effect without restarting the container where AM runs.

Identity

Set of data that uniquely describes a person or a thing such as a device or an application.

Identity federation

Linking of a principal's identity across multiple providers.

Identity provider (IdP)

Entity that produces assertions about a principal (such as how and when a principal authenticated, or that the principal's profile has a specified attribute value).

Identity repository

Data store holding user profiles and group information; different identity repositories can be defined for different realms.

Java agent

Java web application installed in a web container that acts as a policy enforcement point, filtering requests to other applications in the container with policies based on application resource URLs.

Metadata

Federation configuration information for a provider.

Policy

Set of rules that define who is granted access to a protected resource when, how, and under what conditions.

Policy agent

Java, web, or custom agent that intercepts requests for resources, directs principals to AM for authentication, and enforces policy decisions from AM.

Policy Administration Point (PAP)

Entity that manages and stores policy definitions.

Policy Decision Point (PDP)

Entity that evaluates access rights and then issues authorization decisions.

Policy Enforcement Point (PEP)

Entity that intercepts a request for a resource and then enforces policy decisions from a PDP.

Policy Information Point (PIP)

Entity that provides extra information, such as user profile attributes that a PDP needs in order to make a decision.

Principal

Represents an entity that has been authenticated (such as a user, a device, or an application), and thus is distinguished from other entities.

When a Subject successfully authenticates, AM associates the Subject with the Principal.

Privilege

In the context of delegated administration, a set of administrative tasks that can be performed by specified identities in a given realm.

Provider federation

Agreement among providers to participate in a circle of trust.

Realm

AM unit for organizing configuration and identity information.

Realms can be used for example when different parts of an organization have different applications and user data stores, and when different organizations use the same AM deployment.

Administrators can delegate realm administration. The administrator assigns administrative privileges to users, allowing them to perform administrative tasks within the realm.

Resource

Something a user can access over the network such as a web page.

Defined as part of policies, these can include wildcards in order to match multiple actual resources.

Resource owner

In OAuth 2.0, entity who can authorize access to protected web resources, such as an end user.

Resource server

In OAuth 2.0, server hosting protected web resources, capable of handling access tokens to respond to requests for such resources.

Response attributes

Defined as part of policies, these allow AM to return additional information in the form of "attributes" with the response to a policy decision.

Role based access control (RBAC)

Access control that is based on whether a user has been granted a set of permissions (a role).

Security Assertion Markup Language (SAML)

Standard, XML-based language for exchanging authentication and authorization data between identity providers and service providers.

Service provider (SP)

Entity that consumes assertions about a principal (and provides a service that the principal is trying to access).

Authentication Session

The interval while the user or entity is authenticating to AM.

Session

The interval that starts after the user has authenticated and ends when the user logs out, or when their session is terminated. For browser-based clients, AM manages user sessions across one or more applications by setting a session cookie. See also CTS-based sessions and Client-based sessions.

Session high availability

Capability that lets any AM server in a clustered deployment access shared, persistent information about users' sessions from the CTS token store. The user does not need to log in again unless the entire deployment goes down.

Session token

Unique identifier issued by AM after successful authentication. For a CTS-based sessions, the session token is used to track a principal's session.

Single log out (SLO)

Capability allowing a principal to end a session once, thereby ending her session across multiple applications.

Single sign-on (SSO)

Capability allowing a principal to authenticate once and gain access to multiple applications without authenticating again.

Site

Group of AM servers configured the same way, accessed through a load balancer layer. The load balancer handles failover to provide service-level availability.

The load balancer can also be used to protect AM services.

Standard metadata

Standard federation configuration information that you can share with other access management software.

Stateless Service

Stateless services do not store any data locally to the service. When the service requires data to perform any action, it requests it from a data store. For example, a stateless authentication service stores session state for logged-in users in a database. This way, any server in the deployment can recover the session from the database and service requests for any user.

All AM services are stateless unless otherwise specified. See also Client-based sessions and CTS-based sessions.

Subject

Entity that requests access to a resource

When an identity successfully authenticates, AM associates the identity with the Principal that distinguishes it from other identities. An identity can be associated with multiple principals.

User data store

Data storage service holding principals' profiles; underlying storage can be an LDAP directory service, a relational database, or a custom IdRepo implementation.

Web Agent

Native library installed in a web server that acts as a policy enforcement point with policies based on web page URLs.

Read a different version of :