Configure RCS using the RCS Agent

The RCS Agent is a smart websocket proxy that serves as a connection between Identity Cloud and RCS instances. The RCS Agent is an optional component when configuring an RCS installation. It reduces the amount of configuration required, since both Identity Cloud 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 Identity Cloud cluster, since RCS no longer needs to know each of the Identity Cloud instances.

Diagram shows Identity Cloud and RCS both connecting to an RCS Agent.

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

  • Use of the RCS Agent requires Identity Cloud 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 Identity Cloud and RCS. You can download it from the early access 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 Identity Cloud, RCS, and the RCS Agent. The RCS Agent acts as a proxy server, so both Identity Cloud 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 Identity Cloud connector server configuration, and the port included in the RCS connectorserver.url property.

    agent.idm_route

    The endpoint Identity Cloud will use to attempt to communicate with the RCS Agent. This must match the websocketPath in the Identity Cloud 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 Identity Cloud 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 Identity Cloud 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 Identity Cloud 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 RCS to use SSL, see "Secure the Connection to the RCS With SSL".

    agent.idm_principal

    The account name Identity Cloud uses to connect to the RCS Agent. This should match principal in the Identity Cloud connector server configuration.

    agent.idm_secret

    The password Identity Cloud uses to connect to the RCS Agent. This should match key in the Identity Cloud 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.

# 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 Identity Cloud to use the RCS Agent
  1. Create the connector server core configuration in Identity Cloud:

    curl \
    --header "Authorization: Bearer *token*" \
    --header "Accept-API-Version: resource=1.0" \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
      "type" : "remoteConnectorServer",
      "systemType" : "provisioner.openicf"
    }' \
    "https://tenant-name.forgeblocks.com/openidm/system?_action=createConnectorServerCoreConfig"
  2. Update the connector server configuration in Identity Cloud with the details to connect to the RCS Agent:

    curl \
    --header "Authorization: Bearer *token*" \
    --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
        }
      ]
    }' \
    "https://tenant-name.forgeblocks.com/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
        }
      ]
    }

    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 Identity Cloud 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 Identity Cloud, which uniquely identifies each Identity Cloud 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
  1. 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 Identity Cloud and RCS, this must only have one address, even if you are running Identity Cloud 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.

  2. 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).

Read a different version of :