Update_REGISTRATION_DISABLED_behavior (breaking change)

[ejaronne]

https://github.com/mitre/heimdall2/blob/external_auth_provisioning_policy/docs/adr-004-external-auth-user-provisioning-policy.md

[ejaronne]

REGISTRATION_DISABLED=false, true, local, SSO
track down all samples, helm charts, of environment variables to update behavior descriptions
PR name - update_REGISTRATION_DISABLED_behavior_breaking_change
Eugene - update ADR
Amndeep/Will - set up cards and initial LOE
Nick, Sean, Olivia - review cards and feedback on LOE and any problems seen

[aaronlippold]

ADR-004 Review — verification, industry comparison, and recommended revisions

Reviewed against the heimdall2 source (617ea4388). Overall: sound decision, right placement (policy in AuthnService, not per-strategy), honest alternatives. The recommendations below strengthen it into a long-term design — several review questions in §11 can be answered definitively from the code.

---

1. Verification findings (against actual source)

ADR claim	Verified
"Current behavior" snippet for validateOrCreateUser	✅ Matches authn.service.ts exactly
REGISTRATION_DISABLED does not gate the external-auth path	✅ Confirmed
Proposed config helper pattern	✅ isLocalLoginAllowed/isRegistrationAllowed both use ?.toLowerCase() !== 'true' — identical
§9.3 risk / §11 Q2: "LDAP may need a separate review if its login path does not call validateOrCreateUser"	🔑 LDAP already calls validateOrCreateUser (ldap.strategy.ts:78), same as all five OAuth strategies

The LDAP finding settles review questions 1 and 2 together: the gate covers LDAP automatically — and therefore the variable name SSO_AUTO_CREATE_USERS_DISABLED is a misnomer that will surprise LDAP-only deployments. The ADR's own glossary has the right term: EXTERNAL_AUTH_*.

2. Industry comparison

Product	Design	Notes
GitLab	signup_enabled (local) + allow_single_sign_on (per-provider array, defaults deny) + block_auto_created_users (defaults true: JIT users created but blocked pending admin approval)	The approval-queue middle state is absent from this ADR's alternatives
Grafana	Per-provider allow_sign_up under each [auth.*] section	This is the ADR's deferred Option C, shipped as a major product's primary design
SonarQube	Provisioning mode: JIT (default) vs automatic/SCIM — mutually exclusive states, one switch	Mode enum, not boolean accretion
Harbor	oidc_auto_onboard boolean	Closest to this ADR's proposal

Every product surveyed agrees with this ADR's core call: local registration and external-auth JIT are separate controls (rejecting Option A is industry-consistent). The gap: GitLab and SonarQube show two patterns this ADR doesn't consider — the approval queue and the mode enum.

Sources: GitLab OmniAuth · Grafana auth · SonarQube provisioning · Harbor OIDC

3. Recommended design changes

3a. Mode enum instead of boolean — GitLab's lesson is that booleans accrete into a config maze. One enum absorbs the future without migration:

EXTERNAL_AUTH_USER_PROVISIONING=jit | approval | disabled    # default: jit

• jit — current behavior (backwards-compatible default; existing deployments upgrade with zero change)
• disabled — this ADR's goal: unknown external identities rejected
• approval — reserved for phase 2 (GitLab's block_auto_created_users pattern): account created but blocked pending admin approval. Ships later as one switch case, not a new flag.

Fail-fast on unknown values at startup. Note the current boolean pattern silently treats a typo (ture) as permissive — a security-policy variable should refuse to start on garbage, not default open.

3b. State the choke point as an architectural invariant. All six strategies (google, github, gitlab, okta, oidc, ldap) funnel through validateOrCreateUser — that is the real standardization mechanism. Add to the ADR: "All external-auth strategies MUST provision through AuthnService; any future strategy (e.g., SAML) inherits this policy by construction." Suggested shape:

async provisionExternalUser(identity: ExternalIdentity): Promise<User> {
  const existing = await this.findByEmail(identity.email);
  if (existing) return this.refreshMetadata(existing, identity);

  switch (this.config.externalAuthProvisioning()) {   // exhaustive
    case 'jit':      return this.createActiveUser(identity);
    case 'approval': return this.createPendingUser(identity);  // phase 2
    case 'disabled': throw new AccountNotProvisionedError();
  }
}

3c. Promote audit logging from review question (§11 Q3) to in-scope AC. §1.3's justification is "auditors expect account creation to be traceable" — the rejection event IS the audit artifact this feature exists to produce. Structured events at the choke point: external_auth.user.jit_created, external_auth.login.rejected_not_provisioned, (later) user.pending_approval / user.approved.

3d. Specify the frontend error contract now (§11 Q4, §9.3 risk). UnauthorizedException inside an OAuth callback (a redirect flow) surfaces as a generic failure unless handled. Carry a structured code on the redirect (?error=account_not_provisioned) and render remediation on the login page.

3e. Add the misconfiguration advisory — app + docs + defaults. The ADR's own §9.2 negative ("admins can set REGISTRATION_DISABLED=true but forget the SSO flag") has a mitigation:

• Boot: log a coherence warning when REGISTRATION_DISABLED=true while external auth is configured with jit.
• Admin UI: the same check feeds a small reusable "configuration advisories" mechanism — computed at boot, served on an authenticated admin endpoint (note: the existing /server settings payload is fetched pre-auth and must not carry config posture), rendered as a dismissible post-login notification + persistent admin-panel entry with the exact variable, current effective behavior, and the options. This is GitLab's admin-area-warnings pattern, and it is the upgrade/transition path: admins discover the new knob in-app rather than in release notes.
• Public login modal: user remediation ONLY, never config posture — advertising "this instance auto-creates accounts" pre-auth is reconnaissance for attackers.

4. UX sketches

Login modal — rejected (disabled mode), via redirect error code:

┌────────────────────────────────────────────────────────┐
│  ⚠  Sign-in not completed                              │
│     Your Okta identity was verified, but no Heimdall   │
│     account exists for you. Contact your Heimdall      │
│     administrator to request an account.               │
├────────────────────────────────────────────────────────┤
│   Email    [                    ]                      │
│   Password [                    ]        [ LOGIN ]     │
│  ───────────────── or sign in with ─────────────────   │
│        [ Okta ] [ GitHub ] [ Google ] [ LDAP ]         │
└────────────────────────────────────────────────────────┘

Admin panel — persistent configuration advisory (post-login, dismissible):

┌─ Admin ▸ Configuration Advisories ───────────────────────────────┐
│  ⚠ External auth auto-creates users while registration disabled │
│  Your settings:  REGISTRATION_DISABLED=true                      │
│                  EXTERNAL_AUTH_USER_PROVISIONING=(unset → jit)   │
│  Effective: identities from Okta/GitHub/Google/LDAP still get    │
│  Heimdall accounts automatically on first login.                 │
│                                                                  │
│  To change, set EXTERNAL_AUTH_USER_PROVISIONING to:              │
│    jit       auto-create on first login         (current)        │
│    approval  create, block until you approve     ◀ recommended   │
│    disabled  reject sign-ins with no account                     │
│  [ VIEW DOCS ]                                     [ DISMISS ]   │
└──────────────────────────────────────────────────────────────────┘

Admin ▸ Users — approval queue (phase 2 payoff: default-deny with one-click approvals, no manual email matching):

│  ● PENDING APPROVAL (2)                                          │
│  │ jdoe@agency.gov   Jane Doe   via okta   2h ago                │
│  │                             [ APPROVE ]  [ DENY ]             │

5. Migration story this enables

1. Release N: enum ships, default jit — zero behavior change for every existing deployment; the advisory makes the previously-silent behavior visible in-app.
2. Docs: one table mapping the three controls (LOCAL_LOGIN_DISABLED, REGISTRATION_DISABLED, EXTERNAL_AUTH_USER_PROVISIONING) to the three account paths.
3. Phase 2: approval mode + pending-user state + admin queue — a switch case, not a redesign.
4. Future (optional): if the default ever moves toward deny, the advisory channel announces it a release ahead — standard two-release deprecation, already built.

6. Direct answers to §11 review questions

1. Name: EXTERNAL_AUTH_USER_PROVISIONING (enum) — or at minimum EXTERNAL_AUTH_AUTO_CREATE_USERS_DISABLED; "SSO" is wrong because LDAP is provably covered.
2. LDAP: already covered — ldap.strategy.ts:78 calls validateOrCreateUser. Rewrite §9.3 as a settled statement.
3. Audit logging: yes, in scope — it's the artifact §1.3 promises.
4. Frontend: specific message via structured redirect error code; never a generic failure for an intentional policy rejection.

Smaller items

• Behavior matrix: add the top operational failure row — pre-provisioned user whose local email doesn't exactly match the IdP email, policy on → rejected (§8.2 warns about it; the matrix is where operators will debug it).
• §6.2: one sentence on email-binding risk — an IdP allowing user-editable/unverified emails can bind to someone else's pre-provisioned account.
• Header: Author: TBD needs filling; branch name in the header will be stale after a rename.

[aaronlippold]

Re-review of the revised ADR — endorsed, with answers to §12 and a set of edits

The REGISTRATION_DISABLED enum rework is the better design: one variable, four policies, and true finally means what admins always assumed it meant — it repairs the original expectation gap at the root instead of adding a knob beside it. Fail-closed breakage is the right direction to break. Endorsed.

Answers to the §12 review questions, plus edits being applied directly to the ADR in a follow-up commit:

Q1 — unknown values: fail fast. The enum makes permissive-on-unknown more dangerous than before: REGISTRATION_DISABLED=locel (typo) silently opens both account-creation paths — in a variable whose purpose is deny. A security-policy variable should refuse to start on garbage, not default open. (Telling detail: the §7.1 test table has no unknown-value rows.) Edit: startup validation rejects anything outside false|true|local|sso (empty/unset = false), with tests.

Q2 — yes, it's a breaking change, and release notes are the weakest channel. The cohort that breaks (true + relying on SSO JIT) can be targeted precisely at upgrade time: boot check — REGISTRATION_DISABLED=true AND any external auth strategy enabled → one WARN: "As of vX.Y, true also disables SSO/LDAP auto-account creation. Set REGISTRATION_DISABLED=local for the previous behavior." Edit: new implementation subsection + sp:1 work-order phase, and the release/migration note promoted from "should we?" to a required deliverable.

Q3 — split it. Admin user creation while LOCAL_LOGIN_DISABLED=true is a separate concern from registration policy; keeping it in this ADR's scope would tangle two policies. Left as the one open question.

Also restored: the frontend rendering contract. The revision keeps the account_not_provisioned error code (good) but dropped the original Q4 — how the login page renders it. Without a rendering spec, an intentional policy rejection surfaces as a generic auth failure, which §9.3 itself lists as the risk. Edit: short subsection specifying the login-page alert (identity verified / no account / contact admin), carried as a redirect query param consistent with existing OAuth failure handling.

Two hygiene edits:

• §4 gains Option E (GitLab-style approval queue: auto-created-but-blocked-pending-approval), rejected for this ADR with the structural note that "approval" is not a kind of "disabled" and can never be a value of this enum — if ever wanted it's a separate future mechanism. Recorded so nobody invents REGISTRATION_DISABLED=sso-approval later.
• The §2 value table and §5 behavior matrix get explicit LDAP callouts — the glossary covers it, but the value table is what operators actually read.

Edits incoming on this branch.

[aaronlippold]

Deep review + research pass applied — seven commits on this branch

Following up on my earlier endorsement: I ran a full verification pass over the revised ADR (every finding independently re-checked against the code before being applied), plus a targeted research pass with every citation verified against primary sources. Net result: the enum design held up across all of it — nothing overturned the core decision. What changed is precision, evidence, and scope-honesty. Highlights worth your eyes:

The two things that were blocking

1. §3.6's error transport didn't exist. OAuth failures actually reach the login page via the authenticationError cookie set by AuthenticationExceptionFilter (rendered as a generic snackbar) — there is no query-parameter channel. The contract is respecced onto real transports: a second authenticationErrorCode cookie for OAuth callbacks, and the 401 JSON body for the LDAP/local POST flows (which have no exception filter — under the old spec an LDAP user would have gotten exactly the generic failure §9.3 warns about).
2. The 401 body shape is now verified, not assumed (@nestjs/common@11.1.28 + current docs): an object passed to UnauthorizedException replaces the entire body, so the snippets include statusCode explicitly. Exact wire body is pinned in §3.5.

Other substantive additions

• Second breaking cohort acknowledged (§6.2): values like 1/yes/typos run silently permissive today and will refuse to boot after fail-fast lands — plus an upgrade-ordering/rollback rule (local/sso are fully permissive on pre-upgrade code).
• §8.2 runbook conflict: LOCAL_LOGIN_DISABLED=true blocks POST /users for admins too — pre-provision before disabling local login.
• Email handling: findByEmail is case-sensitive with zero normalization anywhere — the ADR now requires trim+lowercase at the choke point (mixed-case IdP emails would otherwise break pre-provisioning). Multi-valued LDAP mail and missing-email behavior specified.
• sso's guarantee stated precisely (§2/§6.3): it blocks silent JIT, not self-provisioning — with registration open and no email verification, register-then-SSO-bind works (this is the Classic-Federated-Merge class from the USENIX 2022 pre-hijacking paper; mitigation carded as open question 12.4).
• NIST mapping (§6.1): AC-2/IA-4/800-63C-4 §4.6.3 — deployers can cite the ADR in ATO docs.
• LDAP strategy await fix, filter log redaction, pinned audit-event shape, §7.5 filter tests + §7.6 frontend tests, and standards/precedent citations throughout (PostgreSQL/Django for the fail-fast pattern, GitLab/Grafana/Mattermost for the error-code UX).

ADR-005 + work tracking

• ADR-005 (docs/adr-005-vitepress-documentation-site.md): VitePress docs site on the vulcan pattern — because the wiki can't be PR'd, which is exactly the Phase 9 problem. Wiki remains the channel until it lands.
• Beads epics ready: heimdall2-4qg (this ADR, 10 cards = the 10 phases) and heimdall2-yvx (ADR-005, 6 cards) — full card templates with ACs, TDD starting points, and verification commands. @Amndeep7 / Will — this should map straight onto the card/LOE task from the kickoff comment.
• Board setup: install bd (https://github.com/gastownhall/beads), then bd dolt pull from a heimdall2 checkout (fresh machine: bd bootstrap). Note: the board schema migrated v49→v54 today — if you have an existing beads clone, bd dolt pull on your current bd binary before upgrading bd. Team workflow skills: https://github.com/mitre/mitre-saf-skills. Details are in both ADRs' work-order sections.

Eugene — the seven commits are individually scoped if you want to review pass-by-pass; happy to walk through any finding. If anything reads as over-reach, flag it and we'll cut it back.

[wdower]

OK, now that I've actually read this PR, ADR, comments and all, a few things stick out.

@NickShumar you're good to proceed, but note that Aaron apparently already created beads for this work, so you should figure out if those are present in your local board and sync them if they aren't; I think you said you'd been making some yourself? Just check they're not duplicative. Let me know if you have trouble.

The ADR doc hasn't actually changed since we had that meeting about it weeks ago. Aaron added a comment with more context, that's all. The comment is a refinement to the suggested implementation of the decisions in the ADR, it doesn't change anything we agreed on as a team.

As previously discussed, ADR-005 should have gone in its own PR so we can review one thing at a time; I'll split it out later, @NickShumar you can ignore it for now. Proceed to work and close the rest of the beads and then we'll review the actual code. At a glance it seems like you've got the tests for TDD in place, which is a good sign.

[ejaronne]

REGISTRATION_DISABLED=false, true, local, SSO track down all samples, helm charts, of environment variables to update behavior descriptions PR name - update_REGISTRATION_DISABLED_behavior_breaking_change Eugene - update ADR Amndeep/Will - set up cards and initial LOE Nick, Sean, Olivia - review cards and feedback on LOE and any problems seen

Human-readable cards for current code from @NickShumar:

ADR-004: External Login Account Policy

Plain-language summary of cards .1 through .10

What this project was meant to solve

Heimdall lets people create and access accounts in two ways:

1. Local registration: A person signs up directly through Heimdall.
2. External login: A person signs in through an organization’s identity provider, such as OIDC, LDAP, GitHub, Google, GitLab, or Okta.

Before this work, an administrator could disable local registration, but Heimdall could still silently create a new account the first time someone used an external login.

This project gives administrators separate control over those two account-creation paths.

The new settings

Setting	Local sign-up	First-time external login
Not set or false	Allowed	Allowed; Heimdall creates the account
true	Blocked	Blocked
local	Blocked	Allowed; Heimdall creates the account
sso	Allowed	Blocked

People who already have a matching Heimdall account can continue signing in through their external provider under every setting.

---

Card .1 — Add the new configuration choices

Purpose

Give administrators the four settings shown above and make configuration mistakes safe.

What was completed

• Heimdall now understands false, true, local, and sso.
• Capitalization does not matter.
• Extra spaces around a value do not matter.
• An empty or missing setting keeps the existing permissive behavior.
• A misspelled or unsupported value stops Heimdall from starting instead of silently allowing account creation.
• The setting is checked when Heimdall starts.

Why this matters

A typo in a security setting can no longer accidentally open both account-creation paths.

How it was checked

Every valid value, capitalization variation, spacing variation, and representative invalid value was tested. Startup was also tested with valid and invalid settings.

Status: Completed

---

Card .2 — Prevent unwanted external account creation

Purpose

Stop Heimdall from creating a new account when external account creation is disabled.

What was completed

• Heimdall checks the policy before creating a missing external user.
• Unknown external users are blocked when the setting is true or sso.
• Unknown external users are created when the setting is unset, false, or local.
• Existing users can still sign in under every setting.
• External email addresses are trimmed and converted to lowercase before matching.
• Database errors are kept separate from normal “user not found” results.
• An external identity that does not provide an email receives a separate error.

Why this matters

Successful identity-provider authentication no longer automatically means that the person is authorized to receive a Heimdall account.

How it was checked

Tests covered new users, existing users, mixed-case email addresses, missing email addresses, database failures, and all policy values.

Status: Completed

---

Card .3 — Record rejected provisioning attempts

Purpose

Give administrators an audit record when a verified external identity is denied because no Heimdall account exists.

What was completed

Heimdall records:

• The type of event
• The external provider
• The normalized email address
• The reason for rejection
• The time of the event

Passwords and authentication tokens are not included.

Why this matters

Administrators can distinguish a policy rejection from a bad password, provider failure, or application problem.

How it was checked

Tests verified the event’s contents and confirmed that sensitive authentication material was excluded.

Status: Completed

---

Card .4 — Preserve the reason for the login failure

Purpose

Ensure the browser receives a reliable reason code when a person is authenticated externally but lacks a Heimdall account.

What was completed

• OAuth and OIDC callback logins preserve the account_not_provisioned reason.
• LDAP login responses preserve the same reason.
• Other authentication failures continue using their existing generic messages.
• Sensitive callback information, such as authorization codes, state values, cookies, and authorization headers, is removed or redacted from diagnostic logs.

Why this matters

The frontend can show the correct explanation instead of treating the event as an ordinary login failure.

How it was checked

Tests covered both browser-redirect and direct-login response paths, generic failures, cookies, response bodies, and log redaction.

Status: Completed

---

Card .5 — Show a clear message to the person signing in

Purpose

Replace the generic authentication error with a useful explanation.

What was completed

When the policy blocks account creation, the login page shows a warning similar to:

Sign-in not completed. Your identity was verified, but no Heimdall account exists for you. Contact your Heimdall administrator to request an account.

The message identifies the provider the person attempted to use, such as LDAP, Okta, or the configured OIDC provider.

The normal generic error message is suppressed for this specific condition.

The Sign Up option follows the policy:

• Hidden for true and local
• Visible for unset, false, and sso

Why this matters

People know that their external identity worked and that they need a Heimdall account. They are not incorrectly told that their credentials failed.

How it was checked

Frontend tests covered OIDC and LDAP, recognized and unrecognized errors, provider names, Sign Up visibility, and generic-message suppression. The alert was also reviewed in light and dark modes.

Status: Completed

---

Card .6 — Warn administrators about important startup conditions

Purpose

Alert administrators when an upgrade or unsafe identity-provider configuration may change access behavior.

What was completed

• Heimdall warns when true is used with an external provider because true now blocks external account creation as well as local registration.
• The warning explains that local preserves the older “local registration blocked, external creation allowed” behavior.
• Heimdall warns when pre-provisioned access is combined with an OIDC setting that permits unverified email addresses.
• Each warning appears once during startup rather than repeatedly during normal use.

Why this matters

Administrators receive actionable guidance at the time a configuration could surprise them or create an account-security risk.

How it was checked

Tests and live startup checks covered OIDC-only, LDAP-only, no-provider, safe, unsafe, and migration-related configurations.

Status: Completed

---

Card .7 — Test the complete policy matrix

Purpose

Prove that each setting behaves correctly for local registration and external login.

What was completed

Tests cover:

• All four explicit values plus the unset default
• Local registration
• First-time external login
• Existing external users
• Administrator account-creation behavior
• Email normalization
• Startup validation
• Warning conditions
• Error delivery to the browser

Additional mutation checks deliberately broke important conditions to confirm that the tests would detect those failures.

Why this matters

The policy is not supported by only a few happy-path tests. Each meaningful branch has evidence.

How it was checked

The affected backend test matrices passed 108 out of 108 checks. The full backend suite, builds, type checks, and accepted lint baseline were also reviewed.

Status: Completed

---

Card .8 — Make LDAP and OIDC follow the same policy

Purpose

Ensure LDAP failures travel through the correct authentication path and that external providers cannot bypass the shared policy.

What was completed

• LDAP now waits for Heimdall’s user check to complete.
• LDAP reports provisioning rejections through the normal authentication error path.
• LDAP and OIDC use the same central account-creation policy.
• End-to-end coverage verifies that a valid LDAP identity is rejected without creating a database user when external provisioning is disabled.
• Existing ordinary login behavior remains intact.

Why this matters

LDAP is covered by the same “SSO” policy even though it is not an OAuth provider.

How it was checked

• Backend tests: 288 out of 288 passed.
• Provisioning-denied browser test: 1 out of 1 passed.
• Existing login browser tests: 8 out of 8 passed.
• Live LDAP test confirmed the number of users did not increase after rejection.

Status: Completed

---

Card .9 — Document the setting and upgrade impact

Purpose

Explain the new choices and prevent upgrades from unexpectedly blocking or allowing users.

What was completed in this repository

• The example backend environment file describes every value.
• The deployment manifest uses a quoted string so tools do not mistakenly turn the value into a simple true/false value.
• The changelog identifies the behavior change.
• A version-specific v2.13.2 upgrade note explains:
  • Who is affected
  • How to preserve earlier behavior
  • How to roll forward safely
  • How to roll back safely
  • Email-matching requirements
  • LDAP’s first-email-value behavior
  • The risk of unverified identity-provider email claims

External documentation still awaiting authorization

• The Heimdall environment-variables wiki was drafted but not published.
• The Heimdall authentication-methods wiki update was drafted but not published.
• The separate mitre/saf-packaging RPM environment description was not changed.

Those external writes were not made because authorization was not provided. The exact proposed wiki wording is preserved in the local Card .9 notes.

What was not included

ADR-005’s proposed VitePress documentation site was not implemented.

How it was checked

Repository documentation surfaces were searched and reviewed, the backend regression suite passed, and the production build passed.

Status: Repository work completed; external documentation follow-up remains

---

Card .10 — Test the complete behavior with a real OIDC provider

Purpose

Verify the feature against a running Heimdall application and a real OIDC authorization flow rather than relying only on unit-test simulations.

What was completed

A live Dex OIDC provider was used to test:

• Existing users under every policy value
• Unknown users under every policy value
• Account creation under the allowed values
• Rejection without account creation under true and sso
• Mixed-case external email matching
• Provider-named warning messages
• Light and dark display modes
• Startup warnings
• Invalid-value startup refusal

Each login used a separate identity and included a database check.

Why this matters

The real provider, callback, token exchange, user-information lookup, Heimdall account check, browser response, and database behavior were exercised together.

How it was checked

• All 10 policy-and-user matrix combinations passed.
• All 4 light/dark warning screenshots passed visual review.
• Warning counts matched expectations.
• Invalid configuration refused startup with the correct explanation.
• Temporary test users and services were cleaned up.

Status: Completed

---

Manual user test performed after the PR update

We also started Heimdall locally with REGISTRATION_DISABLED=sso and used the bundled OIDC provider from a browser.

The observed behavior was:

1. An unknown external identity was rejected.
2. The dedicated “Sign-in not completed” message appeared.
3. Local Sign Up remained available, as required for sso.
4. Creating a local account with the matching email succeeded, confirming that the rejected login had not silently created one.
5. The same external identity then signed in successfully.
6. Heimdall updated the account name from the identity provider, which is existing intended behavior.

The mock provider deliberately marks only its first identity response as verified. Restarting the mock resets it; the later “verify your name and email” message was mock behavior rather than a problem with the feature.

---

Overall result

• All ten implementation cards are closed.
• The final independent acceptance review passed all seven epic-level requirements.
• The core feature is implemented and tested.
• SonarCloud’s GitHub Action warning was fixed by pinning the Cypress action to an immutable version.
• The branch is synchronized with the branch used by PR Update_REGISTRATION_DISABLED_behavior (breaking change) #8383.

Remaining follow-up

1. Decide whether to publish the two drafted wiki updates.
2. Update the separate mitre/saf-packaging RPM environment description.
3. Change ADR-004’s status from Proposed when maintainers formally accept it.
4. Explicitly close the parent Beads epic if desired.
5. Complete normal PR review and merge.

Items such as SCIM, group and role mapping, provider-specific controls, approval queues, email verification for local registration, and ADR-005’s VitePress site were intentionally outside this project.

[ejaronne]

OK, now that I've actually read this PR, ADR, comments and all, a few things stick out.

@NickShumar you're good to proceed, but note that Aaron apparently already created beads for this work, so you should figure out if those are present in your local board and sync them if they aren't; I think you said you'd been making some yourself? Just check they're not duplicative. Let me know if you have trouble.

The ADR doc hasn't actually changed since we had that meeting about it weeks ago. Aaron added a comment with more context, that's all. The comment is a refinement to the suggested implementation of the decisions in the ADR, it doesn't change anything we agreed on as a team.

As previously discussed, ADR-005 should have gone in its own PR so we can review one thing at a time; I'll split it out later, @NickShumar you can ignore it for now. Proceed to work and close the rest of the beads and then we'll review the actual code. At a glance it seems like you've got the tests for TDD in place, which is a good sign.

Note that these comments came after our ADR review/agreement on June 9. Hold off on these to a future phase, if project can support.

ADR-004 Review — verification, industry comparison, and recommended revisions

Reviewed against the heimdall2 source (617ea4388). Overall: sound decision, right placement (policy in AuthnService, not per-strategy), honest alternatives. The recommendations below strengthen it into a long-term design — several review questions in §11 can be answered definitively from the code.

1. Verification findings (against actual source)

ADR claim Verified
"Current behavior" snippet for validateOrCreateUser ✅ Matches authn.service.ts exactly
REGISTRATION_DISABLED does not gate the external-auth path ✅ Confirmed
Proposed config helper pattern ✅ isLocalLoginAllowed/isRegistrationAllowed both use ?.toLowerCase() !== 'true' — identical
§9.3 risk / §11 Q2: "LDAP may need a separate review if its login path does not call validateOrCreateUser" 🔑 LDAP already calls validateOrCreateUser (ldap.strategy.ts:78), same as all five OAuth strategies
The LDAP finding settles review questions 1 and 2 together: the gate covers LDAP automatically — and therefore the variable name SSO_AUTO_CREATE_USERS_DISABLED is a misnomer that will surprise LDAP-only deployments. The ADR's own glossary has the right term: EXTERNAL_AUTH_*.

2. Industry comparison

Product Design Notes
GitLab signup_enabled (local) + allow_single_sign_on (per-provider array, defaults deny) + block_auto_created_users (defaults true: JIT users created but blocked pending admin approval) The approval-queue middle state is absent from this ADR's alternatives
Grafana Per-provider allow_sign_up under each [auth.*] section This is the ADR's deferred Option C, shipped as a major product's primary design
SonarQube Provisioning mode: JIT (default) vs automatic/SCIM — mutually exclusive states, one switch Mode enum, not boolean accretion
Harbor oidc_auto_onboard boolean Closest to this ADR's proposal
Every product surveyed agrees with this ADR's core call: local registration and external-auth JIT are separate controls (rejecting Option A is industry-consistent). The gap: GitLab and SonarQube show two patterns this ADR doesn't consider — the approval queue and the mode enum.

Sources: GitLab OmniAuth · Grafana auth · SonarQube provisioning · Harbor OIDC

3. Recommended design changes

3a. Mode enum instead of boolean — GitLab's lesson is that booleans accrete into a config maze. One enum absorbs the future without migration:

EXTERNAL_AUTH_USER_PROVISIONING=jit | approval | disabled    # default: jit

• jit — current behavior (backwards-compatible default; existing deployments upgrade with zero change)
• disabled — this ADR's goal: unknown external identities rejected
• approval — reserved for phase 2 (GitLab's block_auto_created_users pattern): account created but blocked pending admin approval. Ships later as one switch case, not a new flag.

Fail-fast on unknown values at startup. Note the current boolean pattern silently treats a typo (ture) as permissive — a security-policy variable should refuse to start on garbage, not default open.

3b. State the choke point as an architectural invariant. All six strategies (google, github, gitlab, okta, oidc, ldap) funnel through validateOrCreateUser — that is the real standardization mechanism. Add to the ADR: "All external-auth strategies MUST provision through AuthnService; any future strategy (e.g., SAML) inherits this policy by construction." Suggested shape:

async provisionExternalUser(identity: ExternalIdentity): Promise<User> {
  const existing = await this.findByEmail(identity.email);
  if (existing) return this.refreshMetadata(existing, identity);

  switch (this.config.externalAuthProvisioning()) {   // exhaustive
    case 'jit':      return this.createActiveUser(identity);
    case 'approval': return this.createPendingUser(identity);  // phase 2
    case 'disabled': throw new AccountNotProvisionedError();
  }
}

3c. Promote audit logging from review question (§11 Q3) to in-scope AC. §1.3's justification is "auditors expect account creation to be traceable" — the rejection event IS the audit artifact this feature exists to produce. Structured events at the choke point: external_auth.user.jit_created, external_auth.login.rejected_not_provisioned, (later) user.pending_approval / user.approved.

3d. Specify the frontend error contract now (§11 Q4, §9.3 risk). UnauthorizedException inside an OAuth callback (a redirect flow) surfaces as a generic failure unless handled. Carry a structured code on the redirect (?error=account_not_provisioned) and render remediation on the login page.

3e. Add the misconfiguration advisory — app + docs + defaults. The ADR's own §9.2 negative ("admins can set REGISTRATION_DISABLED=true but forget the SSO flag") has a mitigation:

• Boot: log a coherence warning when REGISTRATION_DISABLED=true while external auth is configured with jit.
• Admin UI: the same check feeds a small reusable "configuration advisories" mechanism — computed at boot, served on an authenticated admin endpoint (note: the existing /server settings payload is fetched pre-auth and must not carry config posture), rendered as a dismissible post-login notification + persistent admin-panel entry with the exact variable, current effective behavior, and the options. This is GitLab's admin-area-warnings pattern, and it is the upgrade/transition path: admins discover the new knob in-app rather than in release notes.
• Public login modal: user remediation ONLY, never config posture — advertising "this instance auto-creates accounts" pre-auth is reconnaissance for attackers.

4. UX sketches

Login modal — rejected (disabled mode), via redirect error code:

┌────────────────────────────────────────────────────────┐
│  ⚠  Sign-in not completed                              │
│     Your Okta identity was verified, but no Heimdall   │
│     account exists for you. Contact your Heimdall      │
│     administrator to request an account.               │
├────────────────────────────────────────────────────────┤
│   Email    [                    ]                      │
│   Password [                    ]        [ LOGIN ]     │
│  ───────────────── or sign in with ─────────────────   │
│        [ Okta ] [ GitHub ] [ Google ] [ LDAP ]         │
└────────────────────────────────────────────────────────┘

Admin panel — persistent configuration advisory (post-login, dismissible):

┌─ Admin ▸ Configuration Advisories ───────────────────────────────┐
│  ⚠ External auth auto-creates users while registration disabled │
│  Your settings:  REGISTRATION_DISABLED=true                      │
│                  EXTERNAL_AUTH_USER_PROVISIONING=(unset → jit)   │
│  Effective: identities from Okta/GitHub/Google/LDAP still get    │
│  Heimdall accounts automatically on first login.                 │
│                                                                  │
│  To change, set EXTERNAL_AUTH_USER_PROVISIONING to:              │
│    jit       auto-create on first login         (current)        │
│    approval  create, block until you approve     ◀ recommended   │
│    disabled  reject sign-ins with no account                     │
│  [ VIEW DOCS ]                                     [ DISMISS ]   │
└──────────────────────────────────────────────────────────────────┘

Admin ▸ Users — approval queue (phase 2 payoff: default-deny with one-click approvals, no manual email matching):

│  ● PENDING APPROVAL (2)                                          │
│  │ jdoe@agency.gov   Jane Doe   via okta   2h ago                │
│  │                             [ APPROVE ]  [ DENY ]             │

5. Migration story this enables

1. Release N: enum ships, default jit — zero behavior change for every existing deployment; the advisory makes the previously-silent behavior visible in-app.
2. Docs: one table mapping the three controls (LOCAL_LOGIN_DISABLED, REGISTRATION_DISABLED, EXTERNAL_AUTH_USER_PROVISIONING) to the three account paths.
3. Phase 2: approval mode + pending-user state + admin queue — a switch case, not a redesign.
4. Future (optional): if the default ever moves toward deny, the advisory channel announces it a release ahead — standard two-release deprecation, already built.

6. Direct answers to §11 review questions

1. Name: EXTERNAL_AUTH_USER_PROVISIONING (enum) — or at minimum EXTERNAL_AUTH_AUTO_CREATE_USERS_DISABLED; "SSO" is wrong because LDAP is provably covered.
2. LDAP: already covered — ldap.strategy.ts:78 calls validateOrCreateUser. Rewrite §9.3 as a settled statement.
3. Audit logging: yes, in scope — it's the artifact §1.3 promises.
4. Frontend: specific message via structured redirect error code; never a generic failure for an intentional policy rejection.

Smaller items

• Behavior matrix: add the top operational failure row — pre-provisioned user whose local email doesn't exactly match the IdP email, policy on → rejected (§8.2 warns about it; the matrix is where operators will debug it).
• §6.2: one sentence on email-binding risk — an IdP allowing user-editable/unverified emails can bind to someone else's pre-provisioned account.
• Header: Author: TBD needs filling; branch name in the header will be stale after a rename.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[mergify]

This pull request has a conflict. Could you fix it @ejaronne?