--- 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-1 canonical_url: https://docs.pingidentity.com/platform/8/sample-setup/idm-setup-1.html page_aliases: ["platform-setup-guide:idm-setup-1.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 MySQL repository. The procedure reflects the listed [server settings](server-settings.html) for installing PingIDM. 1. Follow the instructions in the PingIDM documentation to [download, install, and run PingIDM](https://docs.pingidentity.com/pingidm/8/install-guide/chap-install.html#install-openidm). Before running PingIDM, make sure you set the `JAVA_HOME` environment variable. 2. Edit the `/path/to/openidm/resolver/boot.properties` file to set the hostname: ``` openidm.host=openidm.example.com ``` 3. Configure your PingIDM repository. This procedure was tested with a MySQL repository. Follow the instructions in the PingIDM documentation to set up a [MySQL repository](https://docs.pingidentity.com/pingidm/8/install-guide/repository-mysql.html). 4. Configure social authentication. In your project's `conf/managed.json` file: * Add an `aliasList` property to the `user` object: ```json { "objects": [ { "name": "user", ... "schema": { "properties": { ... "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 } ... ] } ``` * Update the `password` property to ensure that users update their passwords through the self-service APIs, not directly: ```json "userEditable" : false ``` 5. 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. 6. Edit the IDM admin UI configuration so that you can still authenticate through the IDM admin UI: * In your `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's 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" > } > } > ``` You should now be able to access the IDM admin UI at . When you log in to the Admin UI, use the default PingAM administrative user (`amAdmin`), and not `openidm-admin`. 7. Configure the CORS servlet filter. Replace the default `conf/servletfilter-cors.json` file with this [servletfilter-cors.json](../_attachments/servletfilter-cors.json) file. 8. Configure synchronization between the PingIDM repository and the PingAM identity store. * Add a configuration for the LDAP connector. Create a configuration file named `provisioner.openicf-ldap.json` in the `/path/to/openidm/conf` directory. Use this [provisioner.openicf-ldap.json](../_attachments/provisioner.openicf-ldap.json) file as a template. Pay particular attention to the connection properties, `host`, `port`, `principal`, and `credentials`. These must match the configuration of the PingDS server that you set up as the identity store. * Add a mapping between PingIDM managed user objects, and PingAM identities stored in PingDS. Create a mapping file named `sync.json` in the `/path/to/openidm/conf` directory. Use this [sync.json](../_attachments/sync.json) file as a template. 9. Secure the connection to the PingDS server. This step assumes that you have [set up PingDS](deployment1.html#data-setup-1) and exported the PingDS CA certificate from `directory.example.com` (as shown in Step 4 of [Secure connections](deployment1.html#secure-connections-1)). 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 ``` 10. 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": "*" }] } ``` 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) * 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: check-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)