--- title: Set up PingAM 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:am-setup-1 canonical_url: https://docs.pingidentity.com/platform/8/sample-setup/am-setup-1.html page_aliases: ["platform-setup-guide:am-setup-1.adoc"] section_ids: install-am-1: Install PingAM use-external-cts-1: Use the external CTS store create-alpha-1: Create a realm oauth-clients: Configure OAuth clients oauth-service: Configure OAuth 2.0 providers idm-prov-service: Configure a PingIDM provisioning service validation-service: Configure a validation service cors-support: Enable CORS support auth-trees: Configure authentication journeys map-auth-trees: Map authentication trees additional_pingam_configuration: Additional PingAM configuration restart-tomcat-1: Restart Tomcat next_step: Next step --- # Set up PingAM | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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). | When your external data stores are configured, follow these procedures to configure PingAM in an Advanced Identity Software deployment: ## Install PingAM 1. Follow the instructions in the PingAM documentation to [download PingAM](https://docs.pingidentity.com/pingam/8/install-guide/download-openam-software.html). Make sure you download the `.zip` file, not just the `.war` file. 2. Extract the `.zip` file, locate the PingAM `.war` file, and copy the `.war` file to deploy in Apache Tomcat as `am.war`: ```bash cp AM-8.0.1.war /path/to/tomcat/webapps/am.war ``` 3. Start Tomcat if it's not already running. It can take Apache Tomcat several seconds to deploy PingAM. 4. Go to the deployed PingAM application; for example, `http://am.example.com:8081/am/`. 5. On the initial configuration page, click Create New Configuration. 6. Review the software license agreement. If you agree to the license, click I accept the license agreement, and click Continue. 7. Set a password for the default user, `amAdmin`. These instructions assume that the `amAdmin` password is `Passw0rd`. 8. On the Server Settings screen, enter the following details and click Next: * Server URL `http://am.example.com:8081` * Cookie Domain `example.com` * Platform Locale `en_US` * Configuration Directory `/path/to/am` 9. On the Configuration Data Store Settings page, enter the following details and click Next: * SSL/TLS Enabled `Enabled` (PingDS requires TLS.) * Host Name `ds.example.com` * Port `1636` * Encryption Key Keep the randomly generated key. * Root Suffix `ou=am-config` * Login ID `uid=am-config,ou=admins,ou=am-config` * Password `5up35tr0ng` * Server configuration Leave the `New deployment` option selected. 10. On the User Data Store page, enter the following details and click Next: | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The PingAM setup process requires that you configure an identity store.You will use this store later in an `alpha` realm for non-administrative identities. | This list reflects the PingDS identity store installed with the listed [server settings](server-settings.html). * User Data Store Type Leave the `ForgeRock Directory Services (DS)` option selected. * SSL/TLS Enabled `Enabled` (PingDS requires TLS.) * Directory Name `directory.example.com` * Port `1636` * Root Suffix `ou=identities` * Login ID `uid=am-identity-bind-account,ou=admins,ou=identities` * Password `5up35tr0ng` 11. On the Site Configuration page, leave the `No` option selected and click Next. 12. Review the Configurator Summary Details, then click Create Configuration. ## Use the external CTS store Update the PingAM configuration to use PingDS as an external token store: 1. Log in to the AM admin UI as the `amAdmin` user. 2. Browse to Configure > Server Defaults > CTS. 3. Make the following changes, saving your work before switching tabs: | Setting | Choice | | --------------------------------------------------- | -------------------------------------------------------------------- | | CTS Token Store > Store Mode | External Token Store | | CTS Token Store > Root Suffix | `ou=famrecords,ou=openam-session,ou=tokens` | | External Store Configuration > SSL/TLS Enabled | Selected | | External Store Configuration > Connection String(s) | `localhost:1636` | | External Store Configuration > Login Id | `uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens` | | External Store Configuration > Password | `5up35tr0ng` | Keep the defaults for all other settings. ## Create a realm The PingAM Top Level Realm should serve administration purposes only. These steps create an `alpha` realm for non-administrative identities: 1. If you're not currently logged in to the AM admin UI as the `amAdmin` user, log in. 2. Click + New Realm, and create the new realm with the following settings: * Name: `alpha` * Keep the defaults for all other settings. For background information, see [Realms](https://docs.pingidentity.com/pingam/8/setup-guide/am-realms.html) in the PingAM documentation. ## Configure OAuth clients The deployment depends on the following OAuth 2.0 clients: | Client ID | Description | In Top Level Realm? | In subrealms? | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | --------------------- | | `idm-resource-server` | PingIDM uses this confidential client to introspect access tokens through the `/oauth2/introspect` endpoint to obtain information about users.This client is not used for OAuth 2.0 flows, only to introspect tokens. It is not a *real* OAuth 2.0 client, in the traditional sense. Rather, it is an OAuth 2.0 Resource Server account, used exclusively for token introspection. As such, you do not need to specify redirect URIs or grant types.When you configure the client, PingAM adds the `Authorization Code` grant type to the client profile by default. This client does not use it, but there's no requirement to remove it from the client profile. | [icon: check, set=fa] | [icon: times, set=fa] | | `idm-provisioning` | PingAM nodes in authentication journeys (trees) use this confidential client to authenticate through PingAM and provision identities through PingIDM.This client uses the client credentials flow, and does not authenticate resource owners other than itself. | [icon: check, set=fa] | [icon: check, set=fa] | | `idm-admin-ui` | The Advanced Identity Software Admin UI uses this public client to access Advanced Identity Software configuration features, such as identity management and journey (tree) editing.The client uses the implicit flow, and authenticates administrator users who are authorized to perform administrative operations. | [icon: check, set=fa] | [icon: check, set=fa] | | `end-user-ui` | The End User UI uses this public client to access and present end-user profile data.The client uses the implicit flow, and authenticates end users who are authorized to view and edit their profiles. | [icon: check, set=fa] | [icon: check, set=fa] | When configuring a client in more than one realm, make sure the client configurations are identical. Follow these steps to configure the OAuth 2.0 clients: 1. If you're not currently logged in to the AM admin UI as the `amAdmin` user, log in. 2. In **the Top Level Realm**, configure an `idm-resource-server` client to introspect access tokens: * Select Applications > OAuth 2.0 > Clients, and click Add Client. * Enter the following details: * Client ID: `idm-resource-server` * Client secret: `password` The value of this field must match the `clientSecret` that you will set in the `rsFilter` module in the PingIDM authentication configuration (`/path/to/openidm/conf/authentication.json`) during your PingIDM setup. * Scopes:\ `am-introspect-all-tokens`\ `am-introspect-all-tokens-any-realm` * Click Create. 3. In **the Top Level Realm and the `alpha` realm**, configure identical `idm-provisioning` clients to make calls to PingIDM: * Select Applications > OAuth 2.0 > Clients, and click Add Client. * Enter the following details: * Client ID: `idm-provisioning` * Client secret: `openidm` * Scopes: `fr:idm:*` * Click Create. * On the Advanced tab: * Response Types: Check that `token` is present (it should be there by default). * Grant Types: Remove `Authorization Code` and add `Client Credentials`. * Click Save Changes. 4. In **the Top Level Realm and the `alpha` realm**, configure identical `idm-admin-ui` clients that will be used by the Advanced Identity Software Admin UI: * Select Applications > OAuth 2.0 > Clients, and click Add Client. * Enter the following details: * Client ID: `idm-admin-ui` * Client Secret: (no client secret is required) * Redirection URIs: `http://openidm.example.com:8080/platform/appAuthHelperRedirect.html`\ `http://openidm.example.com:8080/platform/sessionCheck.html`\ `http://openidm.example.com:8080/admin/appAuthHelperRedirect.html`\ `http://openidm.example.com:8080/admin/sessionCheck.html`\ `http://admin.example.com:8082/appAuthHelperRedirect.html`\ `http://admin.example.com:8082/sessionCheck.html` * Scopes: `openid`\ `fr:idm:*` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | At a minimum, the scopes that you set here must include the scopes that you will set in the `rsFilter` authentication configuration (`/path/to/openidm/conf/authentication.json`) during your PingIDM setup. | * Click Create. * On the Core tab: * Client type: Select `Public`. * Click Save Changes. * On the Advanced tab: * Grant Types: Add `Implicit`. * Token Endpoint Authentication Method: Select `none`. * Implied consent: Enable. * Click Save Changes. 5. In **the Top Level Realm and the `alpha` realm**, configure identical `end-user-ui` clients that will be used by the Advanced Identity Software End User UI: * Select Applications > OAuth 2.0 > Clients , and click Add Client. * Enter the following details: * Client ID: `end-user-ui` * Client Secret: (no client secret is required) * Redirection URIs: `http://enduser.example.com:8888/appAuthHelperRedirect.html`\ `http://enduser.example.com:8888/sessionCheck.html` * Scopes: `openid`\ `fr:idm:*` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | At a minimum, the scopes that you set here must include the scopes that you will set in the `rsFilter` authentication configuration (`/path/to/openidm/conf/authentication.json`) during your PingIDM setup. | * Click Create. * On the Core tab: * Client type: Select `Public`. * Click Save Changes. * On the Advanced tab: * Grant Types: Add `Implicit`. * Token Endpoint Authentication Method: Select `none`. * Implied Consent: Enable. * Click Save Changes. ## Configure OAuth 2.0 providers 1. If you're not currently logged in to the AM admin UI as the `amAdmin` user, log in. 2. Configure a provider for the Top Level Realm: 1. In the Top Level Realm, select Services, and click Add a Service. 2. Under Choose a service type, select OAuth2 Provider. 3. For Client Registration Scope Allowlist, add the following scopes:\ `am-introspect-all-tokens`\ `am-introspect-all-tokens-any-realm`\ `fr:idm:*`\ `openid` 4. Click Create. 5. On the Advanced tab, make sure that Response Type Plugins includes the following values:\ `id_token|org.forgerock.openidconnect.IdTokenResponseTypeHandler`\ `code|org.forgerock.oauth2.core.AuthorizationCodeResponseTypeHandler` 6. Click Save Changes. 7. On the Consent tab, enable Allow Clients to Skip Consent. 8. Click Save Changes. 3. Configure a provider for the `alpha` realm: 1. In the `alpha` realm, select Services, and click Add a Service. 2. Under Choose a service type, select OAuth2 Provider. 3. For Client Registration Scope Allowlist, add the following scopes:\ `fr:idm:*`\ `openid` 4. Click Create. 5. On the Advanced tab, make sure that Response Type Plugins includes the following values:\ `id_token|org.forgerock.openidconnect.IdTokenResponseTypeHandler`\ `code|org.forgerock.oauth2.core.AuthorizationCodeResponseTypeHandler` 6. Click Save Changes. 7. On the Consent tab, enable Allow Clients to Skip Consent. 8. Click Save Changes. ## Configure a PingIDM provisioning service 1. If you're not currently logged in to the AM admin UI as the `amAdmin` user, log in. 2. From the top menu, select Configure > Global Services > IDM Provisioning. The AM admin UI doesn't let you configure a PingIDM provisioning service in a realm. 3. Set the following fields: * Enabled * Deployment URL: `http://openidm.example.com:8080` * Deployment Path: `openidm` * IDM Provisioning Client: `idm-provisioning` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Do *not* enable the useInternalOAuth2Provider setting in an Advanced Identity Software environment. Doing so can cause other OAuth 2.0 client requests to fail with the following error:`No client profile or more than one profile found.` | 4. Click Save Changes. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If some resource strings in the AM admin UI don't resolve properly at setup time, the UI labels mentioned will show internal keys instead of the labels shown in the steps above. Use the following table to check that you have the correct service and fields:UI label Internal label IDM Provisioning IdmIntegrationService Enabled enabled Deployment URL idmDeploymentUrl Deployment Path idmDeploymentPath IDM Provisioning Client idmProvisioningClient | ## Configure a validation service The Platform UIs need this validation service allow listing for `goto` redirection. 1. If you're not currently logged in to the AM admin UI as the `amAdmin` user, log in. 2. In the `alpha` realm, select Services, and click Add a Service. 3. Under Choose a service type, select Validation Service. 4. For Valid goto URL Resources, add the URLs for the Platform UI: `http://admin.example.com:8082/*`\ `http://admin.example.com:8082/*?*`\ `http://login.example.com:8083/*`\ `http://login.example.com:8083/*?*`\ `http://enduser.example.com:8888/*`\ `http://enduser.example.com:8888/*?*` 5. Click Create. ## Enable CORS support Cross-origin resource sharing (CORS) lets user agents make requests across domains. 1. If you're not currently logged in to the AM admin UI as the `amAdmin` user, log in. 2. From the top menu, select Configure > Global Services > CORS Service. 3. On the Secondary Configurations tab, click Add a Secondary Configuration. 4. On the New Configuration screen, enter the following values: * Name : `Cors Configuration` * Accepted Origins : `http://login.example.com:8083`\ `http://admin.example.com:8082`\ `http://enduser.example.com:8888`\ `http://openidm.example.com:8080`\ `https://openidm.example.com:8443` List only the origins that will be hosting OAuth 2.0 clients (such as the `platform-enduser` and IDM admin UIs). * Accepted Methods: `DELETE`\ `GET`\ `HEAD`\ `PATCH`\ `POST`\ `PUT` * Accepted Headers: `accept-api-version`\ `authorization`\ `cache-control`\ `content-type`\ `if-match`\ `if-none-match`\ `user-agent`\ `x-forgerock-transactionid`\ `x-openidm-nosession`\ `x-openidm-password`\ `x-openidm-username`\ `x-requested-with` * Exposed Headers: `WWW-Authenticate` 5. Click Create. 6. On the Cors Configuration screen, set the following values: * Enable the CORS filter: Enable * Max Age: `600` * Allow Credentials: Enable 7. Click Save Changes. ## Configure authentication journeys Advanced Identity Software deployment relies on three authentication trees to enable authentication through PingAM. When you extract the PingAM `.zip` file, you'll get a `sample-trees-8.zip` file that contains a number of authentication trees, in JSON files. Use the Amster command-line utility to import these authentication trees into your PingAM configuration: 1. Extract the `sample-trees-8.zip` file, and list the sample trees in the `root/AuthTree` directory: ```bash ls /path/to/openam-samples/root/AuthTree Agent.json PlatformForgottenUsername.json Example.json PlatformLogin.json Facebook-ProvisionIDMAccount.json PlatformProgressiveProfile.json Google-AnonymousUser.json PlatformRegistration.json Google-DynamicAccountCreation.json PlatformResetPassword.json HmacOneTimePassword.json PlatformUpdatePassword.json PersistentCookie.json RetryLimit.json ``` 2. In all the sample tree files, replace `"realm" : "/"` with `"realm" : "/alpha"`. 3. [Download and install Amster](https://docs.pingidentity.com/pingam/8/amster/install-amster.html). 4. Start Amster, then connect to your PingAM instance: ```bash ./amster Amster OpenAM Shell (version build build, JVM: version) Type ':help' or ':h' for help. --------------------------------------------------------------------------- am> connect --interactive http://am.example.com:8081/am Sign in User Name: amAdmin Password: Passw0rd amster am.example.com:8081> :exit ``` 5. Import the sample authentication trees and nodes: ```bash amster am.example.com:8081>import-config --path /path/to/openam-samples/root Importing directory /path/to/openam-samples/root/AcceptTermsAndConditions ... Import completed successfully ``` 6. If you're not currently logged in to the AM admin UI as the `amAdmin` user, log in. 7. Configure the `PlatformRegistration` tree: * In the `alpha` realm, select Authentication > Trees, and click PlatformRegistration. * On the `PlatformRegistration` tree, add a `Success URL` node between `Increment Login Count` and `Success`, and set its value to `http://enduser.example.com:8888/?realm=alpha`. > **Collapse: Show me** > > ![platform registration](_images/platform-registration.gif) * Click Save. 8. Configure the `PlatformLogin` tree: * In the `alpha` realm, select Authentication > Trees, and click PlatformLogin. * On the `PlatformLogin` tree, add a `Success URL` node between `Inner Tree Evaluator` and `Success`, and set its value to `http://enduser.example.com:8888/?realm=alpha`. > **Collapse: Show me** > > ![platform login](_images/platform-login.gif) * Click Save. 9. Configure the `PlatformResetPassword` tree: * In the `alpha` realm, select Authentication > Trees, and click PlatformResetPassword. * On the `PlatformResetPassword` tree, add a `Success URL` node between `Patch Object` and `Success`, and set its value to `http://enduser.example.com:8888/?realm=alpha`. > **Collapse: Show me** > > ![platform reset pwd](_images/platform-reset-pwd.gif) * Click Save. 10. Configure the `PlatformUpdatePassword` tree: * In the `alpha` realm, select Authentication > Trees, and click PlatformUpdatePassword. * On the `PlatformUpdatePassword` tree, select the `Patch Object` node, and make sure `Patch As Object` is disabled. > **Collapse: Show me** > > ![patch-as-object-false](_images/patch-as-object-false.png) * Click Save. 11. For the authentication trees that require email, set the External Login Page URL. * In the `alpha` realm, select Authentication > Settings, and click the General tab. * Set External Login Page URL to `http://login.example.com:8083`, then click Save Changes. ## Map authentication trees Map the Advanced Identity Software authentication trees to the corresponding Self-Service endpoints. 1. In the `alpha` realm, select Services, and click Add a Service. 2. Under Choose a service type, select Self Service Trees, and click Create. 3. Add the following tree mappings: | Key | Value | | --------------- | ----------------------- | | `registration` | `PlatformRegistration` | | `login` | `PlatformLogin` | | `resetPassword` | `PlatformResetPassword` | ![self-service-trees](_images/self-service-trees.png) 4. Click Save Changes. ## Additional PingAM configuration The PingAM configuration shown is sufficient for this sample deployment. Read the [PingAM](https://docs.pingidentity.com/pingam/8) documentation when using additional features. For example, if PingAM runs behind a load balancer or a reverse proxy, configure a base URL source service. [Adapt the PingAM configuration](protect-deployment.html#protect-am-config) to use this service when you protect PingAM with PingGateway. ## Restart Tomcat Restart Tomcat to take all the configuration changes into account: ```bash $ /path/to/tomcat/bin/shutdown.sh # Wait a moment for Tomcat to shut down cleanly before starting it again. $ /path/to/tomcat/bin/startup.sh ``` ## 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](deployment1.html) * [icon: check-square-o, set=fa][Set up PingAM](am-setup-1.html) * [icon: square-o, set=fa]*[Set up PingIDM](idm-setup-1.html)* * [icon: square-o, set=fa][Protect the deployment](protect-deployment.html) * [icon: square-o, set=fa][Set up the Platform UIs](platform-ui.html) * [icon: square-o, set=fa][Test your deployment](test-deployment.html)