Ping Advanced Identity Software

UI customization

In an Advanced Identity Software deployment, the Platform admin UI is the primary interface for administering PingAM and PingIDM. PingAM has its own standalone admin UI to access advanced configuration options.

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 journeys (trees) that integrate with PingIDM for user self-service operations.

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

UI Component Characteristics

Admin UI

  • Provides quick access to the configuration capabilities that administrators need every day.

  • Integrates PingIDM administration natively, so you manage PingIDM from the Platform admin UI without switching to a separate UI.

  • Links to the AM admin UI for additional PingAM configuration operations.

  • Replaces the PingIDM admin UI in an Advanced Identity Software deployment.

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

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.

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