fix(accessanalyzer): correct install and IDP setup docs to match current installer

[mckibbenc]

Summary

• Quick Install and Identity Provider docs described a prior installer generation (AD prompts during install, /opt/dspm-tls, a customer-facing breakglass admin@dspm.local). Verified current behavior against the access-analyzer source: IDP flags were removed from the installer (AA-12), the first admin is now the only login-capable account after install (AA-199), and IDP setup happens post-install via the webapp setup wizard at /setup.
• Fixed the TLS certificate directory (/opt/dspm-tls → /etc/dspm), removed the install-time "Active Directory information" section, corrected the first admin account description (local account, generated password, forced change), removed the prompt reference table, updated the installation summary to match actual installer output, and refactored Identity Provider's supported integration types to describe the real AD/Entra ID setup-wizard flow, including "Set up later" and revisiting via /setup.

Test plan

• Vale/Dale checks pass (CI auto-fix workflow)
• Editorial review (doc-pr workflow)
• Manually verify anchors/links render correctly once deployed to a preview

[github-actions]

Auto-Fix Summary

12 issues fixed, 10 skipped across 2 files

Category	Fixes
OnceUsage (rewrite)	1
Dale: misplaced-modifiers	1
Dale: passive-voice	8
Dale: undefined-acronyms	2

Skipped (needs manual review)	Reason

| docs/accessanalyzer/2601/install/quickinstall.md:256 — Dale: positional-references | 'Log in at the URL above' is verbatim installer output reproduced inside a fenced code block — changing it would misrepresent what the product prints |
| docs/accessanalyzer/2601/install/quickinstall.md:70 — Dale: xy-slop | 'Use a DNS hostname, not an IP address' is a deliberate warning contrast, not the negative-positive slop pattern; rewriting would weaken the caution |
| docs/accessanalyzer/2601/install/quickinstall.md:70 — Dale: undefined-acronyms | 'TLD' is standard internet terminology familiar to the sysadmin audience |
| docs/accessanalyzer/2601/install/quickinstall.md:113 — Dale: passive-voice | 'Verify the cert was signed by your CA bundle' is a comment inside a bash code block |
| docs/accessanalyzer/2601/install/quickinstall.md:285 — Dale: xy-slop | 'the local username and password ... — not an Active Directory or Entra ID password' clarifies a genuine point of confusion; the contrast carries the meaning |
| docs/accessanalyzer/2601/install/quickinstall.md:335 — Dale: passive-voice | Inside a commented-out HTML block (unpublished post-GA content) |
| docs/accessanalyzer/2601/configurations/identity-provider.md:54 — Dale: undefined-acronyms | 'DN' (in 'users base DN') is standard LDAP/directory terminology for this audience, and 'Distinguished Name' is spelled out in the related quickinstall troubleshooting table |
| docs/accessanalyzer/2601/configurations/identity-provider.md:62 — Dale: passive-voice | 'the redirect URI shown on the ... step' is a reduced relative clause; expanding it would make the step wordier without adding clarity |
| docs/accessanalyzer/2601/configurations/identity-provider.md:128 — Dale: xy-slop | 'You set roles and permissions in Access Analyzer, not in your IdP or directory' states a real constraint where the negative half is the important information |
| docs/accessanalyzer/2601/configurations/identity-provider.md:129 — Dale: passive-voice | 'The administrator account created at deployment' is a reduced participial modifier in a compact table cell; naming an agent would lengthen it without changing meaning |

Ask @claude on this PR if you'd like an explanation of any fix.

[github-actions]

Documentation PR Review

Editorial Review

docs/accessanalyzer/2601/configurations/identity-provider.md

• Structure — Line 24: The new ## Setting up an identity provider section conflicts with the document's framing. Line 11 (unchanged) tells the reader this is a "two-part process: first you configure the integration in your identity system, then you prepare user accounts inside Access Analyzer" — but the new section inserts a third, chronologically-first stage (the first-sign-in wizard) ahead of Part 1, and then duplicates itself in Part 2 > First sign-in (line 87 repeats "Connect now / Set up later" and the /setup path almost verbatim). A reader scanning for "where do I start" now finds two competing answers. Suggested fix: fold the wizard choice into Part 2 > First sign-in where it chronologically belongs and retitle line 24 to something scoped, such as "Before you begin" or "When to connect an identity provider", covering only the "you don't need an IdP to install" point and the link to Quick Install.
• Completeness — Line 22: The Entra ID row adds a redirect-based integration type, but the "How sign-in works after IdP configuration" section (line 122) still describes only one flow: "the Access Analyzer login page presents a credential form that validates against your directory." A reader who configures Entra ID reaches that section and finds no description of the redirect experience they will actually see. Suggested fix: extend line 122 to cover both — "With Active Directory, the login page presents a credential form that validates against your directory. With Entra ID, the login page presents a Sign in with Microsoft button that redirects users to Entra ID and returns them to Access Analyzer after authentication."
• Completeness — Lines 62–64: The Azure procedure has the reader add two redirect URIs under Add a platform > Web but never tells them to commit the change. Azure requires Configure on the platform panel and Save on the Authentication blade; without it the URIs are lost and the reader hits the exact AADSTS50011 failure the note at line 78 warns about. The previous version of this procedure included an explicit "Click Save" step. Suggested fix: add a step after entering the URIs — "Click Configure, then click Save on the Authentication page."
• Completeness — Line 54: "You don't need to look up the users base DN or the email attribute yourself" introduces two terms that no longer appear anywhere earlier in the document — the table that defined Users base DN and Email attribute name was removed in this PR. A reader new to LDAP is told they don't need something they've never heard of, which reads as a warning rather than a reassurance. Suggested fix: name what the wizard does instead of what the reader skips — "After you enter the domain, service account, and certificate, the wizard tests the connection and automatically discovers where user accounts are stored and which directory attribute holds each user's email address."
• Clarity — Line 43: "AD forest" is the first use of the AD abbreviation in this document (line 21 and line 37 both spell out "Active Directory"), and "forest" is introduced without context. Netwrix standards require spelling out an acronym on first use. Suggested fix: "The Access Analyzer cluster must be able to reach a domain controller in your Active Directory (AD) forest over LDAPS (port 636)." Then keep AD in the table rows at lines 49–52.
• Clarity — Line 31: "browsing to /setup" gives a bare path with no host, so it isn't directly actionable — the reader has to infer that it's relative to their Access Analyzer URL. The same shorthand appears at line 87. Suggested fix: use the full form on first mention — "the wizard stays reachable at any time at https://<your-hostname>/setup" — and keep the short form on the second mention.
• Clarity — Line 110: "The installer assigns the first admin account the Administrator role, so it can pre-provision the rest of your users" uses "it" to refer to the account, which reads as though the installer is doing the pre-provisioning. Suggested fix: "The installer assigns the Administrator role to the first admin account, so that user can pre-provision the rest of your users."

docs/accessanalyzer/2601/install/quickinstall.md

• Completeness — Line 95: Making ca-bundle.crt conditional ("Required only if an internal or private CA signs the certificate — omit it for a publicly trusted certificate") contradicts the surrounding, unchanged instructions. Line 81 still says "Three PEM files", line 85 still says "prepare the following three files", and the commands at lines 103 and 114 both use ca-bundle.crt unconditionally. A reader with a publicly trusted certificate follows those commands and hits a missing-file error. Suggested fix: change line 85 to "prepare the following files", change the What to Prepare cell at line 81 to "Two or three PEM files — see file requirements", and mark the update-ca-certificates block (lines 103–104) and the openssl verify command (line 114) as applying only when you supply a CA bundle.
• Completeness — Line 233: The replacement summary of the installer wizard is missing prompts the reader will actually see. It lists "license key, hostname, first admin name and email, and TLS certificate file paths" but omits the TLS provisioning method choice (the reader must pick one of the three options described at line 77) and the Advanced Settings step that the very next note at line 236 discusses. The deleted prompt table also carried guidance that now has no home in the wizard section — most importantly that the hostname must be lowercase and match the certificate SAN exactly, which is the cause of the first troubleshooting row at line 420. Suggested fix: "The installer presents an interactive wizard: license key, hostname, first admin name and email, TLS provisioning method, and — for Bring your own certificate — the certificate and key file paths. Enter the hostname in lowercase and exactly as it appears in the certificate SAN list. Each prompt shows an example value and validates your input before moving on."
• Structure — Lines 294–303: In Step 6, the "Next step:" pointer to the Identity Provider guide comes before the password-recovery instructions and the closing caveat. A reader who has finished signing in reads "Next step", follows the link, and never sees the recovery information; a reader who has lost the password has to read past a next-step pointer to find help. Suggested fix: move the "If you lose the temporary password…" paragraph, code block, and closing sentence directly after line 290 (where the temporary password is used), leaving the "Next step:" pointer as the last line of the section.
• Completeness — Line 303: "use the app's password reset flow" doesn't tell the reader where that is, leaving the sentence unactionable at the exact moment they need it. Access Analyzer exposes this as a Reset Password action on the Users page. Suggested fix: "This returns only the original temporary password. After you change it, reset the password from Configuration > Users — or contact Netwrix Support if the first admin account becomes inaccessible."
• Structure — Lines 284–286: The note that the first admin signs in with a local password and must change it on first sign-in is the third statement of the same fact (line 127 and line 290 both already say it), and it sits in Step 5 immediately before Step 6, which repeats it. Suggested fix: delete the note here and, if the local-versus-directory distinction needs emphasis at sign-in time, add the clarifying clause to line 290 instead — "…the temporary password from the installation summary (a local password, not an Active Directory or Entra ID password), then set a new password when prompted."
• Completeness — Lines 422 and 426: Two troubleshooting rows now point at procedures and prompts this PR removed. The PKIX path building failed row tells the reader to "Concatenate the DC's LDAPS CA into the bundle and re-run the installer", but the section that explained how to identify and concatenate that CA was deleted; the "Installer rejects the Bind DN" row references a Bind DN prompt the installer no longer presents. Both leave the reader with an instruction they can't act on. Suggested fix: delete the Bind DN row, and either delete the PKIX row or repoint its fix at the Active Directory certificate step in Identity Provider, where the LDAPS CA certificate is now supplied.
• Clarity — Line 19: "this provisions a local account — no AD/Entra dependency" uses slash-joined abbreviations in a checklist aimed at readers who may be new to the product, and AD isn't expanded anywhere earlier in the document. Suggested fix: "First admin name and email address decided (the installer creates a local account — it doesn't depend on Active Directory or Entra ID)".

Summary

14 editorial suggestions across 2 files. Vale and Dale issues are auto-fixed separately.

---

What to do next:

Comment @claude on this PR followed by your instructions to get help:

• @claude fix all issues — fix all editorial issues
• @claude help improve the flow of this document — get writing assistance
• @claude explain the voice issues — understand why something was flagged

You can ask Claude anything about the review or about Netwrix writing standards.

Automated fixes are only available for branches in this repository, not forks.

[github-actions]

Auto-Fix Summary

5 issues fixed, 5 skipped across 2 files

Category	Fixes
Dale: misplaced-modifiers	1
Dale: passive-voice	1
Dale: positional-references	1
Dale: wordiness	2

Skipped (needs manual review)	Reason

| docs/accessanalyzer/2601/install/quickinstall.md:256 — Dale: positional-references | 'Log in at the URL above' is verbatim installer output inside a fenced code block — editing it would misrepresent what the installer prints. |
| docs/accessanalyzer/2601/install/quickinstall.md:113 — Dale: passive-voice | 'Verify the cert was signed by your CA bundle' is a shell comment inside a fenced code block, not documentation prose. |
| docs/accessanalyzer/2601/install/quickinstall.md:335 — Dale: passive-voice | 'The Entra ID installer is invoked...' and 'The flags are passed...' sit inside the HIDDEN HTML comment block (lines 307-393) that is not published; editing unpublished draft content risks conflicting with the eventual rewrite. |
| docs/accessanalyzer/2601/install/quickinstall.md:18 — Dale: misplaced-modifiers | 'certificate files prepared if using Bring Your Own' has an unstated subject for 'using', but the checklist uses terse fragments throughout and rewording risks breaking the reference to the 'Bring your own certificate' option name. |
| docs/accessanalyzer/2601/configurations/identity-provider.md:54 — Dale: undefined-acronyms | 'DN' is a standard LDAP/AD term for the sysadmin audience, in the same class as the LDAP/OU/DACL exclusions the rule lists. |

Ask @claude on this PR if you'd like an explanation of any fix.