UI customization

In version 7 of ForgeRock Identity Platform, the AM and IDM component products continue to provide their own, separate UIs, so you can deploy one independently of the other. Version 7 changes the model for deploying AM and IDM together in a ForgeRock Identity Platform configuration. Key changes to the platform deployment model concern OAuth 2.0 and platform UIs.

When you use AM and IDM together in a ForgeRock Identity Platform configuration:

AM centralizes authentication and authorization services for the platform.

IDM acts as an OAuth 2.0 client of AM. Even when you log in to administer IDM, you authenticate through AM.

More generally, all new client applications are expected to obtain an access token from AM, and present it to IDM for authorization; for example, when calling IDM REST endpoints.

This is why the authentication configuration for IDM includes an rsFilter (OAuth 2.0 resource server) configuration.
IDM centralizes identity management services.

IDM relies on the platform UI, which calls AM trees that integrate with IDM for user self-service operations.

New platform UI components replace functions of the AM and IDM native UIs:

Platform UI	Characteristics
Admin UI	Provides quick access to the configuration capabilities that platform administrators need every day. Links to the AM admin UI and IDM admin UI for additional, less common configuration operations. Cannot be customized, though you can write your own. Runs as an administrator-facing service that you run in front of a platform deployment. Operates as an OAuth 2.0 client of AM. Uses the self-service tree endpoints to configure authentication trees, as described in Configure self-service trees endpoints, and documented in the AM API explorer, which you can access through the AM admin UI. If you write your own admin UI, use these endpoints to manage tree configurations.
End User UI	Provides users with personalized pages to access their applications and update their profiles. Replaces the IDM end user UI in a platform deployment. Can be customized for your deployment. Runs separately as a single-page application. Operates as an OAuth 2.0 client of AM.
Login UI	Replaces the AM login UI (XUI) in a platform deployment. Can be customized for your deployment. Runs separately as a single-page application. Operates as a native AM client, not an OAuth 2.0 client.

Platform UI

Characteristics

Admin UI

Provides quick access to the configuration capabilities that platform administrators need every day.
Links to the AM admin UI and IDM admin UI for additional, less common configuration operations.
Cannot be customized, though you can write your own.
Runs as an administrator-facing service that you run in front of a platform deployment.
Operates as an OAuth 2.0 client of AM.
Uses the self-service tree endpoints to configure authentication trees, as described in Configure self-service trees endpoints, and documented in the AM API explorer, which you can access through the AM admin UI. If you write your own admin UI, use these endpoints to manage tree configurations.

End User UI

Provides users with personalized pages to access their applications and update their profiles.
Replaces the IDM end user UI in a platform deployment.
Can be customized for your deployment.
Runs separately as a single-page application.
Operates as an OAuth 2.0 client of AM.

Replaces the AM login UI (XUI) in a platform deployment.
Can be customized for your deployment.
Runs separately as a single-page application.
Operates as a native AM client, not an OAuth 2.0 client.

High-level instructions for customizing the platform Enduser and Login UIs:

Clone the platform UI repository.
Carefully review the README.
Develop your customizations.
For each UI that you customize, adjust the variables found in the .env.production file to match your production deployment.
Build the customized UIs.

You will find the resulting single-page application files in the dist/ folder of each UI.
Deploy the files in your environment.

For details, keep reading.

End User UI customization

The platform End User UI replaces the IDM end user UI in a platform deployment. IDM still includes the end user UI files, as they are useful in standalone deployments.

Choose how to deploy your customized version of the platform End User UI:

Deploy your customized End User UI in a separate web server.

In the AM OAuth 2.0 client profile for the End User UI, set the redirection URIs to reflect the URL to your End User UI.

This approach is reflected in the sample deployments in this documentation.
Copy the contents of the dist/* folder of your customized end user UI over the files in the expanded IDM ui/enduser folder, overwriting existing files.

The End User UI is then in the same domain as IDM.

If you use a path that is different from ui/enduser for the files, also update the conf/ui.context-enduser.json configuration to match.

The platform Login UI replaces the AM login UI (XUI) in a platform deployment. AM still includes the login UI files, as they are useful in standalone deployments.

The Login UI operates as a native AM client, capable of working with authentication trees. It is not an OAuth 2.0 client, but instead a component used in OAuth 2.0 flows. AM, acting as an OAuth 2.0 authorization server, relies on the platform Login UI for resource owner authentication operations.

The Login UI leverages the AM authentication trees that are compatible with ForgeRock Identity Platform, as described in the self-service documentation. The Login UI translates the AM /json/authenticate challenges into web pages for users, and translates user responses back into REST calls.

Choose how to deploy your customized version of the platform Login UI:

If you… How to deploy

If you…	How to deploy
Use only OAuth 2.0 clients of AM, not others such as SAML or same-domain policy agents.	Deploy your customized login UI in a separate web server. In AM admin UI, for each realm, browse to Authentication > Settings, and click the General tab. Set the External Login Page URL value to the URL of your customized Login UI. If necessary, update the AM CORS and Validation Service configurations. This approach is reflected in the sample deployments in this documentation.
Customize the AM .war file for your deployment.	Copy the contents of the `dist/*` folder of your customized Login UI over the files in the expanded AM `webapps/am/XUI` folder, overwriting XUI files.
Run AM behind a reverse proxy.	Deploy your customized Login UI `dist/*` files in a separate web server, and use the reverse proxy to direct requests for AM XUI to your customized Login UI instead. A few of the JavaScript files from the AM XUI serve to properly render OAuth 2.0 UI screens. Therefore, in addition, customize the AM .war file to move AM XUI files, and specify that location when starting AM. Expand the AM .war. Move the XUI files: `mv am/XUI am/OAuth2_XUI` Update runtime options so that they specify the location of the XUI files when AM starts. For example, if you run in Tomcat as described above, add this option alongside the others in the `setenv.sh` script: -Dorg.forgerock.am.oauth2.consent.xui_path=/OAuth2_XUI

Use only OAuth 2.0 clients of AM, not others such as SAML or same-domain policy agents.

Deploy your customized login UI in a separate web server.

In AM admin UI, for each realm, browse to Authentication > Settings, and click the General tab. Set the External Login Page URL value to the URL of your customized Login UI.

If necessary, update the AM CORS and Validation Service configurations.

This approach is reflected in the sample deployments in this documentation.

Customize the AM .war file for your deployment.

Copy the contents of the dist/* folder of your customized Login UI over the files in the expanded AM webapps/am/XUI folder, overwriting XUI files.

Run AM behind a reverse proxy.

Deploy your customized Login UI dist/* files in a separate web server, and use the reverse proxy to direct requests for AM XUI to your customized Login UI instead.

A few of the JavaScript files from the AM XUI serve to properly render OAuth 2.0 UI screens. Therefore, in addition, customize the AM .war file to move AM XUI files, and specify that location when starting AM.

Expand the AM .war.
Move the XUI files:
```
mv am/XUI am/OAuth2_XUI
```
Update runtime options so that they specify the location of the XUI files when AM starts.

For example, if you run in Tomcat as described above, add this option alongside the others in the setenv.sh script:
```
-Dorg.forgerock.am.oauth2.consent.xui_path=/OAuth2_XUI
```

ForgeRock Identity Platform 7.3

UI customization

End User UI customization

Login UI customization