--- title: Set up PingIDM 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:idm-setup-2 canonical_url: https://docs.pingidentity.com/platform/8/sample-setup/idm-setup-2.html page_aliases: ["platform-setup-guide:idm-setup-2.adoc"] section_ids: next_step: Next step --- # Set up PingIDM | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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 procedure sets up PingIDM with an external PingDS instance as the repository. The PingDS instance is shared with PingAM as the identity store. The procedure reflects the listed [server settings](server-settings.html) for installing PingIDM and PingDS. 1. Follow the instructions in the PingIDM documentation to [download and install PingIDM](https://docs.pingidentity.com/pingidm/8/install-guide/chap-install.html#install-openidm). 2. Edit the `/path/to/openidm/resolver/boot.properties` file to set the hostname: ```properties openidm.host=openidm.example.com ``` 3. Configure the shared PingIDM repository. This step assumes that you have [set up PingDS](deployment2.html#data-setup-2) and exported the PingDS CA certificate from `directory.example.com` (as shown in Step 4 of [Secure connections](deployment2.html#secure-connections-2)). * Import the PingDS CA certificate into the PingIDM truststore: ```bash keytool \ -importcert \ -alias ds-ca-cert \ -file /path/to/ds-ca-cert.pem \ -keystore /path/to/openidm/security/truststore \ -storepass:file /path/to/openidm/security/storepass Owner: CN=Deployment key, O=ForgeRock.com Issuer: CN=Deployment key, O=ForgeRock.com ... Trust this certificate? [no]: yes Certificate was added to keystore ``` * Replace the default `conf/repo.ds.json` file with this [repo.ds.json](../_attachments/repo.ds.json) file. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Replace the values of `fileBasedTrustManagerFile` and `fileBasedTrustManagerPasswordFile` with the path to your PingIDM truststore and truststore password file.Check that the properties under `ldapConnectionFactories` match the PingDS server that you set up as the identity store. | 4. It is worth starting PingIDM at this point, to make sure that it can connect to the external PingDS repository. 1. Set the `JAVA_HOME` environment variable. 2. Start PingIDM, and wait until you see `OpenIDM ready` in the output: ```bash /path/to/openidm/startup.sh -> OpenIDM version "8.0.0" OpenIDM ready ``` 5. Update the `user` object in your managed object configuration by making the following changes to your `conf/managed.json` file. All changes are made to the object `user` > `schema` > `properties`: ```json { "objects": [ { "name": "user", ... "schema": { "properties": { ... } ... } ] } ``` * Remove encryption from the `password` property. Remove: ```json "encryption" : { "purpose": "idm.password.encryption" } ``` Password *encryption* is not supported in a shared identity store setup. Instead, the shared identity store supports only *hashed* passwords, a format that both PingAM and PingIDM can use. This differs from [Separate identity stores](deployment1.html), where PingAM and PingIDM do not share the identity store, and so each service can store passwords in different formats. * Update the `password` property to ensure that users update their passwords through the self-service APIs, not directly: ```json "userEditable" : false ``` * Add a `cn` property to the `user` object: ```json { "objects": [ { "name": "user", ... "schema": { "properties" : { "_id" : { ... }, "cn": { "title": "Common Name", "description": "Common Name", "type": "string", "viewable": false, "searchable": false, "userEditable": false, "scope": "private", "isPersonal": true, "isVirtual": true, "onStore": { "type": "text/javascript", "source": "object.cn || (object.givenName + ' ' + object.sn)" } }, ... } ... } ] } ``` * Configure social authentication. Add an `aliasList` property to the `user` object: ```json "aliasList": { "title": "User Alias Names List", "description": "List of identity aliases used primarily to record social IdP subjects for this user", "type": "array", "items": { "type": "string", "title": "User Alias Names Items" }, "viewable": false, "searchable": false, "userEditable": true, "returnByDefault": false, "isVirtual": false }, ``` 6. Change the authentication mechanism to `rsFilter` only: * Replace the default `conf/authentication.json` file with this [authentication.json](../_attachments/authentication.json) file. * Check that the `clientSecret` matches the `Client secret` that you set for the `idm-resource-server` client in PingAM (see [Configure OAuth Clients](am-setup-1.html#oauth-clients)). * Check that the `rsFilter` > `subjectMapping` > `propertyMapping` > `sub` property is correctly configured. The `authentication.json` file aligns with the default PingAM configuration for subject claim uniqueness. PingAM refers to the subject by its unique identifier, and so PingIDM does, too. If PingAM has its advanced server property, `org.forgerock.security.oauth2.enforce.sub.claim.uniqueness`, set to `false`, for example, because you upgraded from a previous release of PingAM, use this property mapping instead: ```json "propertyMapping": { "sub": "userName" } ``` PingAM refers to the subject by its username in this case. For details, see the [reference for the setting](https://docs.pingidentity.com/pingam/8/reference/deployment-configuration-reference.html#adv-property-sub-claim) in the PingAM documentation. For more information about authenticating using the `rsFilter`, see [Authenticate through PingAM](https://docs.pingidentity.com/pingidm/8/auth-guide/rsfilter-auth.html) in the PingIDM documentation. 7. Edit the IDM admin UI configuration so that you can still authenticate through the IDM admin UI: * In your `/path/to/openidm/conf/ui-configuration.json` file, insert a `platformSettings` object into the `configuration` object: ```json { "configuration" : { "platformSettings" : { "adminOauthClient" : "idm-admin-ui", "adminOauthClientScopes" : "fr:idm:*", "amUrl" : "http://am.example.com:8081/am", "loginUrl" : "" } } } ``` This object tells the IDM admin UI that it is operating in "Advanced Identity Software mode" (that is, as an OAuth 2.0 client of PingAM). * In your `conf/ui.context-admin.json` file, check that `X-Frame-Options` is set to `SAMEORIGIN`: > **Collapse: Sample ui.context-admin.json** > > ```json > { > "enabled" : true, > "cacheEnabled": true, > "urlContextRoot" : "/admin", > "defaultDir" : "&{idm.install.dir}/ui/admin/default", > "extensionDir" : "&{idm.install.dir}/ui/admin/extension", > "responseHeaders" : { > "X-Frame-Options" : "SAMEORIGIN" > } > } > ``` 8. Configure the CORS servlet filter. Replace the default `conf/servletfilter-cors.json` file with this [servletfilter-cors.json](../_attachments/servletfilter-cors.json) file. 9. Add the configuration to enable theming for hosted UI pages. 1. Copy this [ui-themerealm.json](../_attachments/ui-themerealm.json) file to the `conf/` directory. 2. In your `conf/access.json` file, insert a configuration object for the theme in the `configs` array: ```json { "configs": [{ "pattern": "config/ui/themerealm", "roles": "*", "methods": "read", "actions": "*" }] } ``` 10. If you have not already started PingIDM, start it now, and test that you can access the IDM admin UI at . When you log in to the IDM admin UI, use the default PingAM administrative user (`amAdmin`), and not `openidm-admin`. 11. If you want to use the `PlatformForgottenUsername` or `PlatformResetPassword` trees, [configure outbound email](https://docs.pingidentity.com/pingidm/8/external-services-guide/email.html). | | | | - | ----------------------------------------------------------------------------------------------------------------------------- | | | After you have installed the Platform UIs, you can configure email through the UI at `http://openidm.example.com:8080/admin`. | PingIDM is now configured for this deployment. ## 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) * 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: 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)