Set up PingIDM

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

The Ping 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 PingOne Advanced 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 Ping Identity.

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 for installing PingIDM and PingDS.

Follow the instructions in the PingIDM documentation to download and install PingIDM.
Edit the /path/to/openidm/resolver/boot.properties file to set the hostname:
```
openidm.host=openidm.example.com
```

Configure the shared PingIDM repository.

This step assumes that you have set up PingDS and exported the PingDS CA certificate from directory.example.com (as shown in Step 4 of Secure connections).

Import the PingDS CA certificate into the PingIDM truststore:

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 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.

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:
  /path/to/openidm/startup.sh -> OpenIDM version "8.0.0" <build-info> OpenIDM ready

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:

{
    "objects": [
        {
            "name": "user",
            ...
            "schema": {
            "properties": {
                ...
            }
            ...
        }
    ]
}

Remove encryption from the password property. Remove:
```
"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, 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:
```
"userEditable" : false
```

Add a cn property to the user object:

{
    "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:

"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
},

Change the authentication mechanism to rsFilter only:
- Replace the default conf/authentication.json file with this 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).
- 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:
  "propertyMapping": { "sub": "userName" }
  PingAM refers to the subject by its username in this case. For details, see the reference for the setting in the PingAM documentation.
For more information about authenticating using the rsFilter, see Authenticate through PingAM in the PingIDM documentation.

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:

{
    "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 "platform 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:

Sample ui.context-admin.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"
    }
}

Configure the CORS servlet filter.

Replace the default conf/servletfilter-cors.json file with this servletfilter-cors.json file.
Add the configuration to enable theming for hosted UI pages.
1. Copy this 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:
  { "configs": [{ "pattern": "config/ui/themerealm", "roles": "*", "methods": "read", "actions": "*" }] }
If you have not already started PingIDM, start it now, and test that you can access the IDM admin UI at http://openidm.example.com:8080/admin.

When you log in to the IDM admin UI, use the default PingAM administrative user (amAdmin), and not openidm-admin.
If you want to use the PlatformForgottenUsername or PlatformResetPassword trees, configure outbound email.

After you have installed the Platform UI, you can configure email through the UI at http://openidm.example.com:8080/admin.

PingIDM is now configured for this deployment.

Ping Identity Platform

Set up PingIDM

Next step