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 DS instance as the repository. The DS instance is shared with AM as the identity store. The procedure reflects the listed server settings for installing IDM and DS.

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

Configure the shared IDM repository.

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

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 IDM truststore and truststore password file.

Check that the properties under ldapConnectionFactories match the DS server that you set up as the identity store.

It is worth starting IDM at this point, to make sure that it can connect to the external DS repository.
1. Set the JAVA_HOME environment variable.
2. Start IDM, and wait until you see OpenIDM ready in the output:
  /path/to/openidm/startup.sh -> OpenIDM version "7.4.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 AM and IDM can use. This differs from Separate identity stores, where AM and IDM 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 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.

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

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 IDM, 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 AM 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.

IDM is now configured for this deployment.

ForgeRock Identity Platform 7.4

Set up IDM

Next step