Ping Advanced Identity Software

UI customization

In version 8 of Ping Advanced Identity Software, the PingAM and PingIDM component products continue to provide their own, separate UIs, so you can deploy one independently of the other.

When you use PingAM and PingIDM together in an Advanced Identity Software configuration:

  • PingAM centralizes authentication and authorization services for Advanced Identity Software deployments.

    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 admin UI, which calls PingAM trees that integrate with PingIDM for user self-service operations.

New Platform admin UI components replace functions of the PingAM and PingIDM native UIs:

Platform admin UI UI Characteristics

Admin UI

  • Provides quick access to the configuration capabilities that 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 an Advanced Identity Software 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 an Advanced Identity Software 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 an Advanced Identity Software 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 Advanced Identity Software Enduser and Login UIs:

  1. Clone the Platform UI repository.

  2. Carefully review the README.

  3. Develop your customizations.

  4. For each UI that you customize, adjust the variables found in the .env.production file to match your production deployment.

  5. Build the customized UIs.

    You’ll find the resulting single-page application files in the dist/ folder of each UI.

  6. Deploy the files in your environment.

    For details, keep reading.

End User UI customization

The Advanced Identity Software End User UI replaces the PingIDM end-user UI in an Advanced Identity Software 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 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.

Login UI customization

The Advanced Identity Software Login UI replaces the PingAM login UI (XUI) in an Advanced Identity Software 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’s 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 Login UI for resource owner authentication operations.

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

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 Advanced Identity Software Login UI:

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.

  1. Expand the PingAM .war.

  2. Move the XUI files:

    mv am/XUI am/OAuth2_XUI

  3. 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