Ping Advanced Identity Software

Set up the Platform UIs

This is not a comprehensive Advanced Identity Software implementation guide. These sample setup instructions show a minimal integration of Advanced Identity Software components to get you started.

Ping Advanced Identity Software offers maximum extensibility and flexibility in self-managed deployments. Advanced Identity Software includes many features and options these sample setup instructions do not cover. If you don’t need maximum extensibility and flexibility, there are simpler alternatives:

For help with your deployment and to validate your plans before deploying in production, contact Ping Identity.

This page describes two ways to set up the UIs for the sample deployments. Either deploy the Platform UI by running Docker images or by installing a .zip file. Do not attempt to deploy the UI both ways:

The Platform UIs

Ping Advanced Identity Software includes three UIs:

Admin UI

Lets Advanced Identity Software administrators manage applications, identities, end-user journeys, and so on.

End User UI

An example UI that demonstrates profile maintenance, consent management, workflow, and delegated administration capabilities. This UI makes REST calls to PingIDM (using an OAuth 2 bearer token) and to PingAM (using an SSO cookie).

Login UI

A unified Login UI that lets both administrators and end users log in to Advanced Identity Software.

Run Docker images

If you have already deployed the Platform UI by installing a .zip file, do not perform these steps.

In this sample deployment, the three UIs are deployed from three Docker images.

  1. Download the Docker images:

    • Download the Admin UI:

      docker pull gcr.io/forgerock-io/platform-admin-ui:8.0.1

    • Download the End User UI:

      docker pull gcr.io/forgerock-io/platform-enduser-ui:8.0.1

    • Download the Login UI:

      docker pull gcr.io/forgerock-io/platform-login-ui:8.0.1

  2. Create an environment file named platform_env that will be passed to the docker command.

    The file should have the following contents:

    AM_URL=https://platform.example.com:9443/am
AM_ADMIN_URL=https://platform.example.com:9443/am/ui-admin
IDM_REST_URL=https://platform.example.com:9443/openidm
IDM_ADMIN_URL=https://platform.example.com:9443/admin
IDM_UPLOAD_URL=https://platform.example.com:9443/upload
IDM_EXPORT_URL=https://platform.example.com:9443/export
ENDUSER_UI_URL=https://platform.example.com:9443/enduser-ui/
PLATFORM_ADMIN_URL=https://platform.example.com:9443/platform-ui/
ENDUSER_CLIENT_ID=end-user-ui
ADMIN_CLIENT_ID=idm-admin-ui
THEME=default
PLATFORM_UI_LOCALE=en

    When you deploy multiple Platform UI Docker containers with the same hostname, use the SUBFOLDER environment variable to prefix a base URL path for each UI.

    For example, if you deploy all the UIs on ui.example.com, use the following settings to make the End User UI accessible under /enduser:

    In the End User UI configuration, set:

    SUBFOLDER=enduser

    In all Platform UI environments, set:

    ENDUSER_UI_URL=http://ui.example.com:8888/enduser

    Adapt your configuration to account for the path changes.

  3. Start each Docker container, specifying the environment file:

    • Change to the directory in which you saved the platform_env file, then start the Login UI:

      docker run -t -i --rm -p 8083:8080 --env-file=platform_env \
gcr.io/forgerock-io/platform-login-ui:8.0.1
Replacing env vars in JS

Setting AM URL as https://platform.example.com:9443/am
Setting AM ADMIN URL as https://platform.example.com:9443/am/ui-admin
Setting IDM REST URL as https://platform.example.com:9443/openidm
Setting IDM ADMIN URL as https://platform.example.com:9443/admin
...
      The --rm option causes the docker run command to remove the container on exit. Remove this option if you want to keep a container when it exits.

    • In a new terminal, change to the directory in which you saved the platform_env file, then start the Admin UI:

      docker run -t -i --rm -p 8082:8080 --env-file=platform_env \
gcr.io/forgerock-io/platform-admin-ui:8.0.1
Replacing env vars in JS

Setting AM URL as https://platform.example.com:9443/am
Setting AM ADMIN URL as https://platform.example.com:9443/am/ui-admin
Setting IDM REST URL as https://platform.example.com:9443/openidm
Setting IDM ADMIN URL as https://platform.example.com:9443/admin
...

    • In a new terminal, change to the directory in which you saved the platform_env file, then start the End User UI:

      docker run -t -i --rm -p 8888:8080 --env-file=platform_env \
gcr.io/forgerock-io/platform-enduser-ui:8.0.1
Replacing env vars in JS

Setting AM URL as https://platform.example.com:9443/am
Setting AM ADMIN URL as https://platform.example.com:9443/am/ui-admin
Setting IDM REST URL as https://platform.example.com:9443/openidm
Setting IDM ADMIN URL as https://platform.example.com:9443/admin
...

Install a .zip file

If you have already deployed the Platform UI by running Docker images, don’t perform these steps.

In this sample deployment, you obtain the three UIs from a .zip file that you get from Ping Identity. Then, you install them in the PingAM web container. You also tweak the PingAM and PingIDM configurations so that they work with this UI installation.

  1. Get the UI .zip file, and unzip it into the tmp directory:

    1. Create the /tmp/ui-zip directory.

    2. Download the most recent version of the 8.x UI .zip file from the Platform section of the downloads site.

    3. Copy the UI .zip file into the /tmp/ui-zip directory.

    4. Unzip the UI .zip file.

  2. Replace URLs in the UI application with URLs for your Ping Advanced Identity Software deployment:

    1. Change to the /tmp/ui-zip/PlatformUI directory.

    2. Run the following commands:

      export AM_URL=https://platform.example.com:9443/am
export AM_ADMIN_URL=https://platform.example.com:9443/am/ui-admin
export IDM_REST_URL=https://platform.example.com:9443/openidm
export IDM_ADMIN_URL=https://platform.example.com:9443/admin
export IDM_UPLOAD_URL=https://platform.example.com:9443/upload
export IDM_EXPORT_URL=https://platform.example.com:9443/export
export ENDUSER_UI_URL=https://platform.example.com:9443/enduser-ui/
export PLATFORM_ADMIN_URL=https://platform.example.com:9443/platform-ui/
export ENDUSER_CLIENT_ID=end-user-ui
export ADMIN_CLIENT_ID=idm-admin-ui
export THEME=default
export PLATFORM_UI_LOCALE=en

    3. Run the variable_replacement.sh script.

      This script replaces variables in the .zip file’s UI web application with the values of the environment variables that you set in the previous step:

      ./variable_replacement.sh www/platform/js/*.js www/enduser/js/*.js www/login/js/*.js
Replacing env vars in JS

Setting AM URL as https://platform.example.com:9443/am
Setting AM ADMIN URL as https://platform.example.com:9443/am/ui-admin
Setting IDM REST URL as https://platform.example.com:9443/openidm
Setting IDM ADMIN URL as https://platform.example.com:9443/admin
...

  3. Install the UI:

    1. Install the platform and enduser web applications into PingAM’s web container:

      cd /path/to/tomcat/webapps
cp -r /tmp/ui-zip/PlatformUI/www/platform .
cp -r /tmp/ui-zip/PlatformUI/www/enduser .

    2. Modify PingAM to use the new Login UI:

      cd /path/to/tomcat/webapps/am/XUI
cp -r /tmp/ui-zip/PlatformUI/www/login/* .

  4. Change the PingGateway configuration to work with the new UI installation.

    Replace the following PingGateway route files with those for the .zip installation if you haven’t done so already:

  5. Revise the PingAM configuration to work with the new UI installation:

    1. Sign in to the AM admin UI as the amAdmin user.

    2. Clear the External Login Page URL value.

      In the alpha realm, select Authentication > Settings > General and clear External Login Page URL so it’s an empty string.

    3. Click Save Changes.

    4. Sign out of the AM admin UI.

Redirect on signout

When the test user signs out of the End User UI, the browser redirects to the PingAM XUI login page:

XUI login page

You can change this behavior to redirect to your application. Options for managing redirection on sign out include:

  • (Recommended) Use PingGateway, as described in Protect the deployment, with a route to redirect the browser from the XUI to your application.

    If you choose this option, skip the steps that follow.

  • Script a post_logout_url claim that PingAM returns to the End User UI through the user’s ID token. When the user signs out, the End User UI redirects the browser to the URL specified in the claim.

Follow these steps to configure a post_logout_url claim:

  1. If you’re not currently logged in to the AM admin UI as the amAdmin user, log in.

  2. Under Scripts, find the OIDC Claims Script, and click to view the script.

    This script lets you customize the OpenID Connect 1.0 claims in the user’s ID token.

  3. Add a post_logout_url claim method to the array of claimAttributes.

    The following Groovy example adds a final item to claimAttributes to return https://pingidentity.com as the post_logout_url claim. Adapt the method used to return the appropriate URL for your application:

    claimAttributes = [
        //...,
        "post_logout_url": { claim, identity -> return [(claim.getName()): "https://pingidentity.com"] }
]

  4. Add the claim for the fr:idm:* scope as a final item in the scopeClaimsMap:

    scopeClaimsMap = [
        //...,
        "fr:idm:*": [ "post_logout_url" ]
]

  5. Click Validate, correct any errors accidentally introduced, and then click Save Changes.

  6. Under Services > OAuth2 Provider, search for Always Return Claims in ID Tokens, then enable the option, and click Save Changes.

    PingAM can now return the custom claim in the user’s ID token.

  7. Test the changes you have made:

    1. Log out of the AM admin UI.

    2. Sign in as a test user at http://login.example.com:8083/?realm=/alpha#/service/PlatformLogin.

    3. Sign out.

      The End User UI redirects the browser to the URL you configured for the post_logout_url claim, in this case https://pingidentity.com.

Next step