Install a Remote Connector Server (RCS)

1. Download and extract the Java RCS from the ForgeRock BackStage download site.

2. Change to the openicf directory:

   cd /path/to/openicf

3. 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 RCS Properties.

   1. In server mode, the RCS 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.

      In client mode, this is not necessary, and may be skipped. For more information about the differences between client mode and server mode, see "Configure a Remote Connector Server (RCS)".

4. Start the Java RCS:

   /path/to/openicf/bin/ConnectorServer.sh /run

   The RCS 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

5. To stop the Java RCS, press CTRL + C, or q in the terminal where you started the server.

1. Download and extract the Java RCS from the ForgeRock BackStage download site.

2. In a Command Prompt window, change to the openicf directory:

   C:\>cd C:\path\to\openicf

3. 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 RCS Properties.

   1. In server mode, the RCS 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
      Key has been successfully updated.

      In client mode, this is not necessary, and may be skipped. For more information about the differences between client mode and server mode, see "Configure a Remote Connector Server (RCS)".

4. You can either run the Java RCS as a Windows service, or start and stop it from the command line:

   • To install the Java RCS as a Windows service, run the following command:

     c:\path\to\openicf>bin\ConnectorServer.bat /install

     If you install the RCS 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 RCS as a Windows service, run the following command:

     c:\path\to\openicf>bin\ConnectorServer.bat /uninstall

   • To start the Java RCS from the command line, enter the following command:

     c:\path\to\openicf>bin\ConnectorServer.bat /run

5. The RCS is now running, and listening on port 8759, by default.

   Log files are available in the \path\to\openicf\logs directory.

6. To stop the Java RCS, press ^ + C.

The .NET RCS is distributed in two file formats:

1. Depending on how you want to install the RCS, download the corresponding file from the ForgeRock BackStage download site.

2. Follow one of these procedures to install the RCS:

   Install the RCS 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 RCS is installed as a Windows service.

   2. Open the Microsoft Services Console and make sure that the RCS is listed there.

      The name of the service is OpenICF Connector Server, by default.

      

   3. Make sure that the RCS is not currently running. If it is running, use the Microsoft Services Console to stop it.

   Unpack the RCS Zip

   1. If you do not want to run the RCS 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 RCS as a service, install the service manually with the following command:

      .\ConnectorServerService.exe /install /serviceName service-name

3. At the command prompt, change to the directory where the RCS was installed, for example:

   cd "c:\Program Files (x86)\ForgeRock\OpenICF"

4. (Optional) By default, the RCS 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>

5. Run the ConnectorServerService /setKey command to set a secret key for the RCS. 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 RCS. The key that you set here must also be set in the IDM RCS configuration.

6. Edit the RCS configuration.

   The RCS configuration is saved in a file named ConnectorServerService.exe.Config (in the directory where the RCS 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 RCS 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>

   Note

   The baseAddress specifies the host and port on which the RCS 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.

   Important

   If Windows firewall is enabled, you must create an inbound port rule to open the TCP port for the RCS (8759 by default). If you do not open the TCP port, IDM won't be able to contact the RCS. For more information, see the corresponding Microsoft documentation.

7. (Optional) Configure the RCS to use SSL:

   1. Open a Powershell terminal as a user with administrator privileges, then change to the ICF installation directory:

      cd 'C:\Program Files (x86)\ForgeRock\OpenICF'

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

   3. Assign the certificate to the RCS:

      .\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.

   4. Bind the certificate to the RCS 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

   5. Change the RCS 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>

   6. 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.

   7. Import the certificate into the IDM truststore:

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

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

   8. When you configure the RCS, remember to set "useSSL": true.

8. (Optional) Check the trace settings under system.diagnostics in the RCS 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 RCS 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 RCS performance, so take care when setting this level.

9. Start the .NET RCS in one of the following ways:

   • Start the server as a Windows service, by using the Microsoft Services Console.

     Locate the RCS 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 RCS 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 RCS with the credentials of the current user. It does not start the server as a Windows service.