ForgeRock Identity Platform 7.4

Set up IDM

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

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

This procedure sets up IDM with an external MySQL repository. The procedure reflects the listed server settings for installing IDM.

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

    Before running IDM, 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 IDM repository. This procedure was tested with a MySQL repository. Follow the instructions in the IDM 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 AM (see Configure OAuth Clients).

    • Check that the rsFilter > subjectMapping > propertyMapping > sub property is correctly configured.

      The authentication.json file aligns with the default AM configuration for subject claim uniqueness. AM refers to the subject by its unique identifier, and so IDM does, too.

      If AM 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 AM, use this property mapping instead:

      "propertyMapping": {
          "sub": "userName"
      }

      AM refers to the subject by its username in this case. For details, see the reference for the setting in the AM documentation.

    For more information about authenticating using the rsFilter, see Authenticate through AM in the IDM 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 is operating in "platform mode" (that is, as an OAuth 2.0 client of AM).

    • 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 AM 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 IDM repository and the AM 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 DS server that you set up as the identity store.

    • Add a mapping between IDM managed user objects, and AM identities stored in DS.

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

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

    Import the DS CA certificate into the IDM 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 UI, you can configure email through the UI at http://openidm.example.com:8080/admin.

IDM is now configured for this deployment.

Copyright © 2010-2024 ForgeRock, all rights reserved.