ForgeRock Identity Platform 7.4

Set up the platform UIs

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

The ForgeRock Identity Platform offers maximum extensibility and flexibility in self-managed deployments. The platform 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 platform as a service, use ForgeRock Identity Cloud.

  • To deploy in Kubernetes, start with the ForgeOps reference implementation.

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

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

The ForgeRock® Identity Platform includes three UIs:

Admin UI

Lets platform 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 IDM (using an OAuth 2 bearer token) and to AM (using an SSO cookie).

This UI is not the same as the standalone IDM End User UI.

The platform End User UI is designed specifically for an integrated platform deployment.

The IDM end user UI should be used only in a standalone IDM deployment.
Login UI

A unified Login UI that lets both administrators and end users log in to the platform.

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:7.4.0

    • Download the End User UI:

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

    • Download the Login UI:

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

  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=http://am.example.com:8081/am
AM_ADMIN_URL=http://am.example.com:8081/am/ui-admin
IDM_REST_URL=http://openidm.example.com:8080/openidm
IDM_ADMIN_URL=http://openidm.example.com:8080/admin
IDM_UPLOAD_URL=http://openidm.example.com:8080/upload
IDM_EXPORT_URL=http://openidm.example.com:8080/export
ENDUSER_UI_URL=http://enduser.example.com:8888
PLATFORM_ADMIN_URL=http://admin.example.com:8082
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:7.4.0
Replacing env vars in JS

Setting AM URL as http://am.example.com:8081/am
Setting AM ADMIN URL as http://am.example.com:8081/am/ui-admin
Setting IDM REST URL as http://openidm.example.com:8080/openidm
Setting IDM ADMIN URL as http://openidm.example.com:8080/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:7.4.0
Replacing env vars in JS

Setting AM URL as http://am.example.com:8081/am
Setting AM ADMIN URL as http://am.example.com:8081/am/ui-admin
Setting IDM REST URL as http://openidm.example.com:8080/openidm
Setting IDM ADMIN URL as http://openidm.example.com:8080/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:7.4.0
Replacing env vars in JS

Setting AM URL as http://am.example.com:8081/am
Setting AM ADMIN URL as http://am.example.com:8081/am/ui-admin
Setting IDM REST URL as http://openidm.example.com:8080/openidm
Setting IDM ADMIN URL as http://openidm.example.com:8080/admin
...

  4. Test access to the Admin UI by logging in through the Login UI.

    Go to http://login.example.com:8083/?realm=/.

    Login UI

  5. Sign in as amAdmin. You are redirected to the Admin UI:

    Admin UI

  6. Sign out of the Admin UI.

  7. To test the End User UI, self-register as a new user.

    Go to http://login.example.com:8083/?realm=/alpha#/service/PlatformLogin.

    Click Create an account.

    Registration page

  8. When the required fields have been completed, you are logged into the End User UI, as that user:

    End User UI

Install a .zip file

If you have already deployed the Platform UI by running Docker images, do not perform these steps.

In this sample deployment, you obtain the three UIs from a .zip file that you get from ForgeRock. Then, you install them in the AM web container. You also tweak the AM and IDM 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 7.4.x UI .zip file from the Platform section of the ForgeRock 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 ForgeRock Identity Platform deployment:

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

    2. Run the following commands:

      export AM_URL=http://am.example.com:8081/am
export AM_ADMIN_URL=http://am.example.com:8081/am/ui-admin
export IDM_REST_URL=http://openidm.example.com:8080/openidm
export IDM_ADMIN_URL=http://openidm.example.com:8080/admin
export IDM_UPLOAD_URL=http://openidm.example.com:8080/upload
export IDM_EXPORT_URL=http://openidm.example.com:8080/export
export ENDUSER_UI_URL=http://am.example.com:8081/enduser
export PLATFORM_ADMIN_URL=http://am.example.com:8081/platform
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 http://am.example.com:8081/am
Setting AM ADMIN URL as http://am.example.com:8081/am/ui-admin
Setting IDM REST URL as http://openidm.example.com:8080/openidm
...

  3. Install the UI:

    1. Install the platform and enduser web applications into AM’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 AM to use the new Login UI:

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

  4. Revise the AM and IDM configurations to work with the new UI installation:

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

    2. Revise the success URL for three authentication trees, so that they refer to the End User UI:

      1. Change the success URL for the Platform Regstration tree.

        In the alpha realm, select Authentication > Trees, and click on PlatformRegistration. Select the Success URL node. Change the Success URL value to http://am.example.com:8081/enduser, and then click Save.

      2. Use the same technique to change the Success URL value for the PlatformLogin tree to http://am.example.com:8081/enduser.

      3. Use the same technique to change the Success URL value for the PlatformResetPassword tree to http://am.example.com:8081/enduser.

    3. Clear the External Login Page URL value.

      In the alpha realm, select Authentication > Settings, and click the General tab. Set External Login Page URL to an empty string, and then click Save Changes.

    4. Log out of the AM admin UI.

    5. If no /path/to/openidm/conf/ui-themerealm.json file exists, create it with the following contents:

      {
    "realm": {}
}

  5. Test access to the Admin UI:

    1. Go to http://am.example.com:8081/platform.

      The Sign in page appears:

      Login UI

    2. Sign in as the amAdmin user. You are redirected to the Admin UI:

      Admin UI

  6. Test access to the End User UI:

    1. In the Admin UI, create a test user:

      1. Click Identities > Manage.

      2. Click + New User.

      3. Fill in the user details.

      4. Click Save.

        If the UI displays an Invalid create form message, some of the user details you provided are invalid. In particular, make sure the password is valid according to the password policy.

    2. Sign out of the Admin UI.

    3. Go to http://am.example.com:8081/enduser.

      The Sign in page appears.

    4. Sign in as the test user you just created. You should be redirected to the End User UI.

Redirect on signout

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

XUI login page

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

  • Use IG, 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 AM 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://forgerock.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://forgerock.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.

    AM 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 the main ForgeRock site.

Next step

Copyright © 2010-2024 ForgeRock, all rights reserved.