[vharseko]

The installation and Java EE agent guides refer readers to Release Notes, but that guide is missing. Add a four-page guide using the OpenDJ documentation structure, register it in the documentation build, and link both prefaces.

The guide includes selected changes and all eight distribution assets for 16.1.4, Java/container requirements, upgrade considerations, 18 published security advisories fixed in 16.1.4, and a brief history of all 69 published community releases. Release records and source comparisons remain linked for full details. All 35 source-comparison URLs preserve GitHub's literal three-dot separator in both HTML and PDF.

The upgrade guidance identifies the IdP discovery return-URL allowlist, its format, and how to configure it for both OpenAM-hosted endpoints and a standalone IDP Discovery WAR. The 16.1.2 security-advisory reminder applies to the server generally and appears before the standalone-WAR instructions. Links between chapters resolve within the combined PDF, and each redirect advisory has a short description, including the goto/gotoOnFail cross-site scripting issue.

Fixes #1153.

Validation

• Ran doc-maven-plugin 3.2.2 preprocessing, Antora conversion, and PDF generation, including the plugin's PDF preprocessing step. Rebuilt the 12-page Release Notes PDF with Asciidoctor PDF 2.3.18.
• Verified that all 35 distinct comparison URLs match the original source URLs exactly in the generated Antora HTML hrefs and PDF URI annotations, without a substituted ellipsis, zero-width space, or escape character. An Asciidoctor.js 2.2.9 before/after check reproduced all 35 failures before the fix and confirmed all 35 exact URLs after it.
• Checked the PDF chapter-link destinations and confirmed that the security-advisory reminder precedes the standalone-WAR paragraph in the rendered output.
• Built an Antora HTML preview and checked 46 local content links and anchors across the four new pages and two updated prefaces. Generated reference pages from the documentation-site checkout were included. No diagnostics came from the new guide; nine existing attribute warnings remain in other pages.
• Checked all 69 release records and UTC dates, all eight asset names, and the 18 advisories' published status and patched versions against GitHub. Checked platform and compatibility claims against tagged sources and history, including IdP discovery configuration in 16.1.2.
• Ran git diff --check.

Documentation-site follow-up

The companion registration is in doc.openidentityplatform.org#44. It adds the Release Notes sidebar entry and PDF download mapping to openam/antora.yml.

Merge and deploy this PR first, including the generated openam/modules/release-notes module and Release_Notes.pdf; merge the site registration after those artifacts are available.

[maximthomas]

praise: The release facts check out against GitHub.

• The 18 GHSA ids in release-notes/release-16.1.4.adoc are exactly the published advisories whose patched versions include 16.1.4. None is missing and none is extra.
• All 69 rows in release-notes/release-history.adoc carry the same date as gh release list. The 8 asset rows, Dockerfile included, match the 16.1.4 release record.

---

issue (blocking): The 16.1.2 IdP discovery bullet says to configure permitted destinations "as described in" a section that never describes them.

openam-documentation/openam-doc-source/src/main/asciidoc/release-notes/requirements-and-upgrade.adoc:58

The link goes to chap-federation.adoc#deploy-idp-discovery (lines 481-654). That section covers WAR deployment, the Configurator, circle-of-trust membership and metadata. It never mentions the setting. The setting is the advanced server property org.openidentityplatform.openam.idpdiscovery.relaystate.whitelist, and it is described only at chap-federation.adoc:1260 under [#configure-cot] and in the [IMPORTANT] at upgrade-guide/chap-upgrade-servers.adoc:74-79. An admin whose service providers run on another host gets HTTP 400 from /saml2reader and /saml2writer after the upgrade. The bullet neither names the property nor links to where it is described. The standalone IDP Discovery WAR's own configuration was not checked.

* From 16.1.2, IdP discovery endpoints restrict cross-domain return URLs. If service providers run on a different host than the discovery service, add their return URLs to the advanced server property `org.openidentityplatform.openam.idpdiscovery.relaystate.whitelist`, as described in xref:../admin-guide/chap-federation.adoc#configure-cot[Modifying a Circle of Trust's Configuration] and the xref:../upgrade-guide/chap-upgrade-servers.adoc[server upgrade notes]. Review security advisories for additional changes to server-side URL fetching, script execution, and class instantiation.

---

issue (non-blocking): In Release_Notes.pdf, the three links within the book point to files the build never produces.

openam-documentation/openam-doc-source/src/main/asciidoc/release-notes/release-16.1.4.adoc:77, release-history.adoc:129, requirements-and-upgrade.adoc:51

The pom now builds a single PDF from release-notes/index.adoc. In that build, xref:./<file>.adoc[...] stays an inter-document xref:

• doc-maven-plugin 3.2.2 convertXrefForPdf rewrites only ../ and resource-id targets.
• ./requirements-and-upgrade does not match Asciidoctor's include-catalog keys.
• asciidoctor-pdf 2.3.18 renders it as <a href="./requirements-and-upgrade.pdf">.

The Antora site is not affected, and the link check ran only on the Antora preview. Every other guide uses the xref:<file>.adoc#<id> form. In an Asciidoctor probe that form rendered the internal #release-requirements. The anchors it needs are already declared on both ifdef branches.

// release-16.1.4.adoc:77 and release-history.adoc:129
xref:requirements-and-upgrade.adoc#release-requirements[Requirements and Upgrade Considerations]
// requirements-and-upgrade.adoc:51
xref:release-history.adoc#release-history[release history]

---

nitpick (non-blocking): The four advisory links in the "Redirects" group have no labels. Every other group labels each link.

openam-documentation/openam-doc-source/src/main/asciidoc/release-notes/release-16.1.4.adoc:51

Lines 49, 50 and 54 put a short label in parentheses after each GHSA link. Without one, the cross-site scripting half of GHSA-2gwf-vxp5-f9v2 ("open redirect and cross-site scripting via the goto and gotoOnFail parameters") appears nowhere in the 16.1.4 notes. Add a label to each link, taken from the advisory's title.

[vharseko]

@maximthomas Addressed all three points in 4e6e811:

• The 16.1.2 guidance now names org.openidentityplatform.openam.idpdiscovery.relaystate.whitelist, explains its semicolon-separated URL patterns, and links to the circle-of-trust configuration and server upgrade notes. I also checked the standalone WAR configuration: it reads the same property from $HOME/libIDPDiscoveryConfig.properties, so the notes now cover that file and restarting the discovery application as well.
• All three links between chapters now use the explicit file-and-anchor form. After rebuilding the 12-page PDF, I checked its link annotations and named destinations: the links resolve internally and none points to a nonexistent chapter PDF.
• Each of the four redirect advisories now has a short description, including the goto/gotoOnFail cross-site scripting impact.

The Antora preview passes all 46 local content-link and anchor checks, with no diagnostics in the new guide; the nine existing attribute warnings are in other pages. Independent review and git diff --check also passed. The PR description now reflects these details and links to the companion documentation-site PR.

[maximthomas]

praise: The round-2 fixes are accurate, and the release claims match the code and tags.

• The 16.1.2 bullet matches CookieUtils.isRedirectUrlValid: org.openidentityplatform.openam.idpdiscovery.relaystate.whitelist, ;-separated, empty by default. Relative and same-origin URLs pass, including ones with an implicit default port, because BaseURLResourceName.canonicalize adds 80/443.
• xref:requirements-and-upgrade.adoc#release-requirements[] and xref:release-history.adoc#release-history[] now become internal /Dest links in the PDF (asciidoctor-pdf 2.3.18), and they resolve to real ids in the env-site render.
• The version claims match their first tags. ODSEE removal (c0ed63f) first appears in 15.1.6. The empty-allowlist change (GHSA-2gwf-vxp5-f9v2, GHSA-fhqm-62hv-4phw) first appears in 16.1.4.

---

issue (blocking): The 35 GitHub compare/A...B links render as dead URLs on the site and in the PDF.

openam-documentation/openam-doc-source/src/main/asciidoc/release-notes/release-history.adoc:85-118, openam-documentation/openam-doc-source/src/main/asciidoc/release-notes/release-16.1.4.adoc:30

Asciidoctor runs the replacements substitution before macros. So ... inside a bare URL becomes …​ in the href, and GitHub returns 404 for compare/7529aa9%E2%80%A6%E2%80%8B53b06c3 but 200 for compare/7529aa9...53b06c3. I measured this on all 35 links: Asciidoctor.js 2.2.9 (Antora 3.1.9's core) and AsciidoctorJ 2.5.11 break every href, and in asciidoctor-pdf 2.3.18 every /URI annotation has U+2026 U+200B. doc-maven-plugin 3.2.2 passes bare https URLs through unchanged. So "source comparisons remain linked for full details" is not true for these rows. Escape the ellipsis in each of the 35 URLs. No other URL in the four pages contains ....

// release-history.adoc:85 — same change in every compare URL on lines 85-118
|https://github.com/OpenIdentityPlatform/OpenAM/releases/tag/14.6.4[14.6.4] |2021-07-28 |CVE-2021-35464 workaround, embedded Cassandra logging, and Docker/build improvements. https://github.com/OpenIdentityPlatform/OpenAM/compare/7529aa9\...53b06c3[Source comparison].

// release-16.1.4.adoc:30
The https://github.com/OpenIdentityPlatform/OpenAM/releases/tag/16.1.4[16.1.4 release record] lists the assets and changes. The https://github.com/OpenIdentityPlatform/OpenAM/compare/16.1.3\...16.1.4[comparison with 16.1.3] provides the corresponding source history. For newer releases, consult the https://github.com/OpenIdentityPlatform/OpenAM/releases[release list].

Or: link:++https://github.com/OpenIdentityPlatform/OpenAM/compare/7529aa9...53b06c3++[Source comparison]. Both forms render ... in all three renderers above. The PDF check ran on the raw sources, not through doc-maven-plugin's PDF preprocessing.

---

suggestion (non-blocking): Move the 16.1.2 sentence "Review security advisories for additional changes to server-side URL fetching, script execution, and class instantiation." out of the standalone-WAR paragraph.

openam-documentation/openam-doc-source/src/main/asciidoc/release-notes/requirements-and-upgrade.adoc:58, :60

When the bullet was split, this sentence ended up last in the paragraph that opens "For a standalone IDP Discovery WAR,". It now reads as advice for that deployment only. The advisories it points to (SSRF, Groovy sandbox escape, /authservice class instantiation) all concern the server. An admin of an OpenAM-hosted deployment who skips the standalone-WAR paragraph misses the only 16.1.2 pointer to them.

* From 16.1.2, IdP discovery endpoints accept relative and same-origin return URLs; other destinations must match `org.openidentityplatform.openam.idpdiscovery.relaystate.whitelist` (a semicolon-separated list of URL patterns, empty by default). For endpoints hosted by OpenAM, configure this advanced server property as described in xref:../admin-guide/chap-federation.adoc#configure-cot[Modifying a Circle of Trust's Configuration] and the xref:../upgrade-guide/chap-upgrade-servers.adoc[server upgrade notes]. Review security advisories for additional changes to server-side URL fetching, script execution, and class instantiation.
+
For a standalone IDP Discovery WAR, set the same property in `$HOME/libIDPDiscoveryConfig.properties`, where `$HOME` is the home directory of the user running the web container, and restart the discovery application.

[vharseko]

@maximthomas Addressed both points from the second review in 93a505a:

• Escaped the ellipsis (\...) in all 35 GitHub comparison URLs: 34 in the release history and one in the 16.1.4 overview. After rebuilding through doc-maven-plugin 3.2.2, including its PDF preprocessing step, all 35 distinct URLs match the original source URLs exactly in both the Antora HTML hrefs and the PDF URI annotations. No typographic ellipsis, zero-width space, or escape character remains in those targets. The Asciidoctor.js 2.2.9 before/after check also reproduces the original failure and confirms the fix for all 35 URLs.
• Moved the security-advisory reminder into the main 16.1.2 paragraph, before the standalone IDP Discovery WAR instructions. Its server-wide scope is now clear in both rendered formats.

The 12-page PDF was rebuilt, its chapter-link destinations remain valid, and all 46 local HTML content-link and anchor checks pass. The new guide has no diagnostics; the nine existing attribute warnings are in other pages. git diff --check passes. The PR description now reflects the final changes and validation.

[maximthomas]

praise: The round-3 commit fixes the dead compare links and the misplaced advisory pointer exactly where they were.

• All 35 compare/<from>\...<to> links (openam-documentation/openam-doc-source/src/main/asciidoc/release-notes/release-history.adoc:85-118, release-16.1.4.adoc:30) now render with a plain ... in the href: 35/35 in Asciidoctor.js 2.2.9 (Antora's core) and 35 distinct link URIs in the asciidoctor-pdf 2.3.18 book. doc-maven-plugin's AsciidocToPdfMojo rewrites only xref: targets, so the escape reaches the PDF unchanged.
• The "Review security advisories …" sentence closes the first paragraph of the 16.1.2 bullet again (requirements-and-upgrade.adoc:58), and its three topics match the 16.1.1..16.1.2 fixes: SSRF, the Groovy script sandbox escape, and unsafe class instantiation in /authservice.