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
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 asAGENT_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
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:
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 IDMconf/
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 theagent.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 theagent.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 theagent.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 adjustagent.max_http_size
oragent.max_frame_bytes
in your RCS Agent settings if, for example, you see amax frame length has been exceeded
message in the RCS Agent log.
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 examplewss://localhost:8787/rcs
), ending with the endpoint specified in theagent.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 ifconnectorserver.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 theagent.rcs_principal
property in the RCS AgentDefault.properties
file. Configureconnectorserver.password
to match theagent.rcs_secret
property.If using OAuth2, configure
connectorserver.tokenEndpoint
,connectorserver.clientId
,connectorserver.clientSecret
, andconnectorserver.scope
to match the settings in the RCS AgentDefault.properties
file foragent.token_introspect_uri
,agent.token_client_id
,agent.token_client_secret
, andagent.required_scopes
(respectively).