Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions cmd/fanout/main_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -316,6 +316,21 @@ func TestCreateBreakGlassLoginLinkForActiveAdministrator(t *testing.T) {
}
}

// Break-glass exists for when the identity provider cannot help, so it must
// not depend on who owns accounts.
func TestCreateBreakGlassLoginLinkWhenIdentityProviderOwnsAccounts(t *testing.T) {
cfg := breakGlassTestConfig(t, auth.RoleAdmin, auth.UserStatusActive)
cfg.OIDCAdminGroups = "fanout-admins"
cfg.SCIMToken = "scim-test-token-0123456789abcdef0123"
var output bytes.Buffer
if err := createLoginLink(cfg, "user@example.com", true, &output); err != nil {
t.Fatalf("createLoginLink: %v", err)
}
if links, issued, breakGlassIssued := loginLinkState(t, cfg); links != 1 || issued != 0 || breakGlassIssued != 1 {
t.Fatalf("state = %d links, %d issued, %d break-glass issued; want 1, 0, 1", links, issued, breakGlassIssued)
}
}

func TestCreateBreakGlassLoginLinkRefusals(t *testing.T) {
const email = "user@example.com"
for _, tc := range []struct {
Expand Down
55 changes: 50 additions & 5 deletions docs/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,8 +145,11 @@ when there are no users.

Unknown fields return `400`. Email, role, and status changes revoke browser
sessions. Suspension also blocks sign-in and revokes the user's OAuth tokens
and pending authorization codes; reactivation does not restore them. Demotion,
suspension, and deletion cannot remove the last active administrator.
and pending authorization codes. Reactivation revokes any that remain, so a
reactivated user starts with no credentials and signs in again. Demotion,
suspension, and deletion cannot remove the last active administrator. With an
OIDC role mapping, some of these routes are refused; see
[Who owns accounts](#who-owns-accounts).
The first-run `POST /api/auth/setup` request uses `display_name` alongside
`email` and `setup_token`.

Expand Down Expand Up @@ -249,8 +252,9 @@ Fanout’s roles apply across the instance:
Removing a user from an allowed group at the identity provider prevents their
next login; it does not wait for a provisioning cycle.

If neither list is configured there is no allow policy to enforce, and
membership is managed locally through user administration.
If neither list is configured there is no allow policy to enforce. Membership
is then managed locally through user administration, unless a role mapping is
set; see [Who owns accounts](#who-owns-accounts).

### Role ownership

Expand All @@ -268,6 +272,46 @@ The last active administrator is never demoted by this reconciliation — the
installation would lose its ability to administer itself. Promote a second
administrator before expecting the mapping to apply to the first.

### Who owns accounts

Role mapping also moves account ownership to the identity provider, because a
later login with the same verified email would otherwise link to a local account
an administrator created. `GET /api/auth/status` reports the result as
`account_ownership`, and Settings shows it to everyone who is signed in:

| `account_ownership` | Configuration | Browser user routes refuse |
|---|---|---|
| `local` | No role mapping, with or without a SCIM token | Nothing |
| `identity_provider_roles` | Role mapping and `FANOUT_OIDC_AUTO_PROVISION`, no SCIM token | Creating a user and changing a role |
| `identity_provider_roles_no_provisioning` | Role mapping, no `FANOUT_OIDC_AUTO_PROVISION`, no SCIM token | Creating a user and changing a role |
| `identity_provider_directory` | Role mapping and a SCIM token | Creating and deleting a user; changing a role, status or email |

A refused request returns `403` with the code `managed_by_identity_provider`,
and it changes nothing. The check runs before the request body is validated,
except on `PATCH /api/users/{id}`, which has to decode the body to see whether
`email` is present. Malformed JSON there returns `400`.

To add users under a role mapping, set `FANOUT_OIDC_AUTO_PROVISION` with
`FANOUT_OIDC_ALLOWED_GROUPS` or `FANOUT_OIDC_ALLOWED_DOMAINS`, or configure a
SCIM token. With neither, `POST /api/users` is refused and a first login is
denied as not provisioned, so nobody new can get an account. Fanout still starts
in this configuration, logs a warning at startup, and Settings says so. Existing
accounts keep working.

Only `POST /api/users` and the `/api/users/{id}` routes are affected. These keep
working in every mode:

- SCIM provisioning and login-time role reconciliation and provisioning.
- `PATCH /api/users/{id}` with only `display_name`. A directory that sends
`displayName` overwrites the value on its next update.
- `POST /api/users/{id}/access/revoke`, which ends sessions and OAuth tokens
without changing the account.
- `POST /api/auth/setup` for the first administrator when no SCIM token is set.
- `fanout login-link --break-glass`.

Without a SCIM token, an administrator can still suspend, reactivate, delete and
change the email of a user from the browser routes.

### Microsoft Entra ID group overage

Past roughly 200 group memberships, Entra omits the `groups` claim from the
Expand Down Expand Up @@ -313,7 +357,8 @@ Without it the routes do not exist and nothing below applies.

With a token configured, Fanout prints no setup banner, `/api/auth/setup` returns
`410`, and `/api/auth/status` reports `setup_required: false`. The first
administrator comes from SCIM.
administrator comes from SCIM. Until one exists, signed-out API requests return
`401` with `no accounts have been provisioned yet`.

Fanout implements a small subset of SCIM 2.0 (RFC 7644) under `/scim/v2`.
Requests send `Authorization: Bearer <token>`, and bodies use
Expand Down
Loading
Loading