UI customization

In version 7 of Ping Identity Platform, the PingAM and PingIDM 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 PingAM and PingIDM together in a Ping Identity Platform configuration. Key changes to the platform deployment model concern OAuth 2.0 and platform UIs.

When you use PingAM and PingIDM together in a Ping Identity Platform configuration:

PingAM centralizes authentication and authorization services for the platform.

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

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

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

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

New platform UI components replace functions of the PingAM and PingIDM 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 PingAM. Uses the self-service tree endpoints to configure authentication trees. You can find more information on these endpoints in the PingAM 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 PingIDM 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 PingAM.
Login UI	Replaces the PingAM login UI (XUI) in a platform deployment. Can be customized for your deployment. Runs separately as a single-page application. Operates as a native PingAM 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 PingAM.
Uses the self-service tree endpoints to configure authentication trees. You can find more information on these endpoints in

the PingAM 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 PingIDM 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 PingAM.

Replaces the PingAM login UI (XUI) in a platform deployment.
Can be customized for your deployment.
Runs separately as a single-page application.
Operates as a native PingAM 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 PingIDM end-user UI in a platform deployment. PingIDM 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 PingAM 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 PingIDM ui/enduser folder, overwriting existing files.

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

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 PingAM login UI (XUI) in a platform deployment. PingAM still includes the login UI files, as they are useful in standalone deployments.

The Login UI operates as a native PingAM 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. PingAM, acting as an OAuth 2.0 authorization server, relies on the platform Login UI for resource owner authentication operations.

The Login UI leverages the PingAM authentication trees that are compatible with Ping Identity Platform.

The Login UI translates the PingAM /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 PingAM, 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 PingAM CORS and Validation Service configurations. This approach is reflected in the sample deployments in this documentation.
Customize the PingAM .war file for your deployment.	Copy the contents of the `dist/*` folder of your customized Login UI over the files in the expanded PingAM `webapps/am/XUI` folder, overwriting XUI files.
Run PingAM 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 PingAM XUI to your customized Login UI instead. A few of the JavaScript files from the PingAM XUI serve to properly render OAuth 2.0 UI screens. Therefore, in addition, customize the PingAM .war file to move PingAM XUI files, and specify that location when starting PingAM. Expand the PingAM .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 PingAM 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 PingAM, 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 PingAM CORS and Validation Service configurations.

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

Customize the PingAM .war file for your deployment.

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

Run PingAM 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 PingAM XUI to your customized Login UI instead.

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

Expand the PingAM .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 PingAM 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
```

Ping Identity Platform

UI customization

End User UI customization

Login UI customization