How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I connect to IDM (All versions) with mutual SSL authentication from IG (All versions)?

Last updated Jan 11, 2023

The purpose of this article is to provide information on connecting to IDM with mutual SSL authentication from IG using the client certificate module (CLIENT_CERT).

2 readers recommend this article

Connecting to IDM with mutual SSL authentication

The following process guides you through connecting to IDM with mutual SSL authentication from IG, where IDM is the server and IG is the client:

  1. Configure the CLIENT_CERT module in IDM per Authentication and session modules ensuring you update your authentication.json file (located in the /path/to/idm/conf directory) to include the module.
  2. Create a keystore for IG that contains the IG private key and certificate. See Configure IG For HTTPS (client-side) for further information.
  3. Import the IG certificate into the IDM truststore to allow IDM to trust IG. See Test client certificate authentication for an example.
  4. Import the IDM server certificate (openidm-localhost) into the IG truststore to allow IG to trust IDM.
  5. Create a custom endpoint for mutual SSL authentication purposes. See Create custom endpoints to launch scripts for further information on custom endpoints.
  6. Update the access.json file (IDM 7 and later - located in /path/to/idm/conf) or the access.js file (IDM 6.x - located in /path/to/idm/script) to allow the internal/role/openidm-cert role to access the custom endpoint you created. The internal/role/openidm-cert role is the default role for any user authenticated with mutual SSL authentication. For example, if your custom endpoint is endpoint/echo, the addition needed in the access.json file or the access.js file would be similar to this: { "pattern" : "endpoint/echo",  "roles" : "internal/role/openidm-cert",  "methods" : "*",  "actions" : "*" }, In IDM 6, you do not need to include the full path; you can just refer to the role name, for example, openidm-cert.
  7. Create a route in IG that includes ClientTlsOptions (IG 7 and later), TlsOptions (IG 6.5) or keyManager (IG 6) for the ClientHandler that is configured with the IG keystore. For example, your route may look similar to this with a ClientTlsOptions object: {  "handler": {     "type": "Chain",     "config": {       "filters" : [         {             "name": "OpenIDMuserName",             "type": "HeaderFilter",             "config": { "messageType": "REQUEST", "remove": ["X-OpenIDM-Username"],             "add" : {               "X-OpenIDM-Username": [ "anonymous" ]             }           }         },         {             "name": "OpenIDMpassword",             "type": "HeaderFilter",             "config": {               "messageType": "REQUEST",               "remove": ["X-OpenIDM-Password"],               "add" : { "X-OpenIDM-Password": [ "anonymous" ]               }             }         }       ],       "handler": {         "type" : "ClientHandler",         "config": {           "tls": {             "type": "ClientTlsOptions",             "config": {               "sslContextAlgorithm": "TLSv1.2",               "hostnameVerifier": "STRICT",               "keyManager": { "type": "KeyManager", "config": { "keystore": { "type": "KeyStore", "config": { "url": "file://${env['HOME']}/keystore.jks", "passwordSecretId": "", "secretsProvider": "SystemAndEnvSecretStore" } }, "passwordSecretId": "", "secretsProvider": "SystemAndEnvSecretStore" }               }             }           }         }       },       "capture" : "all"     }   },   "condition": "${find(request.uri.path, '^/openidm/endpoint/echo')}",   "baseURI": "",   "capture" : "all",   "timer" : true }This example uses the find function in the condition statement. In pre-IG 7.1.2, this would be the matches function instead. See Configure Routes for further information.
  8. Update the openidm.auth.clientauthonlyport property in the file (located in install-dir/resolver) to include the IG port (and ports for any other clients that are authorized to perform authentication). You can have a list of ports, for example: openidm.auth.clientauthonlyports=18444,9090
  9. Restart IDM.

Header host filter

As an alternative to specifying authorized ports in step 8, you can add a filter to the IG route to replace the header host with the IDM host and port, for example:

{   "name": "HostFilter",    "type": "HeaderFilter",    "config": {      "messageType": "REQUEST",      "remove": "host",      "add": {        "host": ""      }  }

It is up to you whether you choose to make the configuration change in IDM or IG.

See Also

Delegated administration

Authorization and roles

Related Training


Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.