From 21a4593b4fe7a0424e10c761abb1e0db818bd121 Mon Sep 17 00:00:00 2001 From: Valera V Harseko Date: Sat, 3 Oct 2026 10:26:56 +0300 Subject: [PATCH 1/3] [#235] Integrator's guide: the connector server has no default key From OpenICF 2.1 the Java connector server ships without a key and refuses to start on none, on the retired default `changeit`, or on an empty key. Drop the "default key value is changeit" text from the Unix and Windows install procedures, say that a key must be set before the first start with /setKey or CONNECTORSERVER_KEY, replace the Passw0rd sample with a placeholder, show connectorserver.key unset in the default properties, and note that the key in provisioner.openicf.connectorinfoprovider.json must match the server's key. Fixes #235 --- .../integrators-guide/chap-resource-conf.adoc | 42 ++++++++++++++----- 1 file changed, 32 insertions(+), 10 deletions(-) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc index a85171148..dff9ff1c3 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc @@ -1417,15 +1417,29 @@ $ unzip openicf-zip-1.7.1.zip $ cd path/to/openicf ---- -. The Java Connector Server uses a `key` property to authenticate the connection. The default key value is `changeit`. To change the value of the secret key, run a command similar to the following. This example sets the key value to `Passw0rd`: +. Set the connector server key before you start the server for the first time. The Java Connector Server uses a `key` property to authenticate connections from OpenIDM. From OpenICF 2.1 on, there is no default key: the packaged `ConnectorServer.properties` file leaves `connectorserver.key` unset, and the server refuses to start until a key is set. The server also refuses the key `changeit`, which earlier versions shipped as the default, and an empty key, because any client could authenticate with either of them. ++ +To set the key, run the `/setKey` command. The command stores a hash of the key, not the key itself, in the `conf/ConnectorServer.properties` file: + [source, console] ---- $ cd /path/to/openicf -$ bin/ConnectorServer.sh /setkey Passw0rd +$ bin/ConnectorServer.sh /setKey "" Key has been successfully updated. ---- ++ +If you run `/setKey` without a key, the command prompts for the key instead, which keeps the key out of the shell history. The command refuses `changeit` and an empty key: it leaves the configuration file unchanged and exits with status `1`. ++ +Alternatively, pass the key in clear text in the `CONNECTORSERVER_KEY` environment variable when you start the server. This suits containers, where the configuration file is not edited. A key set in the `ConnectorServer.properties` file takes precedence over the environment variable: ++ + +[source, console] +---- +$ CONNECTORSERVER_KEY="" bin/ConnectorServer.sh /run +---- ++ +The `key` property in the OpenIDM remote connector server configuration (`provisioner.openicf.connectorinfoprovider.json`) must match the key of the connector server. For more information, see xref:#connector-info-provider-conf["Accessing Remote Connectors"]. . Review the `ConnectorServer.properties` file in the `/path/to/openicf/conf` directory, and make any required changes. By default, the configuration file has the following properties: + @@ -1437,9 +1451,11 @@ connectorserver.libDir=lib connectorserver.usessl=false connectorserver.bundleDir=bundles connectorserver.loggerClass=org.forgerock.openicf.common.logging.slf4j.SLF4JLog -connectorserver.key=xOS4IeeE6eb/AhMbhxZEC37PgtE\= +#connectorserver.key= ---- + +After you run the `/setKey` command, the `connectorserver.key` property holds the hash of your key. ++ The `connectorserver.usessl` parameter indicates whether client connections to the connector server should be over SSL. This property is set to `false` by default. + To secure connections to the connector server, set this property to `true` and set the following properties before you start the connector server: @@ -1489,18 +1505,22 @@ Connector.log ConnectorServer.log ConnectorServerTrace.log C:\>cd C:\path\to\openicf\bin ---- -. If required, secure the communication between OpenIDM and the Java Connector Server. The Java Connector Server uses a `key` property to authenticate the connection. The default key value is `changeit`. +. Set the connector server key before you start the server for the first time. The Java Connector Server uses a `key` property to authenticate connections from OpenIDM. From OpenICF 2.1 on, there is no default key: the packaged `ConnectorServer.properties` file leaves `connectorserver.key` unset, and the server refuses to start until a key is set. The server also refuses the key `changeit`, which earlier versions shipped as the default, and an empty key, because any client could authenticate with either of them. + -To change the value of the secret key, use the `bin\ConnectorServer.bat /setkey` command. The following example sets the key to `Passw0rd`: +To set the key, use the `bin\ConnectorServer.bat /setKey` command. The command stores a hash of the key, not the key itself, in the `conf\ConnectorServer.properties` file: + [source, console] ---- -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 +c:\path\to\openicf>bin\ConnectorServer.bat /setKey "" +Key has been successfully updated. ---- ++ +If you run `/setKey` without a key, the command prompts for the key instead. The command refuses `changeit` and an empty key: it leaves the configuration file unchanged and exits with status `1`. ++ +Alternatively, pass the key in clear text in the `CONNECTORSERVER_KEY` environment variable when you start the server from the command line. A key set in the `ConnectorServer.properties` file takes precedence over the environment variable. If you install the connector server as a Windows service, set the key with `/setKey`: the service does not see a variable that is set only in the Command Prompt window. ++ +The `key` property in the OpenIDM remote connector server configuration (`provisioner.openicf.connectorinfoprovider.json`) must match the key of the connector server. For more information, see xref:#connector-info-provider-conf["Accessing Remote Connectors"]. . Review the `ConnectorServer.properties` file in the `path\to\openicf\conf` directory, and make any required changes. By default, the configuration file has the following properties: + @@ -1512,8 +1532,10 @@ connectorserver.libDir=lib connectorserver.usessl=false connectorserver.bundleDir=bundles connectorserver.loggerClass=org.forgerock.openicf.common.logging.slf4j.SLF4JLog -connectorserver.key=xOS4IeeE6eb/AhMbhxZEC37PgtE\= +#connectorserver.key= ---- ++ +After you run the `/setKey` command, the `connectorserver.key` property holds the hash of your key. . You can either run the Java Connector Server as a Windows service, or start and stop it from the command-line. + From ffc289aa46f9528574b6757059302cb794506fc2 Mon Sep 17 00:00:00 2001 From: Valera V Harseko Date: Mon, 5 Oct 2026 10:53:10 +0300 Subject: [PATCH 2/3] [#235] Qualify the connector server key steps by OpenICF version OpenICF 2.0.4, the latest release, still ships the changeit hash and does not read CONNECTORSERVER_KEY. Mark the refusal, the environment variable and the empty-key properties excerpt as OpenICF 2.1 behaviour, and tell 2.0.x readers to run /setKey before the first start. Use openicf-.zip in the unzip step. --- .../integrators-guide/chap-resource-conf.adoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc index dff9ff1c3..736613b71 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc @@ -1406,7 +1406,7 @@ In certain situations, it might be necessary to set up a remote Java Connector S [source, console] ---- -$ unzip openicf-zip-1.7.1.zip +$ unzip openicf-.zip ---- . Change to the `openicf` directory: @@ -1417,7 +1417,7 @@ $ unzip openicf-zip-1.7.1.zip $ cd path/to/openicf ---- -. Set the connector server key before you start the server for the first time. The Java Connector Server uses a `key` property to authenticate connections from OpenIDM. From OpenICF 2.1 on, there is no default key: the packaged `ConnectorServer.properties` file leaves `connectorserver.key` unset, and the server refuses to start until a key is set. The server also refuses the key `changeit`, which earlier versions shipped as the default, and an empty key, because any client could authenticate with either of them. +. Set the connector server key before you start the server for the first time. The Java Connector Server uses a `key` property to authenticate connections from OpenIDM. From OpenICF 2.1 on, there is no default key: the packaged `ConnectorServer.properties` file leaves `connectorserver.key` unset, and the server refuses to start until a key is set. The server also refuses the key `changeit`, which earlier versions shipped as the default, and an empty key, because any client could authenticate with either of them. In OpenICF 2.0.x and earlier, the packaged file sets `connectorserver.key` to the hash of `changeit` and the server does not read `CONNECTORSERVER_KEY`, so run `/setKey` before the first start. + To set the key, run the `/setKey` command. The command stores a hash of the key, not the key itself, in the `conf/ConnectorServer.properties` file: + @@ -1429,9 +1429,9 @@ $ bin/ConnectorServer.sh /setKey "" Key has been successfully updated. ---- + -If you run `/setKey` without a key, the command prompts for the key instead, which keeps the key out of the shell history. The command refuses `changeit` and an empty key: it leaves the configuration file unchanged and exits with status `1`. +If you run `/setKey` without a key, the command prompts for the key instead, which keeps the key out of the shell history. From OpenICF 2.1 on, the command refuses `changeit` and an empty key: it leaves the configuration file unchanged and exits with status `1`. + -Alternatively, pass the key in clear text in the `CONNECTORSERVER_KEY` environment variable when you start the server. This suits containers, where the configuration file is not edited. A key set in the `ConnectorServer.properties` file takes precedence over the environment variable: +From OpenICF 2.1 on, you can alternatively pass the key in clear text in the `CONNECTORSERVER_KEY` environment variable when you start the server. This suits containers, where the configuration file is not edited. A key set in the `ConnectorServer.properties` file takes precedence over the environment variable: + [source, console] @@ -1441,7 +1441,7 @@ $ CONNECTORSERVER_KEY="" bin/ConnectorServer.sh /run + The `key` property in the OpenIDM remote connector server configuration (`provisioner.openicf.connectorinfoprovider.json`) must match the key of the connector server. For more information, see xref:#connector-info-provider-conf["Accessing Remote Connectors"]. -. Review the `ConnectorServer.properties` file in the `/path/to/openicf/conf` directory, and make any required changes. By default, the configuration file has the following properties: +. Review the `ConnectorServer.properties` file in the `/path/to/openicf/conf` directory, and make any required changes. In OpenICF 2.1 and later, the configuration file has the following properties by default: + [source] @@ -1505,7 +1505,7 @@ Connector.log ConnectorServer.log ConnectorServerTrace.log C:\>cd C:\path\to\openicf\bin ---- -. Set the connector server key before you start the server for the first time. The Java Connector Server uses a `key` property to authenticate connections from OpenIDM. From OpenICF 2.1 on, there is no default key: the packaged `ConnectorServer.properties` file leaves `connectorserver.key` unset, and the server refuses to start until a key is set. The server also refuses the key `changeit`, which earlier versions shipped as the default, and an empty key, because any client could authenticate with either of them. +. Set the connector server key before you start the server for the first time. The Java Connector Server uses a `key` property to authenticate connections from OpenIDM. From OpenICF 2.1 on, there is no default key: the packaged `ConnectorServer.properties` file leaves `connectorserver.key` unset, and the server refuses to start until a key is set. The server also refuses the key `changeit`, which earlier versions shipped as the default, and an empty key, because any client could authenticate with either of them. In OpenICF 2.0.x and earlier, the packaged file sets `connectorserver.key` to the hash of `changeit` and the server does not read `CONNECTORSERVER_KEY`, so run `/setKey` before the first start. + To set the key, use the `bin\ConnectorServer.bat /setKey` command. The command stores a hash of the key, not the key itself, in the `conf\ConnectorServer.properties` file: + @@ -1516,13 +1516,13 @@ c:\path\to\openicf>bin\ConnectorServer.bat /setKey "" Key has been successfully updated. ---- + -If you run `/setKey` without a key, the command prompts for the key instead. The command refuses `changeit` and an empty key: it leaves the configuration file unchanged and exits with status `1`. +If you run `/setKey` without a key, the command prompts for the key instead. From OpenICF 2.1 on, the command refuses `changeit` and an empty key: it leaves the configuration file unchanged and exits with status `1`. + -Alternatively, pass the key in clear text in the `CONNECTORSERVER_KEY` environment variable when you start the server from the command line. A key set in the `ConnectorServer.properties` file takes precedence over the environment variable. If you install the connector server as a Windows service, set the key with `/setKey`: the service does not see a variable that is set only in the Command Prompt window. +From OpenICF 2.1 on, you can alternatively pass the key in clear text in the `CONNECTORSERVER_KEY` environment variable when you start the server from the command line. A key set in the `ConnectorServer.properties` file takes precedence over the environment variable. If you install the connector server as a Windows service, set the key with `/setKey`: the service does not see a variable that is set only in the Command Prompt window. + The `key` property in the OpenIDM remote connector server configuration (`provisioner.openicf.connectorinfoprovider.json`) must match the key of the connector server. For more information, see xref:#connector-info-provider-conf["Accessing Remote Connectors"]. -. Review the `ConnectorServer.properties` file in the `path\to\openicf\conf` directory, and make any required changes. By default, the configuration file has the following properties: +. Review the `ConnectorServer.properties` file in the `path\to\openicf\conf` directory, and make any required changes. In OpenICF 2.1 and later, the configuration file has the following properties by default: + [source] From 38f9998b1cddee8b265b99c80c89d2db1ecd098c Mon Sep 17 00:00:00 2001 From: Valera V Harseko Date: Tue, 6 Oct 2026 10:17:58 +0300 Subject: [PATCH 3/3] [#235] Run the Windows connector server commands from the openicf directory Step 3 of the Windows procedure said "change to the openicf directory" but changed to openicf\bin, while every later command runs bin\ConnectorServer.bat from openicf. Change to openicf instead. --- .../src/main/asciidoc/integrators-guide/chap-resource-conf.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc b/openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc index 736613b71..cb177bdb3 100644 --- a/openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc +++ b/openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc @@ -1502,7 +1502,7 @@ Connector.log ConnectorServer.log ConnectorServerTrace.log [source, console] ---- -C:\>cd C:\path\to\openicf\bin +C:\>cd C:\path\to\openicf ---- . Set the connector server key before you start the server for the first time. The Java Connector Server uses a `key` property to authenticate connections from OpenIDM. From OpenICF 2.1 on, there is no default key: the packaged `ConnectorServer.properties` file leaves `connectorserver.key` unset, and the server refuses to start until a key is set. The server also refuses the key `changeit`, which earlier versions shipped as the default, and an empty key, because any client could authenticate with either of them. In OpenICF 2.0.x and earlier, the packaged file sets `connectorserver.key` to the hash of `changeit` and the server does not read `CONNECTORSERVER_KEY`, so run `/setKey` before the first start.