Skip to content

feat(auth): identity provider owns accounts when roles are mapped - #459

Merged
vishr merged 3 commits into
mainfrom
feat/idp-owns-accounts
Nov 9, 2026
Merged

vishr merged 3 commits into
mainfrom
feat/idp-owns-accounts

Conversation

@vishr

@vishr vishr commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

Closes #445.

With an OIDC group-to-role mapping, an administrator could still create local users and change roles. A later login with the same verified email then linked to that local account and the mapping overwrote its role. The browser user routes now leave those changes to the identity provider.

Behaviour

Configuration account_ownership Browser user routes refuse
No role mapping, with or without a SCIM token local Nothing
Role mapping and auto-provisioning, no SCIM token identity_provider_roles Create, role change
Role mapping, no auto-provisioning, no SCIM token identity_provider_roles_no_provisioning Create, role change
Role mapping and a SCIM token identity_provider_directory Create, delete, role, status, email

A refusal is 403 with the code managed_by_identity_provider. It changes nothing and names no group or token. Role mapping is one check in config, shared by the routes, login reconciliation and the startup warning, so a list of only commas and spaces counts as no mapping. It applies only in OIDC mode.

Upgrade note

This is a runtime and security behaviour change for installations with FANOUT_OIDC_ADMIN_GROUPS or FANOUT_OIDC_OPERATOR_GROUPS set: administrators lose those browser routes on upgrade.

With a role mapping, no SCIM token and FANOUT_OIDC_AUTO_PROVISION at its default of off, nobody new can get an account: POST /api/users is refused and a first login is denied as not provisioned. To add users, set FANOUT_OIDC_AUTO_PROVISION with FANOUT_OIDC_ALLOWED_GROUPS or FANOUT_OIDC_ALLOWED_DOMAINS, or configure a SCIM token. Fanout still starts in this configuration, because existing installs must keep starting after upgrade. It logs a warning at startup and Settings says so. Existing accounts keep working.

/api/auth/status gains account_ownership.

Paths left alone

  • SCIM create and patch, login-time provisioning, and role reconciliation. These are the identity provider's own paths and are tested with the refusal active.
  • PATCH /api/users/{id} with only display_name. The issue does not list it. A directory sending displayName overwrites it on its next update.
  • POST /api/users/{id}/access/revoke. It ends sessions and OAuth tokens and does not change the account, and an administrator needs it during an incident.
  • POST /api/auth/setup. It creates the first administrator when there is no SCIM token, and without it a role-mapped install has no first login path. With a SCIM token it already returns 410.
  • Local-mode self-signup. It cannot run in OIDC mode.
  • fanout login-link --break-glass. It writes no account fields, and issue and redemption are tested with role mapping and a SCIM token. There are no import, invite or restore routes beyond POST /api/users, which is refused.

UI

Fanout has no screen that creates, edits, suspends or deletes other users, so there are no controls to hide or disable. Settings gains a "User accounts" notice, shown only when the server reports an identity-provider mode, that says what is refused and why. When nothing can create accounts it is a warning that says so. It uses the shared Notice and is covered by Settings stories in the light and dark design check.

Follow-ups from the SCIM review

  • applyUpdate now revokes OAuth tokens and authorization codes on the transition into active as well. Accounts suspended before suspension revoked credentials, and tokens minted in a race with suspension, no longer become valid on reactivation. The test leaves a token and a code unrevoked on a suspended account and reactivates through both the browser route and SCIM; it fails against the old condition.
  • The empty-database messages no longer mention setup when a SCIM token is set.

Known limit

With role mapping and no SCIM token, an administrator can still change the email of an unlinked local account, and unlinked local accounts stay claimable by email at a later login. This PR does not close that path.

For reviewers

  • account_ownership is on the public /api/auth/status route, so an unauthenticated visitor can tell whether role mapping, auto-provisioning and SCIM are on. It carries no values, and that route already reports auth_mode and self_signup.
  • With a SCIM token and role mapping, an account cannot be deleted at all, because SCIM has no delete. Deactivation is the only offboarding path.
  • The refusal runs before body validation, except that PATCH /api/users/{id} has to decode the body to see whether email is present, so malformed JSON there returns 400.

Testing

just check passes, and just test-race passes for internal/api, internal/auth, internal/config and cmd/fanout. The full race suite was not run locally. The Settings stories pass the design check in light and dark at both review widths. The branch merges main to resolve conflicts in the generated browser assets.

vishr added 3 commits November 8, 2026 15:10
With an OIDC group-to-role mapping, an administrator could still create
local users and change roles. A later login with the same verified email
then linked to that local account, and the mapping overwrote the role, so
the browser routes were a second, conflicting source of accounts.

The browser user routes now refuse those changes with 403 and the code
managed_by_identity_provider. Adding a SCIM token extends the refusal to
status, email, and deletion, because the directory owns those too. SCIM and
login-time reconciliation go through the store and are not affected. Without
a mapping nothing changes, including with a SCIM token alone.

/api/auth/status publishes the mode as account_ownership so the browser
does not work it out from settings, and Settings explains it. Fanout has no
screen that changes other users, so there are no controls to hide.

Reactivation now revokes OAuth tokens and authorization codes as well.
Revocation ran only on leaving active, so accounts suspended before it
existed, and tokens minted in a race with suspension, became valid again.

The empty-database messages no longer mention setup when a SCIM token is
set, because browser setup is disabled in that configuration.
With a role mapping, no SCIM token, and auto-provisioning at its default of
off, POST /api/users is refused and a first login is denied as not
provisioned, so nobody new can get an account. Existing installations with
this combination must still start after upgrading, so this is a startup
warning and not a validation error.

/api/auth/status reports the case as its own mode. Settings no longer claims
the identity provider creates accounts when it does not, and the docs say
that adding users under a mapping needs auto-provisioning with an allow-list,
or SCIM.

The docs also state that PATCH /api/users/{id} returns 400 for malformed JSON
before the ownership check, since it must decode the body to see email.

The mapping check moves to config so the startup warning and the routes use
one definition.
Only the generated browser assets conflicted, so they are rebuilt from the
merged sources.
@vishr
vishr enabled auto-merge November 8, 2026 23:45
@vishr
vishr added this pull request to the merge queue Nov 8, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 8, 2026
@vishr
vishr added this pull request to the merge queue Nov 9, 2026
Merged via the queue into main with commit ce76164 Nov 9, 2026
31 checks passed
@vishr
vishr deleted the feat/idp-owns-accounts branch November 9, 2026 00:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Identity provider owns accounts when roles are mapped

1 participant