Configure IDM to Connect to a Remote Connector Server
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
You configure a connector server to run in one of two modes:
- Server mode
In server mode, IDM initiates the connection to the remote connector server. Run the connector server in server mode if IDM can initiate the connection and has access through any firewalls.
The following diagram shows a connector server in server mode:
- Client mode
In client mode, IDM waits for the remote connector server to initiate a connection. Run the connector server in client mode if your data store is "on prem" and protected by a firewall or DMZ. In this case, IDM cannot initiate a connection to the connector server.
The following diagram shows a connector server in client mode:
For failover purposes, you can configure a group of remote connector servers, in either server or client mode. Failover is particularly important when you configure a connector server in client mode because IDM has no way of knowing whether the connector server is available.
This example shows how to retrieve the connector server types over REST:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "http://localhost:8080/openidm/system?_action=availableConnectorServers"{ "connectorServers": [ { "displayName": "Remote Connector Server", "systemType": "provisioner.openicf", "type": "remoteConnectorServer" }, { "displayName": "Remote Connector Servers Group", "systemType": "provisioner.openicf", "type": "remoteConnectorServersGroup" }, { "displayName": "Remote Connector Server in Client mode", "systemType": "provisioner.openicf", "type": "remoteConnectorClient" }, { "displayName": "Remote Connector Servers Group in Client mode", "systemType": "provisioner.openicf", "type": "remoteConnectorClientsGroup" } ] }
Configure a Remote Connector Server in Server Mode
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
The following commands configure a remote connector server in server mode:
To generate the core configuration, use the createConnectorServerCoreConfig action on the system endpoint. Include at least the remote connector server type (remoteConnectorServer) and the systemType in the JSON payload. The systemType is always provisioner.openicf, regardless of the connector server type:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "type" : "remoteConnectorServer", "systemType" : "provisioner.openicf" }' \ "http://localhost:8080/openidm/system?_action=createConnectorServerCoreConfig"{ "displayName": "", "proxyPassword": null, "proxyHost": null, "enabled": true, "useSSL": false, "proxyPort": 8080, "port": "", "name": "", "host": "", "proxyUser": null, "housekeepingInterval": 600, "connectionGroupCheckInterval": 900, "pingPongInterval": 300, "key": "password", "webSocketConnections": 2 }
IDM returns the required configuration properties for a connector server in server mode. The configuration that is returned is not functional. It does not contain the specific property values, such as the host name and port of the remote connector server.
Use the output returned in the previous example to create your complete connector server configuration. Specify at least the host and port of the remote connector server, and use a PUT request on the config endpoint. Note that this step creates a connector server configuration on IDM. The values of these properties must match the connector server configuration specified in the ConnectorServer.properties file on the remote connector server:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "_id": "provisioner.openicf.connectorinfoprovider", "connectorsLocation": "connectors", "enabled": true, "remoteConnectorServers": [ { "type": "remoteConnectorServer", "displayName": "Remote Connector Server 1", "proxyPassword": null, "proxyHost": null, "enabled": true, "useSSL": false, "proxyPort": 8080, "port": 8759, "name": "rcs1", "host": "rcs.example.com", "proxyUser": null, "housekeepingInterval": 600, "connectionGroupCheckInterval": 900, "pingPongInterval": 300, "key": "Passw0rd", "webSocketConnections": 2 } ] }' \ "http://localhost:8080/openidm/config/provisioner.openicf.connectorinfoprovider"{ "_id": "provisioner.openicf.connectorinfoprovider", "connectorsLocation": "connectors", "enabled": true, "remoteConnectorServers": [ { "type": "remoteConnectorServer", "displayName": "Remote Connector Server 1", "proxyPassword": null, "proxyHost": null, "enabled": true, "useSSL": false, "proxyPort": 8080, "port": 8759, "name": "rcs1", "host": "rcs.example.com", "proxyUser": null, "housekeepingInterval": 600, "connectionGroupCheckInterval": 900, "pingPongInterval": 300, "key": { "$crypto": { "type": "x-simple-encryption", "value": { "cipher": "AES/CBC/PKCS5Padding", "stableId": "openidm-sym-default", "salt": "3Mq1UJuZXqANx2AzUtbFbg==", "data": "4WHBEI3nSVWJ2DfIs2dPZg==", "keySize": 16, "purpose": "idm.config.encryption", "iv": "BvFAQ4sjwJCNY2e7WZPkGw==", "mac": "ximBz/BlqC8SEsBTuYQX5Q==" } } }, "webSocketConnections": 2 } ] }
Configure a Remote Connector Server in Client Mode
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
In client mode, the connector server initiates the TCP connection to IDM. Therefore, IDM doesn't need any host, port or other connection details to the connector server.
To generate the core configuration, use the createConnectorServerCoreConfig action on the system endpoint. Include at least the remote connector server type (remoteConnectorClient) and the systemType in the JSON payload. The systemType is always provisioner.openicf, regardless of the connector server type:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "type" : "remoteConnectorClient", "systemType" : "provisioner.openicf" }' \ "http://localhost:8080/openidm/system?_action=createConnectorServerCoreConfig"{ "displayName": "", "name": "", "enabled": true, "useSSL": false }
IDM returns the basic configuration properties for a connector server in client mode. The configuration that is returned is not functional. It does not contain the required configuration property values, such as the name the remote connector server.
Use the output returned in the previous example to create your complete connector server configuration. Specify at least the name of the remote connector server, and use a PUT request on the config endpoint. Note that this step creates a connector server configuration on IDM. The values of these properties must match the connector server configuration specified in the ConnectorServer.properties file on the remote connector server:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "_id": "provisioner.openicf.connectorinfoprovider", "connectorsLocation": "connectors", "enabled": true, "remoteConnectorClients": [ { "displayName": "On premise 1", "name": "onprem", "enabled": true } ] }' \ "http://localhost:8080/openidm/config/provisioner.openicf.connectorinfoprovider"{ "_id": "provisioner.openicf.connectorinfoprovider", "connectorsLocation": "connectors", "enabled": true, "remoteConnectorClients": [ { "displayName": "On premise 1", "name": "onprem", "enabled": true, "useSSL": false } ] }
Configure Failover Between Remote Connector Servers
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
To prevent the connector server from being a single point of failure, you can specify a list of remote connector servers that the connector can target. To set up a failover configuration, you create either a remoteConnectorServersGroup or a remoteConnectorClientsGroup and list the remote connector servers. The connector attempts to contact the first connector server in the list. If that connector server is down, it proceeds to the next connector server.
This example configures a remoteConnectorServersGroup that lists two remote connector servers, on hosts remote-host-1 and remote-host-2. The connector servers are listed, by their name property. You can configure multiple groups and multiple servers per group.
First, generate the core configuration to obtain the required properties:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "type" : "remoteConnectorServersGroup", "systemType" : "provisioner.openicf" }' \ "http://localhost:8080/openidm/system?_action=createConnectorServerCoreConfig"{ "displayName": "", "name": "", "serversList": [], "algorithm": "failover" }
Use the output returned in the previous example to create your connector server group configuration. Use a PUT request on the config endpoint:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "_id": "provisioner.openicf.connectorinfoprovider", "connectorsLocation": "connectors", "enabled": true, "remoteConnectorServers": [ { "type": "remoteConnectorServersGroup", "displayName": ".NET Failover Group", "name" : "dotnet-ha", "algorithm" : "failover", "serversList" : [ {"name": "remote-host-1"}, {"name": "remote-host-2"} ] } ] }' \ "http://localhost:8080/openidm/config/provisioner.openicf.connectorinfoprovider"{ "_id": "provisioner.openicf.connectorinfoprovider", "connectorsLocation": "connectors", "enabled": true, "remoteConnectorServers": [ { "type": "remoteConnectorServersGroup", "displayName": ".NET Failover Group", "name": "dotnet-ha", "algorithm": "failover", "serversList": [ { "name": "remote-host-1" }, { "name": "remote-host-2" } ] } ] }
The algorithm can be either failover or roundrobin. If the algorithm is failover, requests are always sent to the first connector server in the list, unless it is unavailable; in which case, requests are sent to the next connector server in the list. If the algorithm is roundrobin, requests are distributed equally between the connector servers in the list, in the order in which they are received.
Your connector configuration (provisioner.openicf-connector-name.json) references the remote connector server group, rather than a single remote connector server. For example, the following excerpt of a PowerShell connector configuration file references the dotnet-ha connector server group created in the previous example:
{
"connectorRef" : {
"bundleName" : "MsPowerShell.Connector",
"connectorName" : "Org.ForgeRock.OpenICF.Connectors.MsPowerShell.MsPowerShellConnector",
"connectorHostRef" : "dotnet-ha",
"bundleVersion" : "[1.4.2.0,1.5.0.0)"
},
...
} This example configures a remoteConnectorClientsGroup that lists two remote connector servers, on hosts remote-host-1 and remote-host-2. The connector servers are listed, by their name property. You can configure multiple groups and multiple servers per group.
First, generate the core configuration to obtain the required properties:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "type" : "remoteConnectorClientsGroup", "systemType" : "provisioner.openicf" }' \ "http://localhost:8080/openidm/system?_action=createConnectorServerCoreConfig"{ "displayName": "", "name": "", "serversList": [], "algorithm": "failover" }
Use the output returned in the previous example to create your connector server group configuration. Use a PUT request on the config endpoint:
curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "_id": "provisioner.openicf.connectorinfoprovider", "connectorsLocation": "connectors", "enabled": true, "remoteConnectorClients": [ { "type": "remoteConnectorClientsGroup", "displayName": ".NET Failover Group", "name" : "dotnet-ha", "algorithm" : "failover", "serversList" : [ {"name": "remote-host-1"}, {"name": "remote-host-2"} ] } ] }' \ "http://localhost:8080/openidm/config/provisioner.openicf.connectorinfoprovider"{ "_id": "provisioner.openicf.connectorinfoprovider", "connectorsLocation": "connectors", "enabled": true, "remoteConnectorClients": [ { "type": "remoteConnectorClientsGroup", "displayName": ".NET Failover Group", "name": "dotnet-ha", "algorithm": "failover", "serversList": [ { "name": "remote-host-1" }, { "name": "remote-host-2" } ] } ] }
The algorithm can be either failover or roundrobin. If the algorithm is failover, requests are always sent to the first connector server in the list, unless it is unavailable; in which case, requests are sent to the next connector server in the list. If the algorithm is roundrobin, requests are distributed equally between the connector servers in the list, in the order in which they are received.
Your connector configuration (provisioner.openicf-connector-name.json) references the remote connector server group, rather than a single remote connector server. For example, the following excerpt of a PowerShell connector configuration file references the dotnet-ha connector server group created in the previous example:
{
"connectorRef" : {
"bundleName" : "MsPowerShell.Connector",
"connectorName" : "Org.ForgeRock.OpenICF.Connectors.MsPowerShell.MsPowerShellConnector",
"connectorHostRef" : "dotnet-ha",
"bundleVersion" : "[1.4.2.0,1.5.0.0)"
},
...
}