[#235] Integrator's guide: the connector server has no default key

[vharseko]

Fixes #235

The problem

The integrator's guide tells readers that the Java connector server key defaults to changeit. From OpenICF 2.1 on, the connector server ships without a key: the packaged conf/ConnectorServer.properties leaves connectorserver.key unset, and the server refuses to start without a key, on the hash of changeit, or on the hash of an empty key. A reader who follows the guide as written gets a server that will not start.

The sample ConnectorServer.properties excerpts in the same procedures also show connectorserver.key set to a fixed hash, which the packaged file no longer carries.

The change

chap-resource-conf.adoc, in both the Unix (#java-connector-server-unix) and the Windows (#java-connector-server-windows) install procedures:

• Drop "The default key value is changeit." and say that a key must be set before the first start.
• Keep the /setKey example, with a "<your key>" placeholder instead of Passw0rd. Note that /setKey without a key prompts for it, and that from OpenICF 2.1 on it refuses changeit and an empty key with exit status 1.
• Describe CONNECTORSERVER_KEY (OpenICF 2.1 and later) and its precedence: a key in the properties file wins over the variable. On Windows, point out that a variable set only in the Command Prompt window does not reach the Windows service, so the service needs /setKey.
• Say that in OpenICF 2.0.x and earlier the packaged file carries the hash of changeit and the server does not read CONNECTORSERVER_KEY, so /setKey must run before the first start.
• Say that the key in provisioner.openicf.connectorinfoprovider.json must match the server's key, with a link to "Accessing Remote Connectors".
• Show #connectorserver.key= in the default properties excerpts as the OpenICF 2.1 default, and say that /setKey fills it with the hash of the key.
• Replace the stale Windows /setkey output (a classpath echo) with Key has been successfully updated.
• Unix unzip step: openicf-<version>.zip instead of openicf-zip-1.7.1.zip, which is neither the release asset name nor a version this text describes.
• Windows step 3: change to C:\path\to\openicf instead of openicf\bin, since every later command, /setKey included, runs bin\ConnectorServer.bat from openicf.

Verification

Rendered the chapter with Asciidoctor.js 3: no warnings, the connector-info-provider-conf target resolves for both new cross-references, and the Unix and Windows procedures keep their seven and eight steps.

Not in this PR

• The published copy in OpenIdentityPlatform/doc.openidentityplatform.org (openidm/modules/integrators-guide/pages/chap-resource-conf.adoc) needs the same change there.
• The .NET connector server ships the same published key; that is tracked in Connector server ships a working default key (hash of changeit) OpenICF.Net#5.
• The legacy DocBook copy of the chapter (openidm-doc/src/main/docbkx/integrators-guide/chap-resource-conf.xml) still says the key defaults to changeit. No documentation change since Update target JDK to 17 and move to JakartaEE 10 (Pax Web 11) #114 has touched src/main/docbkx, but the man-pages profile still builds it into the release docs zip; whether to sync or drop that copy belongs in its own issue.

[maximthomas]

praise: The key steps now match the real connector-server commands and connect the two ends of the key.

• The Unix example uses /setKey, which is the only spelling OpenICF's bin/ConnectorServer.sh accepts: it dispatches on [[ "$1" == "/setKey" ]], case-sensitively (line 159 at tag 2.0.4). The old /setkey example fell through on Unix.
• Both procedures now say that the key in provisioner.openicf.connectorinfoprovider.json must match the server key, and they link to xref:#connector-info-provider-conf, whose anchor is at chap-resource-conf.adoc:56.

---

question (blocking): Should this PR merge only once an OpenICF release with the documented key behaviour is published?

openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc:1420, :1432, :1434-1439, :1454, :1508, :1519, :1521, :1535

The procedure links to the OpenICF releases page. Its latest release is 2.0.4, and OpenIDM's pom.xml:396 pins openicf 2.0.4. At tag 2.0.4, conf/ConnectorServer.properties:89 ships connectorserver.key=lmA6bMfENJGlIDbfrVtklXFK32s\=, which is the changeit hash according to its ## /setkey changeit comment. Neither connector-server Main.java reads an environment variable. Each key step qualifies only its first sentence with "From OpenICF 2.1 on". The refusal, the CONNECTORSERVER_KEY paragraph and the #connectorserver.key= excerpts all read as current behaviour. A reader on 2.0.4 who sets the key through the environment variable therefore gets a server that still accepts changeit, while the guide says that key is refused. OpenIDM, configured with the new key, then cannot connect. If the merge waits for that release, the qualifiers below are all that is left, and they are non-blocking. If it merges before the release, this blocks.

. Set the connector server key before you start the server for the first time. [...] 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.
[...]
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`.
+
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. [...]
[...]
. 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:

Or: hold the merge until the release is out. The 2.0.x sentence is still worth keeping for readers who stay on 2.0.x.

---

issue (non-blocking): The unchanged unzip step names openicf-zip-1.7.1.zip, and the new key text now contradicts that version.

openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc:1409

At tag 1.7.1, the packaged conf/ConnectorServer.properties:89 carries the changeit hash, and that version has no CONNECTORSERVER_KEY. The steps at :1420 and :1454 therefore describe a different artifact from the one this step unpacks. The release asset is also named openicf-1.7.1.zip, not openicf-zip-1.7.1.zip.

$ unzip openicf-<version>.zip

---

suggestion (non-blocking): Make the same key-step change in the DocBook copy of the chapter, or list that copy under "Not in this PR".

openidm-doc/src/main/docbkx/integrators-guide/chap-resource-conf.xml:1499, :1555, :1560

Both procedures in the DocBook copy still say "The default secret key value is changeit", and :1560 still uses /setkey. The man-pages profile still runs the doc-maven-plugin process/build/release goals over src/main/docbkx with buildReleaseZip set (openidm-doc/pom.xml:48-53, :79). The released openidm-doc-<version>-docs.zip therefore keeps the default that this PR removes from the guide.

[vharseko]

Blocking question (merge before the OpenICF 2.1 release): merging now, so I applied the qualifiers you proposed, in both procedures:

• the key step adds the 2.0.x sentence: the packaged file carries the hash of changeit and the server does not read CONNECTORSERVER_KEY, so run /setKey before the first start;
• the /setKey refusal sentence and the CONNECTORSERVER_KEY paragraph now start with "From OpenICF 2.1 on";
• the properties excerpt is introduced as "In OpenICF 2.1 and later, the configuration file has the following properties by default".

The prompt for a key when /setKey runs without one stays unqualified: at 2.0.4, both ConnectorServer.sh and ConnectorServer.bat already call -setKey without -key in that case.

Unzip step (:1409): changed to $ unzip openicf-<version>.zip.

DocBook copy: listed under "Not in this PR". No documentation change since #114 has touched src/main/docbkx, so syncing it only for this chapter would be a one-off; syncing or dropping that copy belongs in its own issue.

Re-rendered with Asciidoctor.js 3: no warnings, both cross-references resolve, step counts unchanged.

[maximthomas]

praise: The guide is now right for the release readers can download today and for the next one.

• chap-resource-conf.adoc:1420 and :1508 end with the 2.0.x sentence (changeit hash shipped, CONNECTORSERVER_KEY ignored, run /setKey first), so the procedure still works on 2.0.4, the version OpenIDM pins.
• The refusal and env-var paragraphs (:1432, :1434, :1519, :1521) and the excerpt intros (:1444, :1525) carry "From OpenICF 2.1 on" / "In OpenICF 2.1 and later". OpenICF master is 2.1.0-SNAPSHOT with no 2.0.x branch, so the version named is the next release.
• The /setKey prompt sentence stays unqualified, which is correct: at 2.0.4 both ConnectorServer.sh and ConnectorServer.bat already prompt when no key is given.

---

issue (non-blocking): The Windows key step runs bin\ConnectorServer.bat from a directory that step 3 never takes the reader to.

openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc:1505, :1515, :1548, :1558, :1567

Step 3 says "change to the openicf directory", but its command is C:\>cd C:\path\to\openicf\bin. The rewritten key example at :1515 (c:\path\to\openicf>bin\ConnectorServer.bat /setKey "<your key>") only works from openicf. From openicf\bin it resolves to bin\bin\ConnectorServer.bat, so cmd reports "'bin\ConnectorServer.bat' is not recognized" on the first command this PR rewrote. The mismatch already exists at the base and also affects /install, /uninstall and /run. Since this PR edits :1515, it is a cheap place to fix it.

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

[source, console]
----
C:\>cd C:\path\to\openicf
----

---

suggestion (non-blocking): The Verification section reports nine Windows steps, but the chapter renders eight.

openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc:1496

With @asciidoctor/core 3, #java-connector-server-windows is one ordered list of 8 items at the base, at the round-1 head and at this head (:1496, :1498, :1500, :1508, :1525, :1540, :1562, :1574). The Unix procedure is one list of 7. Numbering did not change, so readers are not affected. But "seven and nine" does not match the render it describes. Changing it to "seven and eight" makes the check reproducible.

const fs = require('fs'), assert = require('assert');
const A = require('@asciidoctor/core')();
const doc = A.load(fs.readFileSync('chap-resource-conf.adoc', 'utf8'), {safe: 'safe'});
for (const [id, n] of [['java-connector-server-unix', 7], ['java-connector-server-windows', 8]]) {
  const ex = doc.findBy({id})[0];
  const ols = ex.findBy({context: 'olist'}).filter(o => o.getParent() === ex);
  assert.deepStrictEqual(ols.map(o => o.getItems().length), [n]);
}

Pin: a + continuation that breaks either procedure splits its list into two, and the assertion fails.

[vharseko]

Windows cd step (:1505): changed to C:\>cd C:\path\to\openicf in bc8ef9e, so step 3 matches its own text and the c:\path\to\openicf>bin\ConnectorServer.bat prompts of /setKey, /install, /uninstall and /run.

Step count: you are right, the Windows procedure renders as one list of eight. The Verification section now says "seven and eight"; your @asciidoctor/core 3 check passes with [7] and [8] on the new head, and the render reports no warnings with validate-internal-refs.

The branch is rebased onto the current master; the two earlier commits are unchanged (git range-diff shows = for both).

[vharseko]

Rebased onto the current master (6d183a1d9) to pick up #249. CI on the previous head bc8ef9eb0 failed only because master itself did not compile at that point: openidm-repo-orientdb stopped at DocumentUtil.java:[106,33] cannot find symbol: variable topLevel after #245, in every build-maven job, and both Docker jobs then had no artifact to download.

The three commits are unchanged: git range-diff marks all of them =. The new head is 38f9998b1, and CI is running on it.

[maximthomas]

praise: The Windows procedure now runs every command from the directory its steps name.

• openidm-doc/src/main/asciidoc/integrators-guide/chap-resource-conf.adoc:1505 is C:\>cd C:\path\to\openicf. It matches step 3's text at :1500 and the c:\path\to\openicf>bin\ConnectorServer.bat prompts for /setKey, /install, /uninstall and /run at :1515, :1548, :1558, :1567.
• The description's Verification line now reports seven and eight steps, the counts Asciidoctor.js 3 renders for #java-connector-server-unix and #java-connector-server-windows.