--- title: Set up the Platform UIs description: 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. component: platform version: 8 page_id: platform:sample-setup:platform-ui canonical_url: https://docs.pingidentity.com/platform/8/sample-setup/platform-ui.html page_aliases: ["platform-setup-guide:platform-ui.adoc"] section_ids: the_platform_uis: The Platform UIs deploy-ui-docker: Run Docker images deploy-ui-zip: Install a .zip file post-logout-url: Redirect on signout next_step: Next step --- # 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:- To consume the Advanced Identity Software as a service, use [PingOne Advanced Identity Cloud](https://docs.pingidentity.com/pingoneaic). - To deploy in Kubernetes, start with the [ForgeOps](https://docs.pingidentity.com/forgeops/2025.1) reference implementation.For help with your deployment and to validate your plans before deploying in production, contact [Ping Identity](https://www.pingidentity.com). | 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: * [Run Docker images](#deploy-ui-docker) * [Install a `.zip` file in the PingAM web container](#deploy-ui-zip) ## 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: ```bash docker pull gcr.io/forgerock-io/platform-admin-ui:8.0.1 ``` * Download the End User UI: ```bash docker pull gcr.io/forgerock-io/platform-enduser-ui:8.0.1 ``` * Download the Login UI: ```bash 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: ```properties 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: ```bash 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: ```bash 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: ```bash 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](https://backstage.forgerock.com/downloads/browse/platform). 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: ```bash 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: ```bash ./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: ```bash 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: ```bash 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: * [enduser-ui.json](../_attachments/ig/config/routes/enduser-ui-zip-distro.json) * [login.json](../_attachments/ig/config/routes/login-zip-distro.json) * [platform-ui.json](../_attachments/ig/config/routes/platform-ui-zip-distro.json) 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](_images/xui-login-page.png) 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](protect-deployment.html), 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: ```groovy 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`: ```groovy 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 . 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 * [icon: check-square-o, set=fa][Choose your sample](overview.html) * [icon: check-square-o, set=fa][Prepare the servers](server-settings.html) * Separate identity stores * [icon: check-square-o, set=fa][Set up PingDS](deployment2.html) * [icon: check-square-o, set=fa][Set up PingAM](am-setup-1.html) * [icon: check-square-o, set=fa][Set up PingIDM](idm-setup-1.html) * Shared identity store * [icon: check-square-o, set=fa][Set up PingDS](deployment2.html) * [icon: check-square-o, set=fa][Set up PingAM](am-setup-2.html) * [icon: check-square-o, set=fa][Set up PingIDM](idm-setup-2.html) * [icon: check-square-o, set=fa][Protect the deployment](protect-deployment.html) * [icon: check-square-o, set=fa][Set up the Platform UIs](platform-ui.html) * [icon: square-o, set=fa]*[Test your deployment](test-deployment.html)*