Configure RCS using the RCS Agent

The RCS Agent is a smart websocket proxy that serves as a connection between IDM and RCS instances. The RCS Agent is an optional component when configuring an RCS installation. It reduces the amount of configuration required, since both IDM and RCS only need to know the address of the RCS Agent (a single point of ingress). This also means it is easier to scale an IDM cluster, since RCS no longer needs to know each of the IDM instances.

There are some current limitations where the RCS Agent can't be used:

Use of the RCS Agent requires IDM version 7.1 or newer, and RCS version 1.5.20.0 or newer. If you are attempting to connect to an older version of either of these products, the RCS Agent is not available.
The .NET version of RCS does not currently support the RCS Agent.

Install the RCS Agent

The RCS Agent is a separate application from IDM and RCS. You can download it from the ForgeRock BackStage download site.

Using Docker to deploy and manage the RCS Agent is recommended, and a Dockerfile to create a Docker image is included in the downloaded .zip file. To build the Docker image, in the RCS install directory run:

docker build . -t rcs-agent:latest

Once the Docker image has been built, start the RCS Agent:

docker run -t -i -p 8787:8787 -m 512M \
-e ARGS="-p /Default.properties" \
-e LOGGING_PROPERTIES="/logging.properties" \
-v ${PWD}/Default.properties:/Default.properties \
-v ${PWD}/logging.properties:/logging.properties \
rcs-agent:latest

You can also use the RCS Agent without Docker, by running the .jar file directly:

java \
-server \
-XX:MaxRAMPercentage=80 \
-XX:InitialRAMPercentage=80 \
-XX:MaxTenuringThreshold=1 \
-Djava.util.logging.config.file=logging.properties \
-XshowSettings:vm \
-jar connector-framework-agent.jar \
org.forgerock.openicf.framework.agent.AgentServer -p Default.properties
VM settings:
Max. Heap Size (Estimated): 12.80G
Using VM: OpenJDK 64-Bit Server VM

Mar 17, 2021 5:17:20 PM org.forgerock.openicf.framework.agent.AgentServer start
INFO: Agent starting :8787

Configure the RCS Agent

Using the RCS Agent requires configuration in IDM, RCS, and the RCS Agent. The RCS Agent acts as a proxy server, so both IDM and RCS are configured as clients, connecting to the RCS Agent.

Configure the RCS Agent

Configure the RCS Agent Default.properties file:
agent.port
Port number for the RCS Agent. This should match the port specified in the IDM connector server configuration, and the port included in the RCS connectorserver.url property.
agent.idm_route
The endpoint IDM will use to attempt to communicate with the RCS Agent. This must match the websocketPath in the IDM connector server configuration.
agent.rcs_route
The endpoint RCS will use to attempt to communicate with the RCS Agent. This must match the endpoint included in connectorserver.url in the RCS properties.
agent.health_route
The RCS Agent endpoint used to report system health. For example, in a Kubernetes deployment, this route can be polled by Kubernetes to monitor the status of the RCS Agent.
agent.max_http_size
The maximum size (in bytes) of an HTTP request the RCS Agent will accept. This refers to the initiating requests for IDM and RCS: once a connection is established, a websocket connection is used instead of HTTP.
agent.max_frame_bytes
The maximum size (in bytes) of a websocket frame the RCS Agent will accept.
agent.handshake_timeout_millis
How long the RCS Agent should wait to complete an initiating handshake with an IDM or RCS instance before timing out.
agent.shutdown_timeout_millis
The maximum amount of time for the RCS Agent to perform a graceful shutdown. A graceful shutdown helps IDM instances recover more smoothly during an active recon or sync. If the RCS Agent still hasn't shut down by the end of the timeout, it will force a shutdown.
agent.ssl_enabled
Boolean property enabling or disabling SSL on the RCS Agent. If the RCS Agent is in a protected network behind a reverse proxy or load balancer, it may not be necessary to have this enabled (such as in some cloud environments). If the RCS Agent is exposed directly, or passed through in such a way that the SSL connection is expected to terminate at the Agent, this should be enabled. For more information about configuring IDM to use SSL, see "Use TLS/SSL". For more information about configuring RCS to use SSL, see "Secure the Connection to the RCS With SSL".
agent.idm_principal
The account name IDM uses to connect to the RCS Agent. This should match principal in the IDM connector server configuration.
agent.idm_secret
The password IDM uses to connect to the RCS Agent. This should match key in the IDM connector server configuration.
agent.rcs_principal
The account name RCS uses to connect to the RCS Agent. This should match connectorserver.principal in the RCS properties file. Only used when using basic authentication.
agent.rcs_secret
The password RCS uses to connect to the RCS Agent. This should match connectorserver.password in the RCS properties file. Only used when using basic authentication.
agent.token_introspect_uri
This is the address the RCS Agent uses to validate the access token provided by an RCS instance. Part of OAuth2 authentication. If you plan to use basic authentication instead of OAuth2, do not configure this property, as OAuth2 settings will take precedence.
agent.token_client_id
This is the client ID the RCS Agent uses to validate the access token provided by an RCS instance. Part of OAuth2 authentication. If you plan to use basic authentication instead of OAuth2, do not configure this property, as OAuth2 settings will take precedence.
agent.token_client_secret
This is the client secret the RCS Agent uses to validate the access token provided by an RCS instance. Part of OAuth2 authentication. If you plan to use basic authentication instead of OAuth2, do not configure this property, as OAuth2 settings will take precedence.
agent.required_scopes
These are the scopes RCS needs to include in its access token to authenticate with the RCS Agent. If multiple scopes are needed, separate each scope with a space. Part of OAuth2 authentication. If you plan to use basic authentication instead of OAuth2, do not configure this property, as OAuth2 settings will take precedence.
agent.truststore_file
This is the local path to the truststore file the RCS Agent uses. This is necessary if you are connecting to AM for validating access tokens, and AM is using a self-signed certificate for HTTPS connections. Part of SSL configuration. If AM's SSL certificate is signed by certificate authorities the Java JDK already trusts, then this does not need to be configured.
agent.truststore_secret
Part of SSL configuration. This is the secret key the RCS Agent uses to access the truststore file. If you are using OAuth2, the truststore file must be updated to trust the certificate for the server in agent.token_introspect_uri. Part of SSL configuration. If AM's SSL certificate is signed by certificate authorities the Java JDK already trusts, then this does not need to be configured.
agent.keystore_file
This is the local path to the keystore file the RCS Agent uses. Part of SSL configuration.
agent.keystore_secret
This is the secret key the RCS Agent uses to access the keystore file. Part of SSL configuration.
Note
To better support containerized deployments, any of the agent properties can be specified using environment variables, which will override properties from the config file. Environment variables must be in upper case and use underscores instead of periods. For example, agent.idm_route would be specified as AGENT_IDM_ROUTE.

Sample Default.properties file for the RCS Agent

# NOTE: these are default config properties when no configuration file provided via -p or --properties
agent.port=8787
agent.idm_route=/openicf
agent.rcs_route=/rcs
agent.health_route=/health
agent.max_http_size=65536
agent.max_frame_bytes=20971520
agent.handshake_timeout_millis=10000
agent.shutdown_timeout_millis=25000
agent.ssl_enabled=false

# IDM Basic Auth
agent.idm_principal=idmPrincipal
agent.idm_secret=idmSecret

# RCS Basic Auth
agent.rcs_principal=rcsPrincipal
agent.rcs_secret=rcsSecret

# RCS OAuth 2.0 Bearer Token Auth with AM integration
#agent.token_introspect_uri=http://am:80/am/oauth2/introspect
#agent.token_client_id=rcsAgentClientId
#agent.token_client_secret=rcsAgentClientSecret
#agent.required_scopes=fr:idm:*

# configure truststore to trust self-signed SSL certificate from agent.token_introspect_uri
#agent.truststore_file=/mounted/path/to/truststore/file
#agent.truststore_secret=truststoreSecret

# configure keystore when agent.ssl_enabled=true
#agent.keystore_file=/mounted/path/to/keystore/file
#agent.keystore_secret=keystoreSecret

Configure IDM to use the RCS Agent

Create the connector server core configuration in IDM:

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"

Update the connector server configuration in IDM with the details to connect to the RCS Agent:

Update the connector server configuration in IDM

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": "RCS Agent",
      "enabled": true,
      "useSSL": false,
      "proxyPort": 8080,
      "name": "rcsagent",
      "proxyUser": null,
      "housekeepingInterval": 600,
      "connectionGroupCheckInterval": 900,
      "pingPongInterval": 300,
      "webSocketConnections": 2,
      "host": "localhost",
      "port": 8787,
      "connectionTtl": 3000,
      "websocketPath": "openicf",
      "principal": "idmPrincipal",
      "key": "idmSecret",
      "useAgent": true
    }
  ]
}' \
"http://localhost:8080/openidm/config/provisioner.openicf.connectorinfoprovider"
{
  "_id": "provisioner.openicf.connectorinfoprovider",
  "connectorsLocation": "connectors",
  "enabled": true,
  "remoteConnectorServers": [
    {
      "type": "remoteConnectorServer",
      "displayName": "RCS Agent",
      "enabled": true,
      "useSSL": false,
      "proxyPort": 8080,
      "name": "rcsagent",
      "proxyUser": null,
      "housekeepingInterval": 600,
      "connectionGroupCheckInterval": 900,
      "pingPongInterval": 300,
      "webSocketConnections": 2,
      "host": "localhost",
      "port": 8787,
      "websocketPath": "openicf",
      "principal": "idmPrincipal",
      "key": {
        "$crypto": {
          "type": "x-simple-encryption",
          "value": {
            "cipher": "AES/CBC/PKCS5Padding",
            "stableId": "openidm-sym-default",
            "salt": "c/ydm/RduxT/B8cFLOmLtA==",
            "data": "wk0zEQV5CDCigkevnLBJpQ==",
            "keySize": 16,
            "purpose": "idm.config.encryption",
            "iv": "Kk3lQerGaFLSbNPXeGaO2g==",
            "mac": "cy9QOZTSw2Brf8wGaz/+zg=="
          }
        }
      },
      "useAgent": true
    }
  ]
}

Alternatively, you can create or edit the provisioner.openicf.connectorinfoprovider.json file in your IDM conf/ directory, applying the same changes.

Most configuration remains the same as before, but some properties have specific requirements for use with the RCS Agent:

websocketPath: This is the endpoint in the RCS Agent that IDM will try to communicate with, and must match what is set in the agent.idm_route property in the RCS Agent configuration.
principal: This is the basic authentication username used to connect to the RCS Agent. It must match what is set in the agent.idm_principal property in the RCS Agent configuration.
key: This is the basic authentication password, used to connect to the RCS Agent. It must match what is set in the agent.idm_secret property in the RCS Agent configuration.
useAgent: This is a boolean property to enable use of the RCS Agent as part of the remote connector process.
Important
useAgent must be enabled if you intend to use the RCS Agent.
Note
When using the RCS Agent, an additional header, X-ICF-HostId is sent by IDM, which uniquely identifies each IDM instance. In most cases, no further action is required, but you may need to adjust agent.max_http_size or agent.max_frame_bytes in your RCS Agent settings if, for example, you see a max frame length has been exceeded message in the RCS Agent log.

Configure RCS to use the RCS Agent

In the RCS ConnectorServer.properties file, configure the following properties:
- connectorserver.url: This is the address for the RCS Agent. Since the RCS Agent is acting as the server for both IDM and RCS, this must only have one address, even if you are running IDM as a cluster. This must be a websocket address (for example wss://localhost:8787/rcs), ending with the endpoint specified in the agent.rcs_route property in the RCS Agent configuration.
- connectorserver.hostId: This is the unique identifier for your RCS instance.
  Important
  connectorserver.hostId must be set if you are using the RCS Agent. The connection will be rejected if connectorserver.hostId is not set.
In the RCS ConnectorServer.properties file, configure authentication using either basic auth, or OAuth2 if you are using AM for authentication (such as in the ForgeRock Identity Platform or ForgeRock Identity Cloud).
- If using basic authentication, configure connectorserver.principal to match the settings in the agent.rcs_principal property in the RCS Agent Default.properties file. Configure connectorserver.password to match the agent.rcs_secret property.
- If using OAuth2, configure connectorserver.tokenEndpoint, connectorserver.clientId, connectorserver.clientSecret, and connectorserver.scope to match the settings in the RCS Agent Default.properties file for agent.token_introspect_uri, agent.token_client_id, agent.token_client_secret, and agent.required_scopes (respectively).

Configure RCS using the RCS Agent

Install the RCS Agent

Configure the RCS Agent

Note

Important

Note

Important