Install a Remote Connector Server

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

There are two types of remote connector servers: .NET and Java.

You need a .NET connector server if you are using the PowerShell connector to connect to an identity store. IDM communicates with the .NET connector server over the network, and the connector server runs the Powershell connector.

You need a Java connector server if your Java connector needs to run in a different JVM to IDM.

These procedures describe how to set up both connector server types on a remote host.

Set Up a .NET Connector Server

The .NET connector server is distributed in two file formats:

openicf-version-dotnet.msi is a wizard that installs the connector server as a Windows service.
openicf-version-dotnet.zip is just a bundle of the files required to run the connector server.

Depending on how you want to install the connector server, download the corresponding file from the ForgeRock BackStage download site.
Follow one of these procedures to install the connector server:
Install the Connector Server as a Service
1. Double-click the openicf-version-dotnet.msi installation file and complete the wizard.
  You must run the wizard as a user who has permission to start and stop a Windows service; otherwise, the service will not start.
  Select Typical as the Setup Type.
  When the wizard has completed, the connector server is installed as a Windows service.
2. Open the Microsoft Services Console and make sure that the connector server is listed there.
  The name of the service is OpenICF Connector Server, by default.
3. Make sure that the connector server is not currently running. If it is running, use the Microsoft Services Console to stop it.
Unpack the Connector Server Zip
1. If you do not want to run the connector server as a Windows service, download and extract the openicf-version-dotnet.zip file.
2. If you have already extracted the .zip file and then decide to run the connector server as a service, install the service manually with the following command:
  .\ConnectorServerService.exe /install /serviceName service-name
At the command prompt, change to the directory where the connector server was installed, for example:
```
cd "c:\Program Files (x86)\ForgeRock\OpenICF"
```
(Optional) By default, the connector server outputs log messages to a file named connectorserver.log, in the \path\to\openicf directory. To change the location of the log file, set the initializeData parameter in the configuration file. The following example sets the log directory to C:\openicf\logs\connectorserver.log:
```
<add name="file" type="System.Diagnostics.TextWriterTraceListener" initializeData="C:\openicf\logs\connectorserver.log" traceOutputOptions="DateTime">
  <filter type="System.Diagnostics.EventTypeFilter" initializeData="Information"/>
</add>
```
Run the ConnectorServerService /setKey command to set a secret key for the connector server. The key can be any string value. This example sets the secret key to Passw0rd:
```
ConnectorServerService /setKey Passw0rd
Key has been successfully updated.
```
This key is used by clients connecting to the connector server. The key that you set here must also be set in the IDM remote connector server configuration.
Edit the connector server configuration.
The connector server configuration is saved in a file named ConnectorServerService.exe.Config (in the directory where the connector server is installed).
Check and edit this file, as necessary, to reflect your installation. Specifically, verify that the baseAddress reflects the host and port on which the connector server is installed:
```
<system.serviceModel>
  <services>
    <service name="Org.ForgeRock.OpenICF.Framework.Service.WcfServiceLibrary.WcfWebsocket">
      <host>
        <baseAddresses>
          <add baseAddress="http://0.0.0.0:8759/openicf" />
        </baseAddresses>
      <host>
    </service>
  </services>
</system.serviceModel>
```
The baseAddress specifies the host and port on which the connector server listens, and is set to http://0.0.0.0:8759/openicf by default. If you set a host value other than the default 0.0.0.0, connections from all IP addresses other than the one specified are denied.
If Windows firewall is enabled, you must create an inbound port rule to open the TCP port for the connector server (8759 by default). If you do not open the TCP port, IDM won't be able to contact the connector server. For more information, see the corresponding Microsoft documentation.

(Optional) Configure the connector server to use SSL:

Open a Powershell terminal as a user with administrator privileges, then change to the ICF installation directory:
```
cd 'C:\Program Files (x86)\ForgeRock\OpenICF'
```

Use an existing CA certificate, or use the New-SelfSignedCertificate cmdlet to create a self-signed certificate:

New-SelfSignedCertificate -DnsName "dotnet", "dotnet.example.com" -CertStoreLocation "cert:\LocalMachine\My"
PSParentPath: Microsoft.PowerShell.Security\Certificate::LocalMachine\My

Thumbprint                                Subject
----------                                -------
770F531F14AF435E963E14AD82B70A47A4BFFBF2  CN=dotnet

Assign the certificate to the connector server:

.\ConnectorServerService.exe /setCertificate
Select certificate you want to use:
Index  Issued To                Thumbprint
-----  ---------                -------------------------

   0)  dotnet                    770F531F14AF435E963E14AD82B70A47A4BFFBF2

0
Certificate Thumbprint has been successfully updated to 770F531F14AF435E963E14AD82B70A47A4BFFBF2.

Bind the certificate to the connector server port (8759 by default). To bind the certificate:
1. Use the New-Guid cmdlet to generate a new UUID:
```
New-Guid
Guid
----
0352cf0f-2e7a-4aee-801d-7f27f8344c77
```
2. Enter the netsh http console and add the certificate thumbprint generated in the previous step, and the UUID that you have just generated:
```
netsh
netsh>http
netsh http>add sslcert ipport=0.0.0.0:8759 certhash=770F5...FFBF2 appid={0352c...4c77}
SSL Certificate successfully added
```

Change the connector server configuration (in the ConnectorServerService.exe.Config file) to use HTTPS and not HTTP.

Change baseAddress="http..." to baseAddress="https...":

<host>
  <baseAddresses>
    ...
    <add baseAddress="https://0.0.0.0:8759/openicf"/>
  </baseAddresses>
</host>

Change httpTransport to httpsTransport:

<httpsTransport authenticationScheme="Basic" realm="OpenICF">
  <webSocketSettings transportUsage="Always" createNotificationOnConnection="true" .../>
</httpsTransport>

Export the certificate:
1. Launch the certificate management MMC (certlm.msc).
2. Right-click the dotnet certificate, and select All Tasks > Export to launch the Certificate Export Wizard.
3. Select Next > No, do not export the private key > DER encoded binary X.509 (.CER) > Next.
4. Save the file in an accessible location (for example, C:\Users\Administrator\Desktop\dotnet.cer), and click Finish.

Import the certificate into the IDM truststore:

Transfer the certificate from the Windows machine to the machine that's running IDM.

Change to the openidm/security directory and use the Java keytool command to import the certificate:

cd /path/to/openidm/security
keytool -import -alias dotnet -file ~/Downloads/dotnet.cer -keystore ./truststore
Enter keystore password: changeit
Owner: CN=dotnet
Issuer: CN=dotnet
Serial number: 1e3af7baed05ce834da5cd1bf1241835
Valid from: Tue Aug 08 15:58:32 SAST 2017 until: Wed Aug 08 16:18:32 SAST 2018
Certificate fingerprints:
	 MD5:  D1:B7:B7:46:C2:59:1A:3C:94:AA:65:99:B4:43:3B:E8
	 SHA1: 77:0F:53:1F:14:AF:43:5E:96:3E:14:AD:82:B7:0A:47:A4:BF:FB:F2
	 SHA256: C0:52:E2:E5:E5:72:9D:69:F8:11:4C:B8:4C:E4:E3:1C:19:95:86:19:70:E5:31:FA:D8:81:4B:F2:AC:30:9C:73
	 Signature algorithm name: SHA256withRSA
	 Version: 3

...

Trust this certificate? [no]: yes
Certificate was added to keystore

When you configure the remote connector server, remember to set "useSSL": true.

(Optional) Check the trace settings under system.diagnostics in the connector server configuration file:

<system.diagnostics>
  <trace autoflush="true" indentsize="4">
    <listeners>
      <remove name="Default" />
      <add name="console" />
      <add name="file" />
    </listeners>
  </trace>
  <sources>
    <source name="ConnectorServer" switchName="switch1">
      <listeners>
        <remove name="Default" />
        <add name="file" />
      </listeners>
    </source>
  </sources>
  <switches>
    <add name="switch1" value="Information" />
  </switches>
  <sharedListeners>
    <add name="console" type="System.Diagnostics.ConsoleTraceListener" />
    <add name="file" type="System.Diagnostics.TextWriterTraceListener"
            initializeData="logs\ConnectorServerService.log"
            traceOutputOptions="DateTime">
        <filter type="System.Diagnostics.EventTypeFilter" initializeData="Information" />
    </add>
  </sharedListeners>
</system.diagnostics>

The connector server uses the standard .NET trace mechanism. For more information about tracing options, see Microsoft's .NET documentation for System.Diagnostics.

The default trace settings are a good starting point. For less tracing, set the EventTypeFilter's initializeData to Warning or Error. For very verbose logging, set the value to Verbose or All. The logging level has a direct effect on the Connector server performance, so take care when setting this level.

Start the .NET connector server in one of the following ways:
- Start the server as a Windows service, by using the Microsoft Services Console.
  Locate the connector server service (OpenICF connector server), and click Start the service or Restart the service.
  The service runs with the credentials of the "run as" user (System, by default).
- Start the server as a Windows service, by using the command line.
  In the Windows Command Prompt, run the following command:
```
net start ConnectorServerService
```
  To stop the service, run the following command:
```
net stop ConnectorServerService
```
- Start the server without using Windows services.
  In the Windows Command Prompt, change to the connector server installation directory. The default location is c:\> cd "c:\Program Files (x86)\ForgeRock\OpenICF".
  Start the server with the following command:
```
ConnectorServerService.exe /run
```
  Note
  This command starts the connector server with the credentials of the current user. It does not start the server as a Windows service.

Set Up a Java Connector Server

Install a Java Connector Server on Unix/Linux

Download the ICF Java connector server from the ForgeRock BackStage download site.
Change to the appropriate directory and unpack the .zip file. The following command unzips the file in the current directory:
```
unzip openicf-zip-1.5.20.12.zip
```
Change to the openicf directory:
```
cd path/to/openicf
```
Review the ConnectorServer.properties file in the /path/to/openicf/conf directory, and adjust it to suit your deployment. For a complete list of properties in that file, see Remote Connector Server Properties.
In server mode, the connector server uses a connectorserver.key property to authenticate the connection. The default value of the key is a hashed value of the string changeit. You cannot set this property directly in the configuration file. To change its value, use the command ConnectorServer.sh /setKey. This example sets the key value to Passw0rd:
```
/path/to/openicf/bin/ConnectorServer.sh /setKey Passw0rd
Key has been successfully updated.
```
Start the Java connector server:
```
/path/to/openicf/bin/ConnectorServer.sh /run
```
The connector server is now running, and listening on port 8759, by default.
Log files are available in the /path/to/openicf/logs directory.
```
ls logs/
Connector.log  ConnectorServer.log  ConnectorServerTrace.log
```
To stop the Java connector server, press CTRL + C, or q in the terminal where you started the server.

Install a Java Connector Server on Windows

Download the ICF Java connector server from the ForgeRock BackStage download site.
Change to the appropriate directory and unpack the .zip file.
In a Command Prompt window, change to the openicf directory:
```
C:\>cd C:\path\to\openicf\bin
```
Review the ConnectorServer.properties file in the \path\to\openicf\conf directory, and adjust it to suit your deployment. For a complete list of properties in that file, see Remote Connector Server Properties.
In server mode, the connector server uses a connectorserver.key property to authenticate the connection. The default value of the key is a hashed value of the string changeit. You cannot set this property directly in the configuration file. To change its value, use the ConnectorServer.bat /setKey command. This example sets the key value to Passw0rd:
```
c:\path\to\openicf>bin\ConnectorServer.bat /setKey Passw0rd
lib\framework\connector-framework.jar;lib\framework\connector-framework-internal
.jar;lib\framework\groovy-all.jar;lib\framework\icfl-over-slf4j.jar;lib\framework
\slf4j-api.jar;lib\framework\logback-core.jar;lib\framework\logback-classic.jar
```
You can either run the Java connector server as a Windows service, or start and stop it from the command line:
- To install the Java connector server as a Windows service, run the following command:
```
c:\path\to\openicf>bin\ConnectorServer.bat /install
```
  If you install the connector server as a Windows service, you can use the Microsoft Services Console to start, stop, and restart the service. The Java Connector Service is named OpenICFConnectorServerJava.
  To uninstall the Java connector server as a Windows service, run the following command:
```
c:\path\to\openicf>bin\ConnectorServer.bat /uninstall
```
- To start the Java connector server from the command line, enter the following command:
```
c:\path\to\openicf>bin\ConnectorServer.bat /run
```
The connector server is now running, and listening on port 8759, by default.
Log files are available in the \path\to\openicf\logs directory.
To stop the Java connector server, press ^ + C.

Remote Connector Server Properties

Some of these configuration properties are only applicable if you configure the connector server in client mode. For more information, see "Configure IDM to Connect to a Remote Connector Server".

Note that all configuration properties are prefixed with connectorserver. in the configuration file. The prefixes are not shown here so that the table is easier to read.

Property	RCS Mode (Server or Client)	Description	Example
`url`	Client	URL of the server on which IDM runs.	`wss://openidm.example.com:8443/openicf` ^[a]
`proxyHost`	Client	Proxy server host.
`proxyPort`	Client	Proxy server port number.
`proxyPrincipal`	Client	Proxy server principal.
`proxyPassword`	Client	Proxy server password.
`housekeepingInterval`	Client	WebSocket connections housekeeping interval, in seconds.	600
`groupCheckInterval`	Client	WebSocket groups check interval, in seconds.	900
`webSocketConnections`	Client	Number of WebSocket connections to open.	2
`connectionTtl`	Client	Time to live of a WebSocket connection, in seconds.	600
`tokenEndpoint`	Client	Token endpoint from which to retrieve the access token, if you are using OAuth2 to authenticate against AM.	`https://am.example.com/am/oauth2/realms/root/access_token`
`scope`	Client	OAuth2 token scope, if you are using OAuth2 to authenticate against AM.	fr:idm:*
`clientId`	Client	OAuth2 Client ID for which to request an access token. ^[b]	connectorServer
`clientSecret`	Client	OAuth2 Client Secret.	openidm
`connectorServerName`	Both	Name of the remote connector client. This name is used to identify the remote connector server in the list of connector reference objects. The name must be lower case alphanumeric characters (`^[a-z0-9]*$`), and must match the `name` property in the `provisioner.openicf.connectorinfoprovider.json` file on your IDM server.	rcs1
`pingPongInterval`	Both	WebSocket Ping/Pong interval, in seconds. The purpose of the ping is to keep connections alive (for firewalls or load balancers that honor connections in use). If your firewall or load balancer does not honor connections in use (that is, connections are timed out, regardless of their usage), the ping has no effect and you should disable it. Set this property to `0` to disable the ping.	300
`useSSL`	Both	Whether the connection between IDM and the connector server should be over SSL.	false/true ^[c]
`trustStoreFile`	Both	The IDM truststore file. You do not need to set this property if the IDM certificate is a CA-signed certificate.	`security/truststore.pkcs12`
`trustStoreType`	Both	The IDM truststore type. You do not need to set this property if the IDM certificate is a CA-signed certificate.	`PKCS12`
`trustStorePass`	Both	The IDM truststore password. You do not need to set this property if the IDM certificate is a CA-signed certificate.	changeit
`keyStoreFile`	Both	The IDM keystore file. You do not need to set this property if the IDM certificate is a CA-signed certificate.	`security/keyStore.pkcs12`
`keyStoreType`	Both	The IDM keystore type. You do not need to set this property if the IDM certificate is a CA-signed certificate.	`PKCS12`
`keyStorePass`	Both	The IDM keystore password. You do not need to set this property if the IDM certificate is a CA-signed certificate.	changeit
`keyPass`	Both	The IDM certificate password. You do not need to set this property if the IDM certificate is a CA-signed certificate.	changeit
`libDir`	Both	Directory on the connector server host in which connector library file dependencies are located (relative to `/path/to/openicf/`).	`lib`
`bundleDir`	Both	Directory on the connector server host in which connector .jar files are located (relative to `/path/to/openicf/`).	`connectors`
`loggerClass`	Both	The connector server logger class.	`org.forgerock.openicf.common.logging.slf4j.SLF4JLog`
`port`	Server	Port on which the connector server listens for the connection from IDM.	8759
`principal`	Server	Principal to authenticate to the connector server. This property is not used if the connector server obtains its access token through ForgeRock® Access Management (AM) (which is the case when IDM is running in ForgeRock Identity Cloud).	anonymous
`password`	Server	Password to authenticate to the connector server. This property is not used if the connector server obtains its access token through AM (which is the case when IDM is running in ForgeRock Identity Cloud).	changeit
^[a] Note the `wss` (WebSocket) transport protocol and the `openicf` endpoint. Important ^[b] If the connector server is authenticating against AM, you must update your IDM authentication configuration (in `conf/authentication.json`). Add a user mapping for this client ID in the `rsFilter` authentication module configuration. For more information, see "rsFilter". ^[c] In Client mode (when the connection uses `wss`), the connection must be over SSL, so this property must be set to `true`.