Ping Advanced Identity Software

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:

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 MySQL repository. The procedure reflects the listed server settings for installing PingIDM.

  1. Follow the instructions in the PingIDM documentation to download, install, and run PingIDM.

    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.

  4. Configure social authentication.

    In your project’s conf/managed.json file:

    • Add an aliasList property to the user object:

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

      "userEditable" : false

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

  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:

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

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

    You should now be able to access the IDM admin UI at http://openidm.example.com:8080/admin. 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 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 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 file as a template.

  9. Secure the connection to the PingDS server.

    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

  10. 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": "*"
  }]
}

  11. If you want to use the PlatformForgottenUsername or PlatformResetPassword trees, configure outbound email.

    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