From 8080c25636bd87fb4e2bdf8ed66a7319ebd4dd6b Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Sun, 8 Nov 2026 11:25:00 -0800 Subject: [PATCH 1/2] feat(auth): add SCIM 2.0 user provisioning Nothing tells an instance that a person was removed: eligibility is checked at login only, so browser sessions and MCP tokens outlive the removal. An install also cannot have its first administrator created by automation. FANOUT_SCIM_TOKEN enables POST, GET and PATCH on the SCIM Users resource. The account and its identity (configured issuer, externalId) are written in one transaction, so a crash cannot leave an unlinked account for a later login to claim by email. Requests are safe to repeat: a POST for a known identity returns the account unchanged, and a PATCH that changes nothing writes nothing. Deactivation also revokes OAuth tokens. The per-request status check stops them during suspension but would let them work again after reactivation. With a token set there is no setup banner and the setup route returns 410. Without one, SCIM paths are classified as before. Closes #442 --- .env.example | 6 + cmd/fanout-docgen/routes.go | 2 + cmd/fanout/main.go | 10 +- cmd/fanout/setup_banner_test.go | 26 + docs/authentication.md | 89 ++- docs/operations.md | 1 + internal/api/auth.go | 5 +- internal/api/auth_middleware.go | 41 +- internal/api/auth_test.go | 16 + internal/api/describe.go | 3 + internal/api/oauth_test.go | 8 +- internal/api/scim.go | 637 +++++++++++++++++ internal/api/scim_test.go | 669 ++++++++++++++++++ internal/auth/audit.go | 2 +- internal/auth/identity_store.go | 18 +- internal/auth/provisioning.go | 208 ++++++ internal/auth/provisioning_test.go | 349 +++++++++ internal/auth/user_store.go | 98 ++- internal/config/config.go | 11 + internal/config/config_test.go | 63 ++ .../docs/docs/concepts/authentication.mdx | 33 + site/src/content/docs/docs/reference/api.mdx | 4 + .../docs/reference/configuration/auth.mdx | 5 + 23 files changed, 2269 insertions(+), 35 deletions(-) create mode 100644 cmd/fanout/setup_banner_test.go create mode 100644 internal/api/scim.go create mode 100644 internal/api/scim_test.go create mode 100644 internal/auth/provisioning.go create mode 100644 internal/auth/provisioning_test.go diff --git a/.env.example b/.env.example index 2fbe451d8..4429cc6a8 100644 --- a/.env.example +++ b/.env.example @@ -218,6 +218,12 @@ # Default: false # FANOUT_ROLLUP_SKIP_TO_LATEST= +# FANOUT_SCIM_TOKEN; string; secret +# Enables SCIM 2.0 user provisioning under /scim/v2 and turns off browser setup; requires OIDC mode and at least 32 characters. +# Default: (empty) +# FANOUT_SCIM_TOKEN= +# Alternatively set FANOUT_SCIM_TOKEN_FILE to a secret file path; do not set both. + # FANOUT_SELF_SIGNUP; boolean # Allows verified email addresses to create viewer accounts; requires local auth and SMTP. # Default: false diff --git a/cmd/fanout-docgen/routes.go b/cmd/fanout-docgen/routes.go index f3c6552c8..78e34448f 100644 --- a/cmd/fanout-docgen/routes.go +++ b/cmd/fanout-docgen/routes.go @@ -219,6 +219,8 @@ func requirement(doc api.RouteDoc) string { return "any signed-in user" case api.RoutePolicyProtocol: return "protocol handshake" + case api.RoutePolicySCIM: + return "SCIM bearer token, when `FANOUT_SCIM_TOKEN` is set" case api.RoutePolicyServiceCredential: return fmt.Sprintf("`%s`, or a service credential", doc.Capability) case api.RoutePolicyCapability: diff --git a/cmd/fanout/main.go b/cmd/fanout/main.go index 41fd3fff0..4e69282ad 100644 --- a/cmd/fanout/main.go +++ b/cmd/fanout/main.go @@ -221,7 +221,7 @@ func main() { slog.Error("auth status init failed", "err", err) os.Exit(1) } - if userCount == 0 { + if setupBannerRequired(userCount, cfg) { token, _, err := setup.Rotate() if err != nil { slog.Error("setup token init failed", "err", err) @@ -345,6 +345,7 @@ func main() { api.RegisterHealthRoutes(e, q, cfg, oidcDiscovery) api.RegisterUserRoutes(e, userStore, smtpCfg, cfg) + api.RegisterSCIMRoutes(e, cfg, userStore, identityStore) api.RegisterSettingsRoutes(e, cfg, settingsStore, auditStore) slog.Info("auth enabled") @@ -790,6 +791,13 @@ func browserLoginURL(cfg config.Config) *url.URL { return loginURL } +// setupBannerRequired reports whether to mint the one-time setup credential. +// A SCIM token means accounts come from the provisioner, so the credential is +// never created and cannot reach the log. +func setupBannerRequired(userCount int64, cfg config.Config) bool { + return userCount == 0 && cfg.SCIMToken == "" +} + func printSetupBanner(httpAddr, token string) { lines := []string{ "============================================================", diff --git a/cmd/fanout/setup_banner_test.go b/cmd/fanout/setup_banner_test.go new file mode 100644 index 000000000..1c02ab604 --- /dev/null +++ b/cmd/fanout/setup_banner_test.go @@ -0,0 +1,26 @@ +package main + +import ( + "testing" + + "github.com/labstack/fanout/internal/config" +) + +func TestSetupBannerRequired(t *testing.T) { + scim := config.Config{SCIMToken: "configured"} + for _, tc := range []struct { + name string + count int64 + cfg config.Config + want bool + }{ + {"empty without SCIM", 0, config.Config{}, true}, + {"populated without SCIM", 1, config.Config{}, false}, + {"empty with SCIM", 0, scim, false}, + {"populated with SCIM", 1, scim, false}, + } { + if got := setupBannerRequired(tc.count, tc.cfg); got != tc.want { + t.Errorf("%s = %v, want %v", tc.name, got, tc.want) + } + } +} diff --git a/docs/authentication.md b/docs/authentication.md index 3915da7d4..c943e4b3d 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -303,16 +303,103 @@ require a browser session. Administrators can still revoke all of a user's access, including browser sessions and OAuth tokens, through `POST /api/users/{id}/access/revoke`. +## SCIM provisioning + +Set `FANOUT_SCIM_TOKEN` (or `FANOUT_SCIM_TOKEN_FILE`) to let an identity provider +or automation create, update and deactivate accounts. The setting requires +`FANOUT_AUTH_MODE=oidc` and a value of at least 32 characters with no whitespace. +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. + +Fanout implements a small subset of SCIM 2.0 (RFC 7644) under `/scim/v2`. +Requests send `Authorization: Bearer `, and bodies use +`application/scim+json` or `application/json`. Responses use +`application/scim+json`, and failures use the RFC 7644 error format. + +| Route | Purpose | +|---|---| +| `POST /scim/v2/Users` | Create an account and link its identity | +| `GET /scim/v2/Users?filter=...` | Find an account | +| `GET /scim/v2/Users/{id}` | Read an account | +| `PATCH /scim/v2/Users/{id}` | Change `active`, the role, the email or `displayName` | + +Other methods return `405` and other paths under `/scim/v2` return `404`. Delete +is not supported; deactivate with `active: false`. The `ServiceProviderConfig`, +`Schemas` and `ResourceTypes` discovery endpoints are not implemented. + +### Creating accounts + +`POST` requires the core User schema, `externalId`, `userName` and one value in +`roles`. `externalId` is the subject (`sub`) at the configured issuer, and is +treated as an exact opaque string. `userName` is the email address. If `emails` +is sent, its primary value must be the same address. The role is `admin`, +`operator` or `viewer`. `active` defaults to `true`. + +The account and the identity `(FANOUT_OIDC_ISSUER_URL, externalId)` are written +in one transaction with their audit events. The user's first OIDC login finds +that identity, so no match by email takes place. + +A `POST` for an identity that already exists returns `200` with the current +account and changes nothing, so a delayed retry cannot undo a later change. Send +a `PATCH` to change an existing account. A new account returns `201`. An email +held by a different account returns `409` with `scimType` `uniqueness`; Fanout +never links an existing account by email. + +While there are no users, only an active administrator can be created, using the +same transactional check as setup. Any other request returns `409`, so it can be +retried once an administrator exists. Concurrent administrators are all created. + +### Finding accounts + +`filter` accepts exactly `externalId eq "value"` and `userName eq "value"`. +Attribute names and `eq` are case-insensitive, and the value is a JSON string, +so `"` and `\` must be escaped. `externalId` matches exactly; `userName` is +normalized like any email address. Anything else, including a missing filter, +returns `400` with `scimType` `invalidFilter`. `startIndex` and `count` are +accepted. + +### Updating accounts + +`PATCH` takes the `PatchOp` schema with `add` or `replace` operations on `active`, +`roles`, `userName`, `emails` and `displayName`, with or without a `path`. A path +filter such as `emails[type eq "work"].value` is not supported. `remove` returns +`400`. All operations in a request apply as one update, so the checks below see +the final state. + +A request that changes nothing returns `200` and writes nothing: no session +revocation, no token revocation and no audit event. Resending the same state is +safe. Changing the email or reactivating an account keeps its identity link. + +Deactivating or demoting the last active administrator returns `409`. The check +runs in the same write transaction as the update. + +Deactivation suspends the account. In one transaction it revokes the user's +browser sessions, revokes their MCP OAuth access and refresh tokens, and deletes +their pending OAuth authorization codes. Reactivation restores none of these, so +the user signs in and connects MCP clients again. + +Every change writes an audit event: `user.provisioned` and `identity.linked` on +creation, then `user.suspended`, `user.reactivated`, `role.changed` or +`user.updated`. Metadata records `mode: scim`, which fields changed and any role +or status transition. Addresses and the token are never recorded. + +The token is compared in constant time and is never logged. Rotate it by +changing the setting and restarting Fanout. + ## Credentials at a glance | Credential | Purpose | Rotation | |---|---|---| -| Setup URL | Creates the first administrator | One-time, expires in 1 hour | +| Setup URL | Creates the first administrator | One-time, expires in 1 hour; not issued when `FANOUT_SCIM_TOKEN` is set | | Login URL | Authenticates one existing active local user | One-time, expires in 15 minutes; mint with `fanout login-link` | | Break-glass URL | Authenticates one active administrator in OIDC mode | One-time, expires in 15 minutes; mint with `fanout login-link --break-glass` | | Browser session | Interactive access | Idle and absolute TTL; revoked on role, email, or status change | | Ingest token | OTLP ingest | Settings page; `FANOUT_INGEST_TOKEN` sets only the first token | | Metrics token | `/metrics` scrape | `FANOUT_METRICS_TOKEN` | +| SCIM token | User provisioning at `/scim/v2` | `FANOUT_SCIM_TOKEN`; change the setting and restart | | MCP OAuth tokens | MCP clients | 30-day access tokens, checked on every request; 90-day refresh tokens renewed on each use. Refresh rotation with replay-family revocation, admitting the same client's rotated token for one access-token lifetime so processes sharing a credential can refresh from stale copies. Users disconnect individual agents in Settings; admins can still revoke all of a user's access | Local email codes allow three attempts per code and expire after five minutes. diff --git a/docs/operations.md b/docs/operations.md index fa9f89c7e..3c6342f10 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -33,6 +33,7 @@ Every secret accepts either its value or its file path: | `FANOUT_SMTP_PASSWORD` | `FANOUT_SMTP_PASSWORD_FILE` | | `FANOUT_INGEST_TOKEN` | `FANOUT_INGEST_TOKEN_FILE` | | `FANOUT_METRICS_TOKEN` | `FANOUT_METRICS_TOKEN_FILE` | +| `FANOUT_SCIM_TOKEN` | `FANOUT_SCIM_TOKEN_FILE` | | `ANTHROPIC_API_KEY` | `ANTHROPIC_API_KEY_FILE` | | `OPENAI_API_KEY` | `OPENAI_API_KEY_FILE` | diff --git a/internal/api/auth.go b/internal/api/auth.go index 49261a0ef..bec5ebd7f 100644 --- a/internal/api/auth.go +++ b/internal/api/auth.go @@ -77,7 +77,7 @@ func (h *AuthHandler) Status(c *echo.Context) error { return echo.NewHTTPError(http.StatusInternalServerError, "failed to check auth status") } return c.JSON(200, map[string]any{ - "setup_required": count == 0, + "setup_required": count == 0 && h.cfg.SCIMToken == "", "auth_enabled": true, "auth_mode": strings.ToLower(strings.TrimSpace(h.cfg.AuthMode)), "agent_available": h.cfg.AgentConfigured(), @@ -87,6 +87,9 @@ func (h *AuthHandler) Status(c *echo.Context) error { } func (h *AuthHandler) Setup(c *echo.Context) error { + if h.cfg.SCIMToken != "" { + return echo.NewHTTPError(http.StatusGone, "browser setup is disabled because accounts are provisioned by SCIM") + } if !h.setupLimiter.Allow(c.RealIP()) { return rateLimited(c, 15*time.Minute) } diff --git a/internal/api/auth_middleware.go b/internal/api/auth_middleware.go index ed1ac6c8e..68b408b3c 100644 --- a/internal/api/auth_middleware.go +++ b/internal/api/auth_middleware.go @@ -54,6 +54,7 @@ const ( routePolicyCapability routePolicyServiceCredential routePolicyProtocol + routePolicySCIM ) type routePolicy struct { @@ -87,12 +88,21 @@ func RegisterAuthMiddleware(e *echo.Echo, users *auth.UserStore, sessions *auth. } func AuthMiddleware(users *auth.UserStore, sessions *auth.BrowserSessions, cfg config.Config) echo.MiddlewareFunc { + // Without a token, SCIM paths are classified exactly as if SCIM did not + // exist: unknown to the API and left to the browser application. + classify := classifyNonSCIMRoute + if cfg.SCIMToken != "" { + classify = classifyRoute + } return func(next echo.HandlerFunc) echo.HandlerFunc { return func(c *echo.Context) error { path := c.Request().URL.Path - policy, classified := classifyRoute(c.Request().Method, path) + policy, classified := classify(c.Request().Method, path) + if cfg.SCIMToken != "" && isSCIMPath(path) { + return authorizeSCIM(c, cfg.SCIMToken, classified, next) + } if !classified { - if routePathKnown(path) { + if routePathKnown(classify, path) { return echo.NewHTTPError(http.StatusMethodNotAllowed, "method not allowed") } // Echo may match the trace parameter to an empty or multi-segment ID. @@ -261,7 +271,30 @@ func constantTimeToken(presented, expected string) bool { return subtle.ConstantTimeCompare([]byte(presented), []byte(expected)) == 1 } +// classifyRoute is the full route table, used when SCIM is enabled and to +// document the routes. func classifyRoute(method, path string) (routePolicy, bool) { + if isSCIMPath(path) { + return classifySCIMRoute(method, path) + } + return classifyNonSCIMRoute(method, path) +} + +func classifySCIMRoute(method, path string) (routePolicy, bool) { + policy := routePolicy{kind: routePolicySCIM} + rest, ok := strings.CutPrefix(path, scimUsersPath) + switch { + case !ok: + return policy, false + case rest == "": + return policy, method == http.MethodGet || method == http.MethodPost + case strings.HasPrefix(rest, "/") && len(rest) > 1 && !strings.Contains(rest[1:], "/"): + return policy, method == http.MethodGet || method == http.MethodPatch + } + return policy, false +} + +func classifyNonSCIMRoute(method, path string) (routePolicy, bool) { read := method == http.MethodGet || method == http.MethodHead unsafe := method == http.MethodPost || method == http.MethodPut || method == http.MethodPatch || method == http.MethodDelete @@ -346,9 +379,9 @@ func isProtectedPath(path string) bool { return strings.HasPrefix(path, "/api/") || strings.HasPrefix(path, "/debug/") || path == "/metrics" } -func routePathKnown(path string) bool { +func routePathKnown(classify func(method, path string) (routePolicy, bool), path string) bool { for _, method := range []string{http.MethodGet, http.MethodHead, http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete} { - if _, ok := classifyRoute(method, path); ok { + if _, ok := classify(method, path); ok { return true } } diff --git a/internal/api/auth_test.go b/internal/api/auth_test.go index a0f54e855..0d4856898 100644 --- a/internal/api/auth_test.go +++ b/internal/api/auth_test.go @@ -204,6 +204,10 @@ func TestRoutePolicyClassification(t *testing.T) { {http.MethodPost, "/mcp", routePolicyProtocol, ""}, {http.MethodPost, "/api/mcp", routePolicyCapability, ReadTelemetry}, {http.MethodGet, "/assets/app.js", routePolicyPublic, ""}, + {http.MethodGet, "/scim/v2/Users", routePolicySCIM, ""}, + {http.MethodPost, "/scim/v2/Users", routePolicySCIM, ""}, + {http.MethodGet, "/scim/v2/Users/user-1", routePolicySCIM, ""}, + {http.MethodPatch, "/scim/v2/Users/user-1", routePolicySCIM, ""}, } for _, tc := range tests { policy, ok := classifyRoute(tc.method, tc.path) @@ -215,6 +219,18 @@ func TestRoutePolicyClassification(t *testing.T) { t.Errorf("%s %s policy = {%v %q}, want {%v %q}", tc.method, tc.path, policy.kind, policy.capability, tc.kind, tc.capability) } } + for _, tc := range []struct{ method, path string }{ + {http.MethodDelete, "/scim/v2/Users/user-1"}, + {http.MethodPut, "/scim/v2/Users/user-1"}, + {http.MethodPost, "/scim/v2/Users/user-1"}, + {http.MethodGet, "/scim/v2/Users/"}, + {http.MethodGet, scimUsersPath + "/user-1/extra"}, + {http.MethodGet, "/scim/v2/Groups"}, + } { + if _, ok := classifyRoute(tc.method, tc.path); ok { + t.Errorf("%s %s must be unclassified", tc.method, tc.path) + } + } if _, ok := classifyRoute(http.MethodPost, "/api/new-unreviewed-route"); ok { t.Fatal("unreviewed API route must be unclassified") } diff --git a/internal/api/describe.go b/internal/api/describe.go index 12ac456c4..7aa4cfb33 100644 --- a/internal/api/describe.go +++ b/internal/api/describe.go @@ -23,6 +23,7 @@ const ( RoutePolicyCapability = "capability" RoutePolicyServiceCredential = "service-credential" RoutePolicyProtocol = "protocol" + RoutePolicySCIM = "scim" ) // RouteDoc is what a reader needs to know before calling a route: whether it @@ -58,6 +59,8 @@ func DescribeRoute(method, path string) (RouteDoc, bool) { doc.Policy = RoutePolicyServiceCredential case routePolicyProtocol: doc.Policy = RoutePolicyProtocol + case routePolicySCIM: + doc.Policy = RoutePolicySCIM default: // A new kind added to the switch without a name here would otherwise be // published as an empty cell, which reads as "no requirement". diff --git a/internal/api/oauth_test.go b/internal/api/oauth_test.go index 870c92989..81801d4b4 100644 --- a/internal/api/oauth_test.go +++ b/internal/api/oauth_test.go @@ -32,6 +32,12 @@ func newOAuthTestServer(t *testing.T) (*echo.Echo, *auth.UserStore, *auth.Browse } func newOAuthTestServerWithConfig(t *testing.T, cfg config.Config) (*echo.Echo, *auth.UserStore, *auth.BrowserSessions) { + t.Helper() + e, users, sessions, _ := newOAuthTestServerAndDB(t, cfg) + return e, users, sessions +} + +func newOAuthTestServerAndDB(t *testing.T, cfg config.Config) (*echo.Echo, *auth.UserStore, *auth.BrowserSessions, *appstore.SQLite) { t.Helper() if cfg.PublicURL == "" { cfg.PublicURL = "https://fanout.example.com" @@ -86,7 +92,7 @@ func newOAuthTestServerWithConfig(t *testing.T, cfg config.Config) (*echo.Echo, w.WriteHeader(http.StatusNoContent) }))) e.GET("/api/auth/me", func(c *echo.Context) error { return c.NoContent(http.StatusNoContent) }) - return e, users, sessions + return e, users, sessions, sqlite } func TestMCPRejectsUnexpectedHostBeforeAuthentication(t *testing.T) { diff --git a/internal/api/scim.go b/internal/api/scim.go new file mode 100644 index 000000000..d081ffc8f --- /dev/null +++ b/internal/api/scim.go @@ -0,0 +1,637 @@ +package api + +import ( + "bytes" + "crypto/sha256" + "crypto/subtle" + "encoding/json" + "errors" + "io" + "log/slog" + "mime" + "net/http" + "strconv" + "strings" + "unicode/utf8" + + "github.com/labstack/echo/v5" + + appauth "github.com/labstack/fanout/internal/auth" + "github.com/labstack/fanout/internal/config" +) + +const ( + scimContentType = "application/scim+json" + scimUserSchema = "urn:ietf:params:scim:schemas:core:2.0:User" + scimListSchema = "urn:ietf:params:scim:api:messages:2.0:ListResponse" + scimPatchSchema = "urn:ietf:params:scim:api:messages:2.0:PatchOp" + scimErrorSchema = "urn:ietf:params:scim:api:messages:2.0:Error" + + scimRoot = "/scim/v2" + scimUsersPath = scimRoot + "/Users" + + // An OpenID Connect subject is at most 255 ASCII characters. + scimMaxExternalID = 255 +) + +// SCIMHandler serves the narrow SCIM 2.0 subset used to provision accounts: +// create, look up, and patch a user. Requests are authenticated by the route +// policy in AuthMiddleware before they reach it. +type SCIMHandler struct { + issuer string + publicURL string + users *appauth.UserStore + identities *appauth.IdentityStore +} + +// RegisterSCIMRoutes registers the routes only when a token is configured. +func RegisterSCIMRoutes(e *echo.Echo, cfg config.Config, users *appauth.UserStore, identities *appauth.IdentityStore) { + if cfg.SCIMToken == "" { + return + } + h := &SCIMHandler{issuer: cfg.OIDCIssuerURL, publicURL: strings.TrimRight(cfg.PublicURL, "/"), users: users, identities: identities} + e.GET("/scim/v2/Users", h.serve(h.listUsers)) + e.POST("/scim/v2/Users", h.serve(h.createUser)) + e.GET("/scim/v2/Users/:id", h.serve(h.getUser)) + e.PATCH("/scim/v2/Users/:id", h.serve(h.patchUser)) +} + +// scimError is an error with an RFC 7644 section 3.12 representation. +type scimError struct { + status int + scimType string + detail string +} + +func (e *scimError) Error() string { return e.detail } + +func scimFail(status int, scimType, detail string) error { + return &scimError{status: status, scimType: scimType, detail: detail} +} + +func writeSCIM(c *echo.Context, status int, body any) error { + encoded, err := json.Marshal(body) + if err != nil { + return err + } + header := c.Response().Header() + header.Set("Content-Type", scimContentType) + header.Set("Cache-Control", "no-store") + c.Response().WriteHeader(status) + _, err = c.Response().Write(encoded) + return err +} + +func writeSCIMError(c *echo.Context, failure *scimError) error { + body := map[string]any{ + "schemas": []string{scimErrorSchema}, + "detail": failure.detail, + "status": strconv.Itoa(failure.status), + } + if failure.scimType != "" { + body["scimType"] = failure.scimType + } + return writeSCIM(c, failure.status, body) +} + +// serve renders every handler failure as a SCIM error. +func (h *SCIMHandler) serve(handler func(*echo.Context) error) echo.HandlerFunc { + return func(c *echo.Context) error { + err := handler(c) + if err == nil { + return nil + } + var failure *scimError + if !errors.As(err, &failure) { + slog.Error("SCIM request failed", "method", c.Request().Method, "route", c.Path(), "err", err) + failure = &scimError{status: http.StatusInternalServerError, detail: "The request could not be completed."} + } + return writeSCIMError(c, failure) + } +} + +// authorizeSCIM is the route policy for SCIM paths. An authenticated request to +// a path or method the API does not serve gets a SCIM error rather than the +// product error format. +func authorizeSCIM(c *echo.Context, token string, classified bool, next echo.HandlerFunc) error { + if !scimTokenMatches(scimBearerToken(c.Request().Header.Get("Authorization")), token) { + c.Response().Header().Set("WWW-Authenticate", "Bearer") + return writeSCIMError(c, &scimError{status: http.StatusUnauthorized, detail: "A valid bearer token is required."}) + } + if classified { + return next(c) + } + if _, known := classifySCIMRoute(http.MethodGet, c.Request().URL.Path); known { + return writeSCIMError(c, &scimError{status: http.StatusMethodNotAllowed, detail: "This method is not supported."}) + } + return writeSCIMError(c, &scimError{status: http.StatusNotFound, detail: "Not found."}) +} + +func scimBearerToken(header string) string { + scheme, token, found := strings.Cut(header, " ") + if !found || !strings.EqualFold(scheme, "Bearer") { + return "" + } + return strings.TrimSpace(token) +} + +// scimTokenMatches hashes both sides first, so the comparison takes the same +// time for every input, including one of a different length. +func scimTokenMatches(presented, expected string) bool { + presentedSum, expectedSum := sha256.Sum256([]byte(presented)), sha256.Sum256([]byte(expected)) + return subtle.ConstantTimeCompare(presentedSum[:], expectedSum[:]) == 1 && presented != "" +} + +func isSCIMPath(path string) bool { + return path == scimRoot || strings.HasPrefix(path, scimRoot+"/") +} + +// scimBool accepts the string forms "True" and "False" as well as JSON +// booleans, because Microsoft Entra ID sends those for active and primary. +type scimBool bool + +func (b *scimBool) UnmarshalJSON(data []byte) error { + var value any + if err := json.Unmarshal(data, &value); err != nil { + return err + } + switch typed := value.(type) { + case bool: + *b = scimBool(typed) + return nil + case string: + switch { + case strings.EqualFold(typed, "true"): + *b = true + return nil + case strings.EqualFold(typed, "false"): + *b = false + return nil + } + } + return errors.New("must be a boolean") +} + +type scimMultiValue struct { + Value string `json:"value"` + Primary *scimBool `json:"primary"` +} + +type scimUserRequest struct { + Schemas []string `json:"schemas"` + ExternalID string `json:"externalId"` + UserName string `json:"userName"` + DisplayName string `json:"displayName"` + Active *scimBool `json:"active"` + Emails []scimMultiValue `json:"emails"` + Roles []scimMultiValue `json:"roles"` +} + +type scimPatchRequest struct { + Schemas []string `json:"schemas"` + Operations []struct { + Op string `json:"op"` + Path string `json:"path"` + Value json.RawMessage `json:"value"` + } `json:"Operations"` +} + +type scimResourceValue struct { + Value string `json:"value"` + Primary bool `json:"primary"` +} + +type scimMeta struct { + ResourceType string `json:"resourceType"` + Created string `json:"created"` + LastModified string `json:"lastModified"` + Location string `json:"location"` +} + +type scimUserResource struct { + Schemas []string `json:"schemas"` + ID string `json:"id"` + ExternalID string `json:"externalId,omitempty"` + UserName string `json:"userName"` + DisplayName string `json:"displayName,omitempty"` + Active bool `json:"active"` + Emails []scimResourceValue `json:"emails"` + Roles []scimResourceValue `json:"roles"` + Meta scimMeta `json:"meta"` +} + +func decodeSCIMBody(c *echo.Context, destination any) error { + mediaType, _, err := mime.ParseMediaType(c.Request().Header.Get("Content-Type")) + if err != nil || (mediaType != scimContentType && mediaType != "application/json") { + return scimFail(http.StatusUnsupportedMediaType, "", "Content-Type must be application/scim+json.") + } + body, err := io.ReadAll(http.MaxBytesReader(c.Response(), c.Request().Body, userBodyLimit)) + if err != nil { + var tooLarge *http.MaxBytesError + if errors.As(err, &tooLarge) { + return scimFail(http.StatusRequestEntityTooLarge, "", "The request body is too large.") + } + return scimFail(http.StatusBadRequest, "invalidSyntax", "The request body could not be read.") + } + decoder := json.NewDecoder(bytes.NewReader(body)) + if err := decoder.Decode(destination); err != nil { + return scimFail(http.StatusBadRequest, "invalidSyntax", "The request body is not a valid SCIM message.") + } + if _, err := decoder.Token(); !errors.Is(err, io.EOF) { + return scimFail(http.StatusBadRequest, "invalidSyntax", "The request body has trailing content.") + } + return nil +} + +func hasSchema(schemas []string, want string) bool { + for _, schema := range schemas { + if strings.EqualFold(schema, want) { + return true + } + } + return false +} + +// primaryValue returns the primary entry, or the only entry when none is marked. +func primaryValue(values []scimMultiValue) (string, bool) { + var primary []string + for _, value := range values { + if value.Primary != nil && bool(*value.Primary) { + primary = append(primary, value.Value) + } + } + switch { + case len(primary) == 1: + return primary[0], true + case len(primary) == 0 && len(values) == 1: + return values[0].Value, true + } + return "", false +} + +func parseSCIMRole(values []scimMultiValue) (appauth.Role, error) { + value, ok := primaryValue(values) + if !ok || !appauth.ValidRole(value) { + return "", scimFail(http.StatusBadRequest, "invalidValue", "roles must hold one value: admin, operator, or viewer.") + } + return appauth.Role(value), nil +} + +func parseSCIMEmails(values []scimMultiValue) (string, error) { + value, ok := primaryValue(values) + if !ok { + return "", scimFail(http.StatusBadRequest, "invalidValue", "emails must hold one primary value.") + } + return parseSCIMEmail(value, "emails") +} + +func parseSCIMEmail(value, attribute string) (string, error) { + email, err := appauth.NormalizeEmail(value) + if err != nil { + return "", scimFail(http.StatusBadRequest, "invalidValue", attribute+" must be a valid email address.") + } + return email, nil +} + +func scimAuditSource(c *echo.Context) appauth.AuditEvent { + return appauth.AuditEvent{RemoteIP: c.RealIP(), UserAgent: c.Request().UserAgent(), Metadata: map[string]any{"mode": "scim"}} +} + +func (h *SCIMHandler) createUser(c *echo.Context) error { + var req scimUserRequest + if err := decodeSCIMBody(c, &req); err != nil { + return err + } + if !hasSchema(req.Schemas, scimUserSchema) { + return scimFail(http.StatusBadRequest, "invalidSyntax", "schemas must include the core User schema.") + } + if strings.TrimSpace(req.ExternalID) == "" || len(req.ExternalID) > scimMaxExternalID { + return scimFail(http.StatusBadRequest, "invalidValue", "externalId must be between 1 and 255 bytes.") + } + email, err := parseSCIMEmail(req.UserName, "userName") + if err != nil { + return err + } + if len(req.Emails) != 0 { + primary, err := parseSCIMEmails(req.Emails) + if err != nil { + return err + } + if primary != email { + return scimFail(http.StatusBadRequest, "invalidValue", "userName and the primary email must be the same address.") + } + } + role, err := parseSCIMRole(req.Roles) + if err != nil { + return err + } + status := appauth.UserStatusActive + if req.Active != nil && !bool(*req.Active) { + status = appauth.UserStatusSuspended + } + + user, identity, created, err := h.users.ProvisionFederated(c.Request().Context(), appauth.ProvisionRequest{ + Issuer: h.issuer, Subject: req.ExternalID, Email: email, DisplayName: req.DisplayName, Role: role, Status: status, + }, scimAuditSource(c)) + switch { + case errors.Is(err, appauth.ErrFirstUserMustBeAdmin): + return scimFail(http.StatusConflict, "", "The first account must be an active administrator.") + case errors.Is(err, appauth.ErrUserConflict), errors.Is(err, appauth.ErrIdentityConflict): + return scimFail(http.StatusConflict, "uniqueness", "The email address belongs to a different account.") + case err != nil: + return err + } + resource := h.resource(user, identity.Subject) + c.Response().Header().Set("Location", resource.Meta.Location) + statusCode := http.StatusOK + if created { + statusCode = http.StatusCreated + } + return writeSCIM(c, statusCode, resource) +} + +func (h *SCIMHandler) getUser(c *echo.Context) error { + user, err := h.users.GetByIDContext(c.Request().Context(), c.Param("id")) + if errors.Is(err, appauth.ErrUserNotFound) { + return scimFail(http.StatusNotFound, "", "User not found.") + } + if err != nil { + return err + } + subject, err := h.linkedSubject(c, user.ID) + if err != nil { + return err + } + return writeSCIM(c, http.StatusOK, h.resource(user, subject)) +} + +func (h *SCIMHandler) listUsers(c *echo.Context) error { + attribute, value, ok := parseSCIMFilter(c.QueryParam("filter")) + if !ok { + return scimFail(http.StatusBadRequest, "invalidFilter", `Only externalId eq "value" and userName eq "value" are supported.`) + } + startIndex, err := scimQueryInt(c, "startIndex", 1) + if err != nil { + return err + } + count, err := scimQueryInt(c, "count", 1) + if err != nil { + return err + } + matches, err := h.lookup(c, attribute, value) + if err != nil { + return err + } + // A filter matches at most one account, so paging only decides whether + // that account is on the requested page. + response := map[string]any{ + "schemas": []string{scimListSchema}, "totalResults": len(matches), + "startIndex": max(startIndex, 1), "itemsPerPage": 0, + } + if len(matches) > 0 && startIndex <= 1 && count > 0 { + response["itemsPerPage"] = len(matches) + response["Resources"] = matches + } + return writeSCIM(c, http.StatusOK, response) +} + +func (h *SCIMHandler) lookup(c *echo.Context, attribute, value string) ([]scimUserResource, error) { + ctx := c.Request().Context() + var user appauth.User + var subject string + if attribute == "externalid" { + identity, err := h.identities.Find(ctx, h.issuer, value) + if errors.Is(err, appauth.ErrUserNotFound) { + return nil, nil + } + if err != nil { + return nil, err + } + if user, err = h.users.GetByIDContext(ctx, identity.UserID); err != nil { + return nil, err + } + subject = identity.Subject + } else { + // A userName that is not an address simply matches nothing. + email, err := appauth.NormalizeEmail(value) + if err != nil { + return nil, nil + } + user, err = h.users.GetByEmailContext(ctx, email) + if errors.Is(err, appauth.ErrUserNotFound) { + return nil, nil + } + if err != nil { + return nil, err + } + if subject, err = h.linkedSubject(c, user.ID); err != nil { + return nil, err + } + } + return []scimUserResource{h.resource(user, subject)}, nil +} + +// parseSCIMFilter accepts exactly `externalId eq "value"` and +// `userName eq "value"`. Attribute names and the operator are case-insensitive +// as RFC 7644 requires; the value is a JSON string, so escapes are decoded and +// anything after it is rejected. +func parseSCIMFilter(raw string) (attribute, value string, ok bool) { + fields := strings.SplitN(strings.TrimSpace(raw), " ", 3) + if len(fields) != 3 || !strings.EqualFold(fields[1], "eq") { + return "", "", false + } + attribute = strings.ToLower(fields[0]) + if attribute != "externalid" && attribute != "username" { + return "", "", false + } + literal := strings.TrimSpace(fields[2]) + if !utf8.ValidString(literal) || !strings.HasPrefix(literal, `"`) { + return "", "", false + } + if err := json.Unmarshal([]byte(literal), &value); err != nil { + return "", "", false + } + return attribute, value, true +} + +func scimQueryInt(c *echo.Context, name string, fallback int) (int, error) { + raw := c.QueryParam(name) + if raw == "" { + return fallback, nil + } + value, err := strconv.Atoi(raw) + if err != nil { + return 0, scimFail(http.StatusBadRequest, "invalidValue", name+" must be an integer.") + } + return value, nil +} + +func (h *SCIMHandler) patchUser(c *echo.Context) error { + var req scimPatchRequest + if err := decodeSCIMBody(c, &req); err != nil { + return err + } + if !hasSchema(req.Schemas, scimPatchSchema) { + return scimFail(http.StatusBadRequest, "invalidSyntax", "schemas must include the PatchOp schema.") + } + if len(req.Operations) == 0 { + return scimFail(http.StatusBadRequest, "invalidValue", "Operations must not be empty.") + } + id := c.Param("id") + subject, err := h.linkedSubject(c, id) + if err != nil { + return err + } + patch := scimPatch{subject: subject} + for _, operation := range req.Operations { + if err := patch.applyOperation(operation.Op, operation.Path, operation.Value); err != nil { + return err + } + } + if patch.userName != nil && patch.primaryEmail != nil && *patch.userName != *patch.primaryEmail { + return scimFail(http.StatusBadRequest, "invalidValue", "userName and the primary email must be the same address.") + } + if patch.userName != nil { + patch.change.Email = patch.userName + } else if patch.primaryEmail != nil { + patch.change.Email = patch.primaryEmail + } + user, _, err := h.users.UpdateProvisioned(id, patch.change, scimAuditSource(c)) + switch { + case errors.Is(err, appauth.ErrUserNotFound): + return scimFail(http.StatusNotFound, "", "User not found.") + case errors.Is(err, appauth.ErrUserConflict): + return scimFail(http.StatusConflict, "uniqueness", "The email address belongs to a different account.") + case errors.Is(err, appauth.ErrLastActiveAdmin): + return scimFail(http.StatusConflict, "", "This would remove the last active administrator.") + case err != nil: + return err + } + return writeSCIM(c, http.StatusOK, h.resource(user, subject)) +} + +// scimPatch collects the operations of one request, so they apply as a single +// update and the last-administrator check sees the final state. +type scimPatch struct { + subject string + change appauth.UserChange + userName *string + primaryEmail *string +} + +func (p *scimPatch) applyOperation(op, path string, value json.RawMessage) error { + switch strings.ToLower(op) { + case "replace", "add": + case "remove": + return scimFail(http.StatusBadRequest, "mutability", "Attributes cannot be removed; set a new value instead.") + default: + return scimFail(http.StatusBadRequest, "invalidSyntax", "op must be add, replace, or remove.") + } + if path != "" { + return p.applyAttribute(path, value) + } + var attributes map[string]json.RawMessage + if err := json.Unmarshal(value, &attributes); err != nil || attributes == nil { + return scimFail(http.StatusBadRequest, "invalidValue", "An operation without a path needs an object value.") + } + for name, attribute := range attributes { + if err := p.applyAttribute(name, attribute); err != nil { + return err + } + } + return nil +} + +func (p *scimPatch) applyAttribute(name string, value json.RawMessage) error { + switch strings.TrimPrefix(strings.ToLower(name), strings.ToLower(scimUserSchema)+":") { + case "active": + var active scimBool + if err := json.Unmarshal(value, &active); err != nil { + return scimFail(http.StatusBadRequest, "invalidValue", "active must be a boolean.") + } + status := appauth.UserStatusSuspended + if active { + status = appauth.UserStatusActive + } + p.change.Status = &status + case "roles": + var values []scimMultiValue + if err := json.Unmarshal(value, &values); err != nil { + return scimFail(http.StatusBadRequest, "invalidValue", "roles must be a list of values.") + } + role, err := parseSCIMRole(values) + if err != nil { + return err + } + p.change.Role = &role + case "username": + var userName string + if err := json.Unmarshal(value, &userName); err != nil { + return scimFail(http.StatusBadRequest, "invalidValue", "userName must be a string.") + } + email, err := parseSCIMEmail(userName, "userName") + if err != nil { + return err + } + p.userName = &email + case "emails": + var values []scimMultiValue + if err := json.Unmarshal(value, &values); err != nil { + return scimFail(http.StatusBadRequest, "invalidValue", "emails must be a list of values.") + } + email, err := parseSCIMEmails(values) + if err != nil { + return err + } + p.primaryEmail = &email + case "displayname": + var displayName string + if err := json.Unmarshal(value, &displayName); err != nil { + return scimFail(http.StatusBadRequest, "invalidValue", "displayName must be a string.") + } + p.change.DisplayName = &displayName + case "externalid": + var externalID string + if err := json.Unmarshal(value, &externalID); err != nil || externalID != p.subject { + return scimFail(http.StatusBadRequest, "mutability", "externalId cannot be changed.") + } + default: + return scimFail(http.StatusBadRequest, "invalidPath", "This attribute cannot be patched.") + } + return nil +} + +// linkedSubject returns the subject of the user's identity with the configured +// issuer, or an empty string when the user has none. +func (h *SCIMHandler) linkedSubject(c *echo.Context, userID string) (string, error) { + identity, err := h.identities.FindForUser(c.Request().Context(), userID) + if errors.Is(err, appauth.ErrUserNotFound) { + return "", nil + } + if err != nil { + return "", err + } + if identity.Issuer != h.issuer { + return "", nil + } + return identity.Subject, nil +} + +func (h *SCIMHandler) resource(user appauth.User, subject string) scimUserResource { + return scimUserResource{ + Schemas: []string{scimUserSchema}, + ID: user.ID, + ExternalID: subject, + UserName: user.Email, + DisplayName: user.DisplayName, + Active: user.Status == appauth.UserStatusActive, + Emails: []scimResourceValue{{Value: user.Email, Primary: true}}, + Roles: []scimResourceValue{{Value: string(user.Role), Primary: true}}, + Meta: scimMeta{ + ResourceType: "User", + Created: user.CreatedAt, + LastModified: user.UpdatedAt, + Location: h.publicURL + scimUsersPath + "/" + user.ID, + }, + } +} diff --git a/internal/api/scim_test.go b/internal/api/scim_test.go new file mode 100644 index 000000000..ceeae5106 --- /dev/null +++ b/internal/api/scim_test.go @@ -0,0 +1,669 @@ +package api + +import ( + "bytes" + "encoding/json" + "fmt" + "log/slog" + "net/http" + "net/http/httptest" + "net/url" + "path/filepath" + "strconv" + "strings" + "sync" + "testing" + "time" + + "github.com/labstack/echo/v5" + + "github.com/labstack/fanout/internal/auth" + "github.com/labstack/fanout/internal/config" + appstore "github.com/labstack/fanout/internal/store" +) + +const ( + testSCIMToken = "scim-test-token-0123456789abcdef0123" + testSCIMIssuer = "https://issuer.example" +) + +func scimTestConfig() config.Config { + return config.Config{AuthMode: "oidc", OIDCIssuerURL: testSCIMIssuer, PublicURL: "https://fanout.example.com", SCIMToken: testSCIMToken} +} + +type scimServer struct { + e *echo.Echo + users *auth.UserStore + identities *auth.IdentityStore + db *appstore.SQLite +} + +func newSCIMServer(t *testing.T) *scimServer { + t.Helper() + cfg := scimTestConfig() + e, users, _, db := newOAuthTestServerAndDB(t, cfg) + identities := auth.NewIdentityStore(db.DB) + RegisterSCIMRoutes(e, cfg, users, identities) + return &scimServer{e: e, users: users, identities: identities, db: db} +} + +func scimHeaders() map[string]string { + return map[string]string{"Authorization": "Bearer " + testSCIMToken, "Content-Type": scimContentType} +} + +func (s *scimServer) do(t *testing.T, method, target, body string) *httptest.ResponseRecorder { + t.Helper() + return serve(t, s.e, method, target, body, scimHeaders()) +} + +func scimUser(externalID, email, role string) string { + body, _ := json.Marshal(map[string]any{ + "schemas": []string{scimUserSchema}, "externalId": externalID, "userName": email, + "roles": []map[string]any{{"value": role, "primary": true}}, + }) + return string(body) +} + +func scimPatchBody(operations string) string { + return `{"schemas":["` + scimPatchSchema + `"],"Operations":[` + operations + `]}` +} + +func decodeSCIMResource(t *testing.T, rec *httptest.ResponseRecorder) scimUserResource { + t.Helper() + if got := rec.Header().Get("Content-Type"); got != scimContentType { + t.Fatalf("Content-Type = %q, want %q", got, scimContentType) + } + var resource scimUserResource + if err := json.Unmarshal(rec.Body.Bytes(), &resource); err != nil { + t.Fatalf("decode resource: %v in %s", err, rec.Body.String()) + } + return resource +} + +func assertSCIMError(t *testing.T, rec *httptest.ResponseRecorder, status int, scimType string) { + t.Helper() + if rec.Code != status { + t.Fatalf("status = %d %s, want %d", rec.Code, rec.Body.String(), status) + } + if got := rec.Header().Get("Content-Type"); got != scimContentType { + t.Fatalf("Content-Type = %q, want %q", got, scimContentType) + } + var body struct { + Schemas []string `json:"schemas"` + ScimType string `json:"scimType"` + Detail string `json:"detail"` + Status string `json:"status"` + } + if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil { + t.Fatalf("decode error: %v in %s", err, rec.Body.String()) + } + if len(body.Schemas) != 1 || body.Schemas[0] != scimErrorSchema || body.Status != strconv.Itoa(status) || body.Detail == "" || body.ScimType != scimType { + t.Fatalf("error body = %+v, want status %d scimType %q", body, status, scimType) + } +} + +func (s *scimServer) seed(t *testing.T, externalID, email, role string) scimUserResource { + t.Helper() + rec := s.do(t, http.MethodPost, scimUsersPath, scimUser(externalID, email, role)) + if rec.Code != http.StatusCreated { + t.Fatalf("seed %s = %d %s", email, rec.Code, rec.Body.String()) + } + return decodeSCIMResource(t, rec) +} + +func (s *scimServer) auditCount(t *testing.T, eventType, targetID string) int { + t.Helper() + var count int + if err := s.db.DB.QueryRow(`SELECT COUNT(*) FROM auth_audit_events WHERE event_type = ? AND target_id = ?`, eventType, targetID).Scan(&count); err != nil { + t.Fatalf("audit count: %v", err) + } + return count +} + +func TestSCIMCreateLinksIdentityAndRetrySucceeds(t *testing.T) { + s := newSCIMServer(t) + rec := s.do(t, http.MethodPost, scimUsersPath, scimUser("sub-opaque", "Owner@Example.com", "admin")) + if rec.Code != http.StatusCreated { + t.Fatalf("create = %d %s", rec.Code, rec.Body.String()) + } + created := decodeSCIMResource(t, rec) + if created.ExternalID != "sub-opaque" || created.UserName != "owner@example.com" || !created.Active || created.Roles[0].Value != "admin" { + t.Fatalf("created = %+v", created) + } + wantLocation := "https://fanout.example.com/scim/v2/Users/" + created.ID + if rec.Header().Get("Location") != wantLocation || created.Meta.Location != wantLocation || created.Meta.ResourceType != "User" { + t.Fatalf("location header %q meta %+v", rec.Header().Get("Location"), created.Meta) + } + identity, err := s.identities.Find(t.Context(), testSCIMIssuer, "sub-opaque") + if err != nil || identity.UserID != created.ID { + t.Fatalf("identity = %+v err=%v", identity, err) + } + + retry := s.do(t, http.MethodPost, scimUsersPath, scimUser("sub-opaque", "owner@example.com", "admin")) + if retry.Code != http.StatusOK || decodeSCIMResource(t, retry).ID != created.ID { + t.Fatalf("retry = %d %s", retry.Code, retry.Body.String()) + } + if got := s.auditCount(t, "user.provisioned", created.ID); got != 1 { + t.Fatalf("user.provisioned events = %d, want 1", got) + } + if got := s.auditCount(t, "identity.linked", identity.ID); got != 1 { + t.Fatalf("identity.linked events = %d, want 1", got) + } +} + +func TestSCIMCreateValidation(t *testing.T) { + s := newSCIMServer(t) + tests := map[string]struct { + body string + scimType string + }{ + "not json": {`{`, "invalidSyntax"}, + "trailing content": {scimUser("a", "a@example.com", "admin") + `{}`, "invalidSyntax"}, + "missing schema": {`{"externalId":"a","userName":"a@example.com","roles":[{"value":"admin"}]}`, "invalidSyntax"}, + "missing external": {`{"schemas":["` + scimUserSchema + `"],"userName":"a@example.com","roles":[{"value":"admin"}]}`, "invalidValue"}, + "long external": {scimUser(strings.Repeat("x", 256), "a@example.com", "admin"), "invalidValue"}, + "invalid email": {scimUser("a", "not-an-email", "admin"), "invalidValue"}, + "missing role": {`{"schemas":["` + scimUserSchema + `"],"externalId":"a","userName":"a@example.com"}`, "invalidValue"}, + "unknown role": {scimUser("a", "a@example.com", "owner"), "invalidValue"}, + "disagreeing email": {`{"schemas":["` + scimUserSchema + `"],"externalId":"a","userName":"a@example.com","emails":[{"value":"b@example.com"}],"roles":[{"value":"admin"}]}`, "invalidValue"}, + } + for name, tc := range tests { + t.Run(name, func(t *testing.T) { + assertSCIMError(t, s.do(t, http.MethodPost, scimUsersPath, tc.body), http.StatusBadRequest, tc.scimType) + }) + } + headers := scimHeaders() + headers["Content-Type"] = "text/plain" + assertSCIMError(t, serve(t, s.e, http.MethodPost, scimUsersPath, scimUser("a", "a@example.com", "admin"), headers), http.StatusUnsupportedMediaType, "") + assertSCIMError(t, s.do(t, http.MethodPost, scimUsersPath, `{"schemas":["`+strings.Repeat("x", userBodyLimit)+`"]}`), http.StatusRequestEntityTooLarge, "") + + headers["Content-Type"] = "application/json; charset=utf-8" + rec := serve(t, s.e, http.MethodPost, scimUsersPath, scimUser("json", "json@example.com", "admin"), headers) + if rec.Code != http.StatusCreated { + t.Fatalf("application/json create = %d %s", rec.Code, rec.Body.String()) + } +} + +func TestSCIMZeroUsersOnlyAdministrator(t *testing.T) { + s := newSCIMServer(t) + for _, role := range []string{"viewer", "operator"} { + assertSCIMError(t, s.do(t, http.MethodPost, scimUsersPath, scimUser("early-"+role, role+"@example.com", role)), http.StatusConflict, "") + } + s.seed(t, "owner", "owner@example.com", "admin") + viewer := s.seed(t, "member", "member@example.com", "viewer") + if viewer.Roles[0].Value != "viewer" { + t.Fatalf("viewer role = %+v", viewer.Roles) + } +} + +func TestSCIMConcurrentAdministratorsOnEmptyDatabase(t *testing.T) { + db, err := appstore.NewSQLite(filepath.Join(t.TempDir(), "control.db")) + if err != nil { + t.Fatalf("NewSQLite: %v", err) + } + t.Cleanup(func() { _ = db.Close() }) + cfg := scimTestConfig() + users := auth.NewUserStore(db.DB) + sessions := auth.NewBrowserSessions(db.DB, 12*time.Hour, 7*24*time.Hour, false) + e := echo.New() + e.HTTPErrorHandler = HTTPErrorHandler + RegisterAuthMiddleware(e, users, sessions, auth.NewAuditStore(db.DB), cfg) + RegisterSCIMRoutes(e, cfg, users, auth.NewIdentityStore(db.DB)) + + const requests = 10 + start := make(chan struct{}) + codes := make(chan string, requests) + var wg sync.WaitGroup + for i := range requests { + wg.Add(1) + go func() { + defer wg.Done() + <-start + req := httptest.NewRequest(http.MethodPost, scimUsersPath, strings.NewReader(scimUser(fmt.Sprintf("sub-%d", i), fmt.Sprintf("admin-%d@example.com", i), "admin"))) + for key, value := range scimHeaders() { + req.Header.Set(key, value) + } + rec := httptest.NewRecorder() + e.ServeHTTP(rec, req) + codes <- strconv.Itoa(rec.Code) + " " + rec.Body.String() + }() + } + close(start) + wg.Wait() + close(codes) + for result := range codes { + if !strings.HasPrefix(result, "201 ") { + t.Fatalf("concurrent administrator = %s, want 201", result) + } + } + count, err := users.CountActiveAdmins() + if err != nil || count != requests { + t.Fatalf("active administrators = %d err=%v, want %d", count, err, requests) + } +} + +func TestSCIMEmailHeldByDifferentAccountConflicts(t *testing.T) { + s := newSCIMServer(t) + local, err := s.users.CreateWithAudit("taken@example.com", "", "admin", auth.AuditEvent{EventType: "user.created", Outcome: "success"}) + if err != nil { + t.Fatalf("create: %v", err) + } + assertSCIMError(t, s.do(t, http.MethodPost, scimUsersPath, scimUser("sub-1", "taken@example.com", "viewer")), http.StatusConflict, "uniqueness") + if count, err := s.identities.CountForUser(t.Context(), local.ID); err != nil || count != 0 { + t.Fatalf("local account linked by email: %d %v", count, err) + } + + other := s.seed(t, "sub-2", "other@example.com", "viewer") + body := scimPatchBody(`{"op":"replace","path":"userName","value":"taken@example.com"}`) + assertSCIMError(t, s.do(t, http.MethodPatch, scimUsersPath+"/"+other.ID, body), http.StatusConflict, "uniqueness") +} + +func TestSCIMFilterFindsAccounts(t *testing.T) { + s := newSCIMServer(t) + escaped := "tenant\"a\\b/é" + owner := s.seed(t, escaped, "owner@example.com", "admin") + local, err := s.users.CreateWithAudit("local@example.com", "", "viewer", auth.AuditEvent{EventType: "user.created", Outcome: "success"}) + if err != nil { + t.Fatalf("create: %v", err) + } + list := func(filter string) (scimListResult, int) { + rec := s.do(t, http.MethodGet, scimUsersPath+"?filter="+url.QueryEscape(filter), "") + if rec.Header().Get("Content-Type") != scimContentType { + t.Fatalf("Content-Type = %q", rec.Header().Get("Content-Type")) + } + var out scimListResult + _ = json.Unmarshal(rec.Body.Bytes(), &out) + return out, rec.Code + } + tests := []struct { + filter string + wantID string + }{ + {`externalId eq "tenant\"a\\b/é"`, owner.ID}, + {`externalId eq "tenant\"a\\b\/é"`, owner.ID}, + {`EXTERNALID EQ "tenant\"a\\b/é"`, owner.ID}, + {`userName eq "OWNER@example.com"`, owner.ID}, + {`userName eq "local@example.com"`, local.ID}, + {`externalId eq "missing"`, ""}, + {`externalId eq "TENANT\"A\\B/é"`, ""}, + {`userName eq "not-an-email"`, ""}, + } + for _, tc := range tests { + out, code := list(tc.filter) + if code != http.StatusOK { + t.Fatalf("filter %s = %d", tc.filter, code) + } + if tc.wantID == "" { + if out.TotalResults != 0 || len(out.Resources) != 0 { + t.Fatalf("filter %s = %+v, want empty", tc.filter, out) + } + continue + } + if out.TotalResults != 1 || len(out.Resources) != 1 || out.Resources[0].ID != tc.wantID || out.Schemas[0] != scimListSchema { + t.Fatalf("filter %s = %+v, want %s", tc.filter, out, tc.wantID) + } + } + if out, _ := list(`userName eq "local@example.com"`); out.Resources[0].ExternalID != "" { + t.Fatalf("local account reports externalId %q", out.Resources[0].ExternalID) + } + + rec := s.do(t, http.MethodGet, scimUsersPath+"?filter="+url.QueryEscape(`externalId eq "tenant\"a\\b/é"`)+"&count=0", "") + var counted scimListResult + _ = json.Unmarshal(rec.Body.Bytes(), &counted) + if counted.TotalResults != 1 || len(counted.Resources) != 0 { + t.Fatalf("count=0 = %+v", counted) + } + assertSCIMError(t, s.do(t, http.MethodGet, scimUsersPath+"?filter="+url.QueryEscape(`externalId eq "x"`)+"&count=abc", ""), http.StatusBadRequest, "invalidValue") +} + +type scimListResult struct { + Schemas []string `json:"schemas"` + TotalResults int `json:"totalResults"` + Resources []scimUserResource `json:"Resources"` +} + +func TestSCIMRejectsUnsupportedFilters(t *testing.T) { + s := newSCIMServer(t) + for _, filter := range []string{ + ``, + `externalId`, + `externalId eq`, + `externalId ne "x"`, + `externalId co "x"`, + `externalId pr`, + `emails eq "x"`, + `id eq "x"`, + `active eq true`, + `externalId eq x`, + `externalId eq "x`, + `externalId eq "x" and userName eq "y"`, + `externalId eq "x" or externalId eq "y"`, + `not (externalId eq "x")`, + `externalId eq "x"junk`, + `externalId eq "\q"`, + "externalId eq \"\xff\"", + } { + target := scimUsersPath + if filter != "" { + target += "?filter=" + url.QueryEscape(filter) + } + assertSCIMError(t, s.do(t, http.MethodGet, target, ""), http.StatusBadRequest, "invalidFilter") + } +} + +func TestSCIMParseFilterDecodesJSONString(t *testing.T) { + attribute, value, ok := parseSCIMFilter(`externalId eq "a\"b\\cA d"`) + if !ok || attribute != "externalid" || value != `a"b\cA d` { + t.Fatalf("parse = %q %q %v", attribute, value, ok) + } +} + +func TestSCIMPatchUpdatesFieldsAndIsRepeatable(t *testing.T) { + s := newSCIMServer(t) + owner := s.seed(t, "owner", "owner@example.com", "admin") + member := s.seed(t, "member", "member@example.com", "viewer") + path := scimUsersPath + "/" + member.ID + + tests := []struct { + name string + body string + check func(scimUserResource) bool + event string + }{ + {"deactivate", scimPatchBody(`{"op":"replace","path":"active","value":false}`), func(r scimUserResource) bool { return !r.Active }, "user.suspended"}, + {"reactivate as string", scimPatchBody(`{"op":"Replace","path":"active","value":"True"}`), func(r scimUserResource) bool { return r.Active }, "user.reactivated"}, + {"role", scimPatchBody(`{"op":"replace","path":"roles","value":[{"value":"operator","primary":true}]}`), func(r scimUserResource) bool { return r.Roles[0].Value == "operator" }, "role.changed"}, + {"email by userName", scimPatchBody(`{"op":"replace","path":"userName","value":"New@Example.com"}`), func(r scimUserResource) bool { + return r.UserName == "new@example.com" && r.Emails[0].Value == "new@example.com" + }, "user.updated"}, + {"email by emails", scimPatchBody(`{"op":"replace","path":"emails","value":[{"value":"newer@example.com","primary":true}]}`), func(r scimUserResource) bool { return r.UserName == "newer@example.com" }, "user.updated"}, + {"pathless", scimPatchBody(`{"op":"replace","value":{"active":false,"roles":[{"value":"viewer"}]}}`), func(r scimUserResource) bool { return !r.Active && r.Roles[0].Value == "viewer" }, "user.suspended"}, + {"urn path", scimPatchBody(`{"op":"replace","path":"urn:ietf:params:scim:schemas:core:2.0:User:active","value":true}`), func(r scimUserResource) bool { return r.Active }, "user.reactivated"}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + before := s.auditCount(t, tc.event, member.ID) + rec := s.do(t, http.MethodPatch, path, tc.body) + if rec.Code != http.StatusOK || !tc.check(decodeSCIMResource(t, rec)) { + t.Fatalf("patch = %d %s", rec.Code, rec.Body.String()) + } + if got := s.auditCount(t, tc.event, member.ID); got != before+1 { + t.Fatalf("%s events = %d, want %d", tc.event, got, before+1) + } + repeat := s.do(t, http.MethodPatch, path, tc.body) + if repeat.Code != http.StatusOK || !tc.check(decodeSCIMResource(t, repeat)) { + t.Fatalf("repeat = %d %s", repeat.Code, repeat.Body.String()) + } + if got := s.auditCount(t, tc.event, member.ID); got != before+1 { + t.Fatalf("repeat wrote an audit event: %d", got) + } + }) + } + + identity, err := s.identities.Find(t.Context(), testSCIMIssuer, "member") + if err != nil || identity.UserID != member.ID { + t.Fatalf("identity lost: %+v err=%v", identity, err) + } + rec := s.do(t, http.MethodGet, path, "") + if got := decodeSCIMResource(t, rec); got.ExternalID != "member" { + t.Fatalf("GET = %+v", got) + } + if got := s.auditCount(t, "user.suspended", owner.ID); got != 0 { + t.Fatalf("unrelated account audited: %d", got) + } +} + +func TestSCIMPatchValidation(t *testing.T) { + s := newSCIMServer(t) + s.seed(t, "owner", "owner@example.com", "admin") + member := s.seed(t, "member", "member@example.com", "viewer") + path := scimUsersPath + "/" + member.ID + tests := map[string]struct { + body string + status int + scimType string + }{ + "missing schema": {`{"Operations":[{"op":"replace","path":"active","value":false}]}`, 400, "invalidSyntax"}, + "no operations": {scimPatchBody(``), 400, "invalidValue"}, + "unknown op": {scimPatchBody(`{"op":"move","path":"active","value":false}`), 400, "invalidSyntax"}, + "remove": {scimPatchBody(`{"op":"remove","path":"displayName"}`), 400, "mutability"}, + "unknown path": {scimPatchBody(`{"op":"replace","path":"title","value":"x"}`), 400, "invalidPath"}, + "filtered path": {scimPatchBody(`{"op":"replace","path":"emails[type eq \"work\"].value","value":"x@example.com"}`), 400, "invalidPath"}, + "bad active": {scimPatchBody(`{"op":"replace","path":"active","value":"maybe"}`), 400, "invalidValue"}, + "bad role": {scimPatchBody(`{"op":"replace","path":"roles","value":[{"value":"owner"}]}`), 400, "invalidValue"}, + "many roles": {scimPatchBody(`{"op":"replace","path":"roles","value":[{"value":"admin"},{"value":"viewer"}]}`), 400, "invalidValue"}, + "bad email": {scimPatchBody(`{"op":"replace","path":"userName","value":"nope"}`), 400, "invalidValue"}, + "disagreeing emails": {scimPatchBody(`{"op":"replace","path":"userName","value":"a@example.com"},{"op":"replace","path":"emails","value":[{"value":"b@example.com"}]}`), 400, "invalidValue"}, + "external change": {scimPatchBody(`{"op":"replace","path":"externalId","value":"other"}`), 400, "mutability"}, + "pathless non-object": {scimPatchBody(`{"op":"replace","value":false}`), 400, "invalidValue"}, + } + for name, tc := range tests { + t.Run(name, func(t *testing.T) { + assertSCIMError(t, s.do(t, http.MethodPatch, path, tc.body), tc.status, tc.scimType) + }) + } + ok := s.do(t, http.MethodPatch, path, scimPatchBody(`{"op":"replace","path":"externalId","value":"member"}`)) + if ok.Code != http.StatusOK { + t.Fatalf("restating externalId = %d %s", ok.Code, ok.Body.String()) + } + assertSCIMError(t, s.do(t, http.MethodPatch, scimUsersPath+"/missing", scimPatchBody(`{"op":"replace","path":"active","value":false}`)), http.StatusNotFound, "") + assertSCIMError(t, s.do(t, http.MethodGet, scimUsersPath+"/missing", ""), http.StatusNotFound, "") +} + +func TestSCIMLastActiveAdministratorIsProtected(t *testing.T) { + s := newSCIMServer(t) + owner := s.seed(t, "owner", "owner@example.com", "admin") + path := scimUsersPath + "/" + owner.ID + assertSCIMError(t, s.do(t, http.MethodPatch, path, scimPatchBody(`{"op":"replace","path":"active","value":false}`)), http.StatusConflict, "") + assertSCIMError(t, s.do(t, http.MethodPatch, path, scimPatchBody(`{"op":"replace","path":"roles","value":[{"value":"viewer"}]}`)), http.StatusConflict, "") + // The final state counts: demotion plus reactivation in one request is + // still a demotion of the last administrator. + assertSCIMError(t, s.do(t, http.MethodPatch, path, scimPatchBody(`{"op":"replace","path":"roles","value":[{"value":"viewer"}]},{"op":"replace","path":"active","value":true}`)), http.StatusConflict, "") + + second := s.seed(t, "second", "second@example.com", "admin") + if rec := s.do(t, http.MethodPatch, path, scimPatchBody(`{"op":"replace","path":"active","value":false}`)); rec.Code != http.StatusOK { + t.Fatalf("deactivate with a second administrator = %d %s", rec.Code, rec.Body.String()) + } + assertSCIMError(t, s.do(t, http.MethodPatch, scimUsersPath+"/"+second.ID, scimPatchBody(`{"op":"replace","path":"active","value":false}`)), http.StatusConflict, "") +} + +func TestSCIMDeactivationEndsBrowserAndMCPAccess(t *testing.T) { + s := newSCIMServer(t) + s.seed(t, "owner", "owner@example.com", "admin") + member := s.seed(t, "member", "member@example.com", "admin") + user, err := s.users.GetByID(member.ID) + if err != nil { + t.Fatalf("GetByID: %v", err) + } + cookie := oauthCookieForUser(t, s.e, user) + if rec := serve(t, s.e, http.MethodGet, "/api/auth/me", "", nil, cookie); rec.Code != http.StatusNoContent { + t.Fatalf("session before deactivation = %d", rec.Code) + } + + client := registerOAuthClient(t, s.e) + verifier, challenge := pkcePair() + code := approveAndGetCode(t, s.e, authorizeParams(client.ClientID, mcpReadScope, challenge), cookie) + tokens := decodeTokens(t, exchangeCode(t, s.e, client.ClientID, code, testRedirectURI, verifier)) + access, refresh := tokens["access_token"].(string), tokens["refresh_token"].(string) + bearer := map[string]string{"Authorization": "Bearer " + access} + if rec := serve(t, s.e, http.MethodPost, "/mcp", testReadMCPCall, bearer); rec.Code != http.StatusNoContent { + t.Fatalf("MCP before deactivation = %d %s", rec.Code, rec.Body.String()) + } + refreshForm := url.Values{"grant_type": {"refresh_token"}, "client_id": {client.ClientID}, "refresh_token": {refresh}}.Encode() + + // A second grant is checked only after reactivation. Presenting a refresh + // token while suspended revokes its family by itself, which would hide a + // missing revocation at the moment of deactivation. + secondVerifier, secondChallenge := pkcePair() + secondCode := approveAndGetCode(t, s.e, authorizeParams(client.ClientID, mcpReadScope, secondChallenge), cookie) + second := decodeTokens(t, exchangeCode(t, s.e, client.ClientID, secondCode, testRedirectURI, secondVerifier)) + secondBearer := map[string]string{"Authorization": "Bearer " + second["access_token"].(string)} + secondRefreshForm := url.Values{"grant_type": {"refresh_token"}, "client_id": {client.ClientID}, "refresh_token": {second["refresh_token"].(string)}}.Encode() + + assertTokensRejected := func(stage string, accessHeaders map[string]string, form string) { + t.Helper() + if rec := serve(t, s.e, http.MethodPost, "/mcp", testReadMCPCall, accessHeaders); rec.Code != http.StatusUnauthorized { + t.Fatalf("%s: MCP access token = %d %s, want 401", stage, rec.Code, rec.Body.String()) + } + rec := serve(t, s.e, http.MethodPost, "/oauth/token", form, formHeaders) + if rec.Code != http.StatusBadRequest || !strings.Contains(rec.Body.String(), "invalid_grant") { + t.Fatalf("%s: refresh = %d %s, want invalid_grant", stage, rec.Code, rec.Body.String()) + } + } + assertSessionEnded := func(stage string) { + t.Helper() + if rec := serve(t, s.e, http.MethodGet, "/api/auth/me", "", nil, cookie); rec.Code != http.StatusUnauthorized { + t.Fatalf("%s: session = %d, want 401", stage, rec.Code) + } + } + + path := scimUsersPath + "/" + member.ID + if rec := s.do(t, http.MethodPatch, path, scimPatchBody(`{"op":"replace","path":"active","value":false}`)); rec.Code != http.StatusOK { + t.Fatalf("deactivate = %d %s", rec.Code, rec.Body.String()) + } + assertSessionEnded("after deactivation") + assertTokensRejected("after deactivation", bearer, refreshForm) + + if rec := s.do(t, http.MethodPatch, path, scimPatchBody(`{"op":"replace","path":"active","value":true}`)); rec.Code != http.StatusOK { + t.Fatalf("reactivate = %d %s", rec.Code, rec.Body.String()) + } + assertSessionEnded("after reactivation") + assertTokensRejected("after reactivation", bearer, refreshForm) + assertTokensRejected("after reactivation, unused grant", secondBearer, secondRefreshForm) + reactivated, err := s.users.GetByID(member.ID) + if err != nil || reactivated.Status != auth.UserStatusActive { + t.Fatalf("reactivated = %+v err=%v", reactivated, err) + } + if identity, err := s.identities.Find(t.Context(), testSCIMIssuer, "member"); err != nil || identity.UserID != member.ID { + t.Fatalf("identity after reactivation: %+v err=%v", identity, err) + } +} + +func TestSCIMFirstLoginUsesLinkedIdentityWithoutEmailMatch(t *testing.T) { + s := newSCIMServer(t) + owner := s.seed(t, "portal-subject", "owner@example.com", "admin") + handler := &OIDCHandler{ + cfg: config.Config{OIDCEmailVerification: "required"}, + users: s.users, + identities: s.identities, + audit: auth.NewAuditStore(s.db.DB), + } + verified := true + claims := oidcClaims{Subject: "portal-subject", Email: "different@example.com", EmailVerified: &verified} + user, identity, err := handler.resolveUser(t.Context(), testSCIMIssuer, claims, requestSource{}) + if err != nil || user.ID != owner.ID || identity.UserID != owner.ID { + t.Fatalf("resolveUser = %+v %+v err=%v", user, identity, err) + } +} + +func TestSCIMRequiresToken(t *testing.T) { + s := newSCIMServer(t) + tests := map[string]map[string]string{ + "missing": {}, + "wrong": {"Authorization": "Bearer wrong-token"}, + "wrong scheme": {"Authorization": "Basic " + testSCIMToken}, + "prefix": {"Authorization": "Bearer " + testSCIMToken[:10]}, + } + for name, headers := range tests { + t.Run(name, func(t *testing.T) { + rec := serve(t, s.e, http.MethodGet, scimUsersPath+"?filter="+url.QueryEscape(`externalId eq "x"`), "", headers) + assertSCIMError(t, rec, http.StatusUnauthorized, "") + if rec.Header().Get("WWW-Authenticate") != "Bearer" { + t.Fatalf("WWW-Authenticate = %q", rec.Header().Get("WWW-Authenticate")) + } + }) + } + rec := serve(t, s.e, http.MethodGet, scimUsersPath+"?filter="+url.QueryEscape(`externalId eq "x"`), "", map[string]string{"Authorization": "bearer " + testSCIMToken}) + if rec.Code != http.StatusOK { + t.Fatalf("lowercase scheme = %d %s", rec.Code, rec.Body.String()) + } + for name, tc := range map[string]struct { + method, path string + status int + }{ + "method": {http.MethodDelete, scimUsersPath + "/x", http.StatusMethodNotAllowed}, + "unknown route": {http.MethodGet, scimRoot + "/Groups", http.StatusNotFound}, + "trailing path": {http.MethodGet, scimUsersPath + "/x/y", http.StatusNotFound}, + } { + t.Run(name, func(t *testing.T) { + assertSCIMError(t, s.do(t, tc.method, tc.path, ""), tc.status, "") + }) + } +} + +func TestSCIMTokenComparison(t *testing.T) { + if !scimTokenMatches("abc", "abc") { + t.Fatal("equal tokens must match") + } + for _, presented := range []string{"", "ab", "abd", "abcd"} { + if scimTokenMatches(presented, "abc") { + t.Fatalf("%q must not match", presented) + } + } +} + +func TestSCIMDoesNotLogToken(t *testing.T) { + var logs bytes.Buffer + previous := slog.Default() + slog.SetDefault(slog.New(slog.NewTextHandler(&logs, &slog.HandlerOptions{Level: slog.LevelDebug}))) + t.Cleanup(func() { slog.SetDefault(previous) }) + + s := newSCIMServer(t) + s.seed(t, "owner", "owner@example.com", "admin") + serve(t, s.e, http.MethodGet, scimUsersPath, "", map[string]string{"Authorization": "Bearer " + testSCIMToken + "x"}) + if _, err := s.db.DB.Exec(`ALTER TABLE users RENAME TO users_offline`); err != nil { + t.Fatalf("hide users: %v", err) + } + assertSCIMError(t, s.do(t, http.MethodPost, scimUsersPath, scimUser("a", "a@example.com", "admin")), http.StatusInternalServerError, "") + if strings.Contains(logs.String(), testSCIMToken) { + t.Fatalf("token reached the log: %s", logs.String()) + } +} + +func TestSCIMRoutesAbsentWithoutToken(t *testing.T) { + cfg := scimTestConfig() + cfg.SCIMToken = "" + e, users, _, db := newOAuthTestServerAndDB(t, cfg) + RegisterSCIMRoutes(e, cfg, users, auth.NewIdentityStore(db.DB)) + e.GET("/*", func(c *echo.Context) error { return c.String(http.StatusOK, "SPA") }) + + bearer := map[string]string{"Authorization": "Bearer " + testSCIMToken, "Content-Type": scimContentType} + for _, path := range []string{scimUsersPath, scimUsersPath + "/id", scimRoot + "/Groups"} { + rec := serve(t, e, http.MethodGet, path, "", bearer) + if rec.Code != http.StatusOK || rec.Body.String() != "SPA" { + t.Fatalf("GET %s = %d %s, want the SPA", path, rec.Code, rec.Body.String()) + } + rec = serve(t, e, http.MethodPost, path, "{}", bearer) + if rec.Code != http.StatusMethodNotAllowed || !strings.Contains(rec.Body.String(), `"code"`) || rec.Header().Get("Content-Type") == scimContentType { + t.Fatalf("POST %s = %d %s %q, want the product 405", path, rec.Code, rec.Body.String(), rec.Header().Get("Content-Type")) + } + } + var created int + if err := db.DB.QueryRow(`SELECT COUNT(*) FROM users`).Scan(&created); err != nil || created != 0 { + t.Fatalf("users = %d err=%v", created, err) + } +} + +func TestSCIMTokenDisablesBrowserSetup(t *testing.T) { + s := newTestAuthServerWith(t, scimTestConfig(), auth.SMTPConfig{}) + body := strings.NewReader(`{"email":"first@example.com","setup_token":"` + s.setupToken + `"}`) + req := sessionRequest(http.MethodPost, "/api/auth/setup", body, nil) + req.Header.Set("Content-Type", "application/json") + rec := httptest.NewRecorder() + s.e.ServeHTTP(rec, req) + if rec.Code != http.StatusGone { + t.Fatalf("setup = %d %s, want 410", rec.Code, rec.Body.String()) + } + count, err := s.users.CountUsers() + if err != nil || count != 0 { + t.Fatalf("users = %d err=%v", count, err) + } + statusRec := httptest.NewRecorder() + s.e.ServeHTTP(statusRec, httptest.NewRequest(http.MethodGet, "/api/auth/status", nil)) + var status struct { + SetupRequired bool `json:"setup_required"` + } + if err := json.Unmarshal(statusRec.Body.Bytes(), &status); err != nil || status.SetupRequired { + t.Fatalf("status = %s err=%v, want setup_required false", statusRec.Body.String(), err) + } +} diff --git a/internal/auth/audit.go b/internal/auth/audit.go index 7fdc5b05c..0cefb4d64 100644 --- a/internal/auth/audit.go +++ b/internal/auth/audit.go @@ -57,7 +57,7 @@ func recordAudit(ctx context.Context, executor auditExecutor, event AuditEvent) "login_link.issued": {}, "login_link.redeemed": {}, "login_link.break_glass_issued": {}, "login_link.break_glass_redeemed": {}, "oauth_connection.revoked": {}, "oidc.denied": {}, "role.changed": {}, "session.revoked": {}, "setup.completed": {}, - "user.created": {}, "user.suspended": {}, "user.deleted": {}, "user.provisioned": {}, "user.updated": {}, + "user.created": {}, "user.suspended": {}, "user.deleted": {}, "user.provisioned": {}, "user.reactivated": {}, "user.updated": {}, }) { appmetrics.AuthAuditWriteFailures.Inc() return fmt.Errorf("auth: invalid audit event type %q", event.EventType) diff --git a/internal/auth/identity_store.go b/internal/auth/identity_store.go index 8dcb3db4d..8c22eff3f 100644 --- a/internal/auth/identity_store.go +++ b/internal/auth/identity_store.go @@ -28,11 +28,25 @@ type IdentityStore struct{ db *sql.DB } func NewIdentityStore(db *sql.DB) *IdentityStore { return &IdentityStore{db: db} } func (s *IdentityStore) Find(ctx context.Context, issuer, subject string) (UserIdentity, error) { + return findIdentity(ctx, s.db, `issuer = ? AND subject = ?`, issuer, subject) +} + +// FindForUser returns the identity linked to a user, or ErrUserNotFound when +// the user has none. +func (s *IdentityStore) FindForUser(ctx context.Context, userID string) (UserIdentity, error) { + return findIdentity(ctx, s.db, `user_id = ?`, userID) +} + +type identityQuerier interface { + QueryRowContext(context.Context, string, ...any) *sql.Row +} + +func findIdentity(ctx context.Context, querier identityQuerier, where string, args ...any) (UserIdentity, error) { var identity UserIdentity var lastLogin sql.NullString - err := s.db.QueryRowContext(ctx, ` + err := querier.QueryRowContext(ctx, ` SELECT id, user_id, issuer, subject, email_at_link, created_at, last_login_at - FROM user_identities WHERE issuer = ? AND subject = ?`, issuer, subject, + FROM user_identities WHERE `+where, args..., ).Scan(&identity.ID, &identity.UserID, &identity.Issuer, &identity.Subject, &identity.EmailAtLink, &identity.CreatedAt, &lastLogin) if errors.Is(err, sql.ErrNoRows) { return UserIdentity{}, ErrUserNotFound diff --git a/internal/auth/provisioning.go b/internal/auth/provisioning.go new file mode 100644 index 000000000..c1c270344 --- /dev/null +++ b/internal/auth/provisioning.go @@ -0,0 +1,208 @@ +package auth + +import ( + "context" + "errors" + "fmt" + "time" + + "github.com/labstack/fanout/internal/db/generated" + appid "github.com/labstack/fanout/internal/id" + appstore "github.com/labstack/fanout/internal/store" +) + +// ErrFirstUserMustBeAdmin refuses an account on an empty database that would +// leave the installation without an active administrator. +var ErrFirstUserMustBeAdmin = errors.New("the first account must be an active administrator") + +// ProvisionRequest describes an account an identity provider wants to exist. +type ProvisionRequest struct { + Issuer string + Subject string + Email string + DisplayName string + Role Role + Status UserStatus +} + +// ProvisionFederated creates an account and its identity link in one +// transaction, so a crash cannot leave an unlinked account for a later login +// to claim by email. +// +// A request whose identity already exists changes nothing and returns the +// current account with created false. A delayed retry therefore cannot undo a +// later role change or suspension; the provisioner applies changes with an +// update. +// +// source supplies attribution for the audit events; its type and target are +// set here. +func (s *UserStore) ProvisionFederated(ctx context.Context, req ProvisionRequest, source AuditEvent) (User, UserIdentity, bool, error) { + if !ValidRole(string(req.Role)) { + return User{}, UserIdentity{}, false, fmt.Errorf("auth: invalid role %q", req.Role) + } + if !ValidUserStatus(string(req.Status)) { + return User{}, UserIdentity{}, false, fmt.Errorf("auth: invalid status %q", req.Status) + } + ctx, cancel := DetachedWriteContext(ctx) + defer cancel() + conn, err := s.db.Conn(ctx) + if err != nil { + return User{}, UserIdentity{}, false, fmt.Errorf("auth: open user conn: %w", err) + } + defer conn.Close() + if _, err := conn.ExecContext(ctx, "BEGIN IMMEDIATE"); err != nil { + return User{}, UserIdentity{}, false, fmt.Errorf("auth: begin provisioning: %w", err) + } + committed := false + defer func() { + if !committed { + rollbackConn(conn, "user provisioning") + } + }() + + q := generated.New(conn) + identity, err := findIdentity(ctx, conn, `issuer = ? AND subject = ?`, req.Issuer, req.Subject) + if err == nil { + row, err := q.GetUserByID(ctx, identity.UserID) + if err != nil { + return User{}, UserIdentity{}, false, fmt.Errorf("auth: read provisioned user: %w", err) + } + return toUser(row), identity, false, nil + } + if !errors.Is(err, ErrUserNotFound) { + return User{}, UserIdentity{}, false, err + } + + // Holding the write lock makes this the same check setup performs. A + // concurrent administrator that loses it sees a non-empty database and is + // created normally below. + empty, err := noUsersExist(ctx, q) + if err != nil { + return User{}, UserIdentity{}, false, err + } + if empty && (req.Role != RoleAdmin || req.Status != UserStatusActive) { + return User{}, UserIdentity{}, false, ErrFirstUserMustBeAdmin + } + + params, err := newCreateUserParams(req.Email, req.DisplayName, req.Role) + if err != nil { + return User{}, UserIdentity{}, false, err + } + row, err := q.CreateUser(ctx, params) + if err != nil { + if appstore.IsUniqueConstraint(err) { + return User{}, UserIdentity{}, false, fmt.Errorf("%w: %v", ErrUserConflict, err) + } + return User{}, UserIdentity{}, false, fmt.Errorf("auth: create provisioned user: %w", err) + } + if req.Status != UserStatusActive { + row, err = q.UpdateUser(ctx, generated.UpdateUserParams{ + Email: row.Email, DisplayName: row.DisplayName, Role: row.Role, Status: string(req.Status), + UpdatedAt: row.UpdatedAt, ID: row.ID, + }) + if err != nil { + return User{}, UserIdentity{}, false, fmt.Errorf("auth: set provisioned status: %w", err) + } + } + + identityID, err := appid.New() + if err != nil { + return User{}, UserIdentity{}, false, fmt.Errorf("auth: identity id: %w", err) + } + now := userTimestamp(time.Now()) + if _, err := conn.ExecContext(ctx, ` + INSERT INTO user_identities (id, user_id, issuer, subject, email_at_link, created_at) + VALUES (?, ?, ?, ?, ?, ?)`, identityID, row.ID, req.Issuer, req.Subject, req.Email, now); err != nil { + if appstore.IsUniqueConstraint(err) { + return User{}, UserIdentity{}, false, fmt.Errorf("%w: %v", ErrIdentityConflict, err) + } + return User{}, UserIdentity{}, false, fmt.Errorf("auth: link provisioned identity: %w", err) + } + + created := source + created.EventType, created.Outcome, created.TargetType, created.TargetID = "user.provisioned", "success", "user", row.ID + created.Metadata = withMetadata(source.Metadata, map[string]any{"role": row.Role, "status": row.Status, "first_user": empty}) + if err := recordAudit(ctx, conn, created); err != nil { + return User{}, UserIdentity{}, false, err + } + linked := source + linked.EventType, linked.Outcome, linked.TargetType, linked.TargetID = "identity.linked", "success", "identity", identityID + linked.Metadata = withMetadata(source.Metadata, map[string]any{"issuer": req.Issuer, "user_id": row.ID}) + if err := recordAudit(ctx, conn, linked); err != nil { + return User{}, UserIdentity{}, false, err + } + if _, err := conn.ExecContext(ctx, "COMMIT"); err != nil { + return User{}, UserIdentity{}, false, fmt.Errorf("auth: commit provisioning: %w", err) + } + committed = true + return toUser(row), UserIdentity{ID: identityID, UserID: row.ID, Issuer: req.Issuer, Subject: req.Subject, EmailAtLink: req.Email, CreatedAt: now}, true, nil +} + +// UserChange lists the fields a directory update may set; nil leaves one alone. +type UserChange struct { + Email *string + DisplayName *string + Role *Role + Status *UserStatus +} + +// UpdateProvisioned applies a directory update in one write transaction, +// including the last-active-administrator check. A change to the current state +// is reported with changed false and writes nothing, so it is safe to repeat. +// Suspending also revokes the user's OAuth tokens, which a later reactivation +// does not restore. The identity link is never touched. +func (s *UserStore) UpdateProvisioned(id string, change UserChange, source AuditEvent) (User, bool, error) { + event := source + event.Outcome = "success" + return s.applyUpdate(id, change.Email, change.DisplayName, change.Role, change.Status, &event, userUpdateOptions{ + skipUnchanged: true, + revokeOAuthOnSuspend: true, + describe: func(before, after User, event *AuditEvent) { + event.EventType, event.Metadata = describeProvisionedUpdate(before, after, source.Metadata) + }, + }) +} + +// describeProvisionedUpdate never records addresses: the audit log names which +// fields changed and the role and status transitions. +func describeProvisionedUpdate(before, after User, base map[string]any) (AuditEventType, map[string]any) { + changed := []string{} + fields := map[string]any{} + if before.Email != after.Email { + changed = append(changed, "email") + } + if before.DisplayName != after.DisplayName { + changed = append(changed, "display_name") + } + if before.Role != after.Role { + changed = append(changed, "role") + fields["role_from"], fields["role_to"] = string(before.Role), string(after.Role) + } + if before.Status != after.Status { + changed = append(changed, "status") + fields["status_from"], fields["status_to"] = string(before.Status), string(after.Status) + } + fields["changed"] = changed + + eventType := AuditEventType("user.updated") + switch { + case before.Status == UserStatusActive && after.Status != UserStatusActive: + eventType = "user.suspended" + case before.Status != UserStatusActive && after.Status == UserStatusActive: + eventType = "user.reactivated" + case before.Role != after.Role: + eventType = "role.changed" + } + return eventType, withMetadata(base, fields) +} + +func withMetadata(base, extra map[string]any) map[string]any { + merged := make(map[string]any, len(base)+len(extra)) + for key, value := range base { + merged[key] = value + } + for key, value := range extra { + merged[key] = value + } + return merged +} diff --git a/internal/auth/provisioning_test.go b/internal/auth/provisioning_test.go new file mode 100644 index 000000000..3951fa22a --- /dev/null +++ b/internal/auth/provisioning_test.go @@ -0,0 +1,349 @@ +package auth + +import ( + "context" + "errors" + "fmt" + "path/filepath" + "sync" + "testing" + + appstore "github.com/labstack/fanout/internal/store" +) + +const testIssuer = "https://issuer.example" + +func provisionFixture(subject, email string, role Role) ProvisionRequest { + return ProvisionRequest{Issuer: testIssuer, Subject: subject, Email: email, Role: role, Status: UserStatusActive} +} + +// fileSQLite returns a database with a real connection pool. The :memory: +// database holds one connection, which would hide transaction races. +func fileSQLite(t *testing.T) *appstore.SQLite { + t.Helper() + db, err := appstore.NewSQLite(filepath.Join(t.TempDir(), "control.db")) + if err != nil { + t.Fatalf("NewSQLite: %v", err) + } + t.Cleanup(func() { _ = db.Close() }) + return db +} + +func provisionSource() AuditEvent { + return AuditEvent{RemoteIP: "192.0.2.1", UserAgent: "test", Metadata: map[string]any{"mode": "scim"}} +} + +func countRows(t *testing.T, db *appstore.SQLite, query string, args ...any) int { + t.Helper() + var count int + if err := db.DB.QueryRow(query, args...).Scan(&count); err != nil { + t.Fatalf("%s: %v", query, err) + } + return count +} + +func TestProvisionFailureAfterAccountInsertLeavesNothing(t *testing.T) { + failures := map[string]string{ + "identity insert": `CREATE TRIGGER fail_write BEFORE INSERT ON user_identities BEGIN SELECT RAISE(ABORT, 'injected'); END`, + "audit insert": `CREATE TRIGGER fail_write BEFORE INSERT ON auth_audit_events WHEN NEW.event_type = 'identity.linked' BEGIN SELECT RAISE(ABORT, 'injected'); END`, + } + for name, trigger := range failures { + t.Run(name, func(t *testing.T) { + db := fileSQLite(t) + users := NewUserStore(db.DB) + if _, err := db.DB.Exec(trigger); err != nil { + t.Fatalf("install trigger: %v", err) + } + _, _, _, err := users.ProvisionFederated(t.Context(), provisionFixture("subject-1", "owner@example.com", RoleAdmin), provisionSource()) + if err == nil { + t.Fatal("provisioning succeeded despite the injected failure") + } + if got := countRows(t, db, `SELECT COUNT(*) FROM users`); got != 0 { + t.Fatalf("users after rollback = %d, want 0", got) + } + if got := countRows(t, db, `SELECT COUNT(*) FROM user_identities`); got != 0 { + t.Fatalf("identities after rollback = %d, want 0", got) + } + if got := countRows(t, db, `SELECT COUNT(*) FROM auth_audit_events`); got != 0 { + t.Fatalf("audit events after rollback = %d, want 0", got) + } + if _, err := db.DB.Exec(`DROP TRIGGER fail_write`); err != nil { + t.Fatalf("drop trigger: %v", err) + } + if _, _, created, err := users.ProvisionFederated(t.Context(), provisionFixture("subject-1", "owner@example.com", RoleAdmin), provisionSource()); err != nil || !created { + t.Fatalf("retry after failure: created=%v err=%v", created, err) + } + }) + } +} + +func TestProvisionRetryReturnsExistingAccountUnchanged(t *testing.T) { + db := fileSQLite(t) + users := NewUserStore(db.DB) + first, identity, created, err := users.ProvisionFederated(t.Context(), provisionFixture("subject-1", "owner@example.com", RoleAdmin), provisionSource()) + if err != nil || !created || identity.UserID != first.ID { + t.Fatalf("first provision: created=%v identity=%+v err=%v", created, identity, err) + } + if identity.LastLoginAt != "" { + t.Fatalf("a provisioned identity has not signed in, got last login %q", identity.LastLoginAt) + } + // A delayed retry carrying stale values must not overwrite the account. + stale := provisionFixture("subject-1", "old@example.com", RoleViewer) + stale.Status = UserStatusSuspended + again, _, created, err := users.ProvisionFederated(t.Context(), stale, provisionSource()) + if err != nil || created { + t.Fatalf("retry: created=%v err=%v", created, err) + } + if again.ID != first.ID || again.Email != "owner@example.com" || again.Role != RoleAdmin || again.Status != UserStatusActive { + t.Fatalf("retry changed the account: %+v", again) + } + if got := countRows(t, db, `SELECT COUNT(*) FROM auth_audit_events WHERE event_type = 'user.provisioned'`); got != 1 { + t.Fatalf("user.provisioned events = %d, want 1", got) + } +} + +func TestProvisionRefusesEmailHeldByDifferentAccount(t *testing.T) { + db := fileSQLite(t) + users := NewUserStore(db.DB) + local, err := users.CreateWithAudit("taken@example.com", "", RoleAdmin, AuditEvent{EventType: "user.created", Outcome: "success"}) + if err != nil { + t.Fatalf("create local account: %v", err) + } + _, _, _, err = users.ProvisionFederated(t.Context(), provisionFixture("subject-1", "taken@example.com", RoleViewer), provisionSource()) + if !errors.Is(err, ErrUserConflict) { + t.Fatalf("provision over local account = %v, want ErrUserConflict", err) + } + if got := countRows(t, db, `SELECT COUNT(*) FROM user_identities WHERE user_id = ?`, local.ID); got != 0 { + t.Fatalf("local account was linked by email: %d identities", got) + } +} + +func TestProvisionOnEmptyDatabaseRequiresActiveAdministrator(t *testing.T) { + for name, req := range map[string]ProvisionRequest{ + "viewer": provisionFixture("subject-1", "first@example.com", RoleViewer), + "operator": provisionFixture("subject-1", "first@example.com", RoleOperator), + "suspended admin": {Issuer: testIssuer, Subject: "subject-1", Email: "first@example.com", Role: RoleAdmin, Status: UserStatusSuspended}, + } { + t.Run(name, func(t *testing.T) { + db := fileSQLite(t) + users := NewUserStore(db.DB) + if _, _, _, err := users.ProvisionFederated(t.Context(), req, provisionSource()); !errors.Is(err, ErrFirstUserMustBeAdmin) { + t.Fatalf("provision = %v, want ErrFirstUserMustBeAdmin", err) + } + if got := countRows(t, db, `SELECT COUNT(*) FROM users`); got != 0 { + t.Fatalf("users = %d, want 0", got) + } + }) + } +} + +func TestConcurrentAdministratorsOnEmptyDatabaseAreAllCreated(t *testing.T) { + db := fileSQLite(t) + users := NewUserStore(db.DB) + const requests = 12 + start := make(chan struct{}) + errs := make(chan error, requests) + var wg sync.WaitGroup + for i := range requests { + wg.Add(1) + go func() { + defer wg.Done() + <-start + req := provisionFixture(fmt.Sprintf("subject-%d", i), fmt.Sprintf("admin-%d@example.com", i), RoleAdmin) + _, _, created, err := users.ProvisionFederated(context.Background(), req, provisionSource()) + if err == nil && !created { + err = errors.New("not created") + } + errs <- err + }() + } + close(start) + wg.Wait() + close(errs) + for err := range errs { + if err != nil { + t.Fatalf("concurrent administrator rejected: %v", err) + } + } + if got := countRows(t, db, `SELECT COUNT(*) FROM users WHERE role = 'admin'`); got != requests { + t.Fatalf("administrators = %d, want %d", got, requests) + } + if got := countRows(t, db, `SELECT COUNT(*) FROM user_identities`); got != requests { + t.Fatalf("identities = %d, want %d", got, requests) + } + if got := countRows(t, db, `SELECT COUNT(*) FROM auth_audit_events WHERE event_type = 'user.provisioned' AND json_extract(metadata_json, '$.first_user') = 1`); got != 1 { + t.Fatalf("first-user events = %d, want exactly 1", got) + } +} + +func TestConcurrentRetriesOfOneIdentityCreateOneAccount(t *testing.T) { + db := fileSQLite(t) + users := NewUserStore(db.DB) + const requests = 10 + start := make(chan struct{}) + type outcome struct { + id string + created bool + err error + } + outcomes := make(chan outcome, requests) + var wg sync.WaitGroup + for range requests { + wg.Add(1) + go func() { + defer wg.Done() + <-start + user, _, created, err := users.ProvisionFederated(context.Background(), provisionFixture("subject-1", "owner@example.com", RoleAdmin), provisionSource()) + outcomes <- outcome{user.ID, created, err} + }() + } + close(start) + wg.Wait() + close(outcomes) + created, ids := 0, map[string]bool{} + for result := range outcomes { + if result.err != nil { + t.Fatalf("retry failed: %v", result.err) + } + ids[result.id] = true + if result.created { + created++ + } + } + if created != 1 || len(ids) != 1 { + t.Fatalf("created = %d across %d accounts, want 1 and 1", created, len(ids)) + } +} + +func TestConcurrentRemovalNeverLeavesNoActiveAdministrator(t *testing.T) { + viewer, suspended := RoleViewer, UserStatusSuspended + for name, change := range map[string]UserChange{ + "deactivation": {Status: &suspended}, + "demotion": {Role: &viewer}, + } { + t.Run(name, func(t *testing.T) { + db := fileSQLite(t) + users := NewUserStore(db.DB) + const admins = 8 + ids := make([]string, admins) + for i := range admins { + user, _, _, err := users.ProvisionFederated(t.Context(), provisionFixture(fmt.Sprintf("subject-%d", i), fmt.Sprintf("admin-%d@example.com", i), RoleAdmin), provisionSource()) + if err != nil { + t.Fatalf("seed administrator: %v", err) + } + ids[i] = user.ID + } + start := make(chan struct{}) + errs := make(chan error, admins) + var wg sync.WaitGroup + for _, id := range ids { + wg.Add(1) + go func() { + defer wg.Done() + <-start + _, _, err := users.UpdateProvisioned(id, change, provisionSource()) + errs <- err + }() + } + close(start) + wg.Wait() + close(errs) + refused := 0 + for err := range errs { + switch { + case errors.Is(err, ErrLastActiveAdmin): + refused++ + case err != nil: + t.Fatalf("update failed: %v", err) + } + } + active, err := users.CountActiveAdmins() + if err != nil { + t.Fatalf("CountActiveAdmins: %v", err) + } + if active != 1 || refused != 1 { + t.Fatalf("active administrators = %d, refused = %d, want 1 and 1", active, refused) + } + }) + } +} + +func TestUpdateProvisionedRepeatWritesNothing(t *testing.T) { + db := fileSQLite(t) + users := NewUserStore(db.DB) + if _, _, _, err := users.ProvisionFederated(t.Context(), provisionFixture("owner", "owner@example.com", RoleAdmin), provisionSource()); err != nil { + t.Fatalf("seed owner: %v", err) + } + member, _, _, err := users.ProvisionFederated(t.Context(), provisionFixture("member", "member@example.com", RoleViewer), provisionSource()) + if err != nil { + t.Fatalf("seed member: %v", err) + } + role := RoleOperator + updated, changed, err := users.UpdateProvisioned(member.ID, UserChange{Role: &role}, provisionSource()) + if err != nil || !changed || updated.Role != RoleOperator { + t.Fatalf("first update: %+v changed=%v err=%v", updated, changed, err) + } + version := updated.AuthVersion + again, changed, err := users.UpdateProvisioned(member.ID, UserChange{Role: &role}, provisionSource()) + if err != nil || changed { + t.Fatalf("repeat update: changed=%v err=%v", changed, err) + } + if again.AuthVersion != version { + t.Fatalf("repeat bumped the auth version: %d -> %d", version, again.AuthVersion) + } + if got := countRows(t, db, `SELECT COUNT(*) FROM auth_audit_events WHERE event_type = 'role.changed' AND target_id = ?`, member.ID); got != 1 { + t.Fatalf("role.changed events = %d, want 1", got) + } +} + +func TestUpdateProvisionedSuspensionRevokesOAuthAndKeepsIdentity(t *testing.T) { + db := fileSQLite(t) + users := NewUserStore(db.DB) + identities := NewIdentityStore(db.DB) + if _, _, _, err := users.ProvisionFederated(t.Context(), provisionFixture("owner", "owner@example.com", RoleAdmin), provisionSource()); err != nil { + t.Fatalf("seed owner: %v", err) + } + member, _, _, err := users.ProvisionFederated(t.Context(), provisionFixture("member", "member@example.com", RoleViewer), provisionSource()) + if err != nil { + t.Fatalf("seed member: %v", err) + } + if _, err := db.DB.Exec(`INSERT INTO oauth_clients (client_id, client_name, redirect_uris_json, grant_types_json, response_types_json, token_endpoint_auth_method, created_at) VALUES ('client-1', 'Client', '[]', '[]', '[]', 'none', 1)`); err != nil { + t.Fatalf("insert client: %v", err) + } + if _, err := db.DB.Exec(`INSERT INTO oauth_authorization_codes (code_hash, client_id, user_id, redirect_uri, scope, resource, code_challenge, expires_at, created_at) VALUES ('code-1', 'client-1', ?, 'r', 's', 'res', 'c', 9999999999, 1)`, member.ID); err != nil { + t.Fatalf("insert code: %v", err) + } + if _, err := db.DB.Exec(`INSERT INTO oauth_tokens (token_hash, kind, client_id, user_id, scope, resource, expires_at, created_at, family_id) VALUES ('hash-1', 'access', 'client-1', ?, 's', 'res', 9999999999, 1, 'family-1')`, member.ID); err != nil { + t.Fatalf("insert token: %v", err) + } + + suspended := UserStatusSuspended + if _, _, err := users.UpdateProvisioned(member.ID, UserChange{Status: &suspended}, provisionSource()); err != nil { + t.Fatalf("suspend: %v", err) + } + if got := countRows(t, db, `SELECT COUNT(*) FROM oauth_tokens WHERE user_id = ? AND revoked_at IS NOT NULL`, member.ID); got != 1 { + t.Fatalf("revoked tokens = %d, want 1", got) + } + if got := countRows(t, db, `SELECT COUNT(*) FROM oauth_authorization_codes WHERE user_id = ?`, member.ID); got != 0 { + t.Fatalf("authorization codes = %d, want 0", got) + } + + active := UserStatusActive + if _, _, err := users.UpdateProvisioned(member.ID, UserChange{Status: &active}, provisionSource()); err != nil { + t.Fatalf("reactivate: %v", err) + } + email := "renamed@example.com" + if _, _, err := users.UpdateProvisioned(member.ID, UserChange{Email: &email}, provisionSource()); err != nil { + t.Fatalf("email change: %v", err) + } + identity, err := identities.Find(t.Context(), testIssuer, "member") + if err != nil || identity.UserID != member.ID { + t.Fatalf("identity after reactivation and email change: %+v err=%v", identity, err) + } + if got := countRows(t, db, `SELECT COUNT(*) FROM auth_audit_events WHERE event_type = 'user.reactivated' AND target_id = ?`, member.ID); got != 1 { + t.Fatalf("user.reactivated events = %d, want 1", got) + } + if got := countRows(t, db, `SELECT COUNT(*) FROM oauth_tokens WHERE user_id = ? AND revoked_at IS NULL`, member.ID); got != 0 { + t.Fatalf("live tokens after reactivation = %d, want 0", got) + } +} diff --git a/internal/auth/user_store.go b/internal/auth/user_store.go index ffa23d5c4..64408ba49 100644 --- a/internal/auth/user_store.go +++ b/internal/auth/user_store.go @@ -192,16 +192,37 @@ func (s *UserStore) UpdateWithAudit(id string, email, displayName *string, role } func (s *UserStore) update(id string, email, displayName *string, role *Role, status *UserStatus, event *AuditEvent) (User, error) { + user, _, err := s.applyUpdate(id, email, displayName, role, status, event, userUpdateOptions{}) + return user, err +} + +// userUpdateOptions adds the behaviour a directory-driven update needs on top +// of an administrator's update. +type userUpdateOptions struct { + // skipUnchanged leaves a request that changes nothing unwritten: no + // session or token revocation and no audit event, so a provisioner can + // resend the same state. + skipUnchanged bool + // revokeOAuthOnSuspend revokes the user's OAuth tokens and authorization + // codes when the account leaves the active state, so a later reactivation + // cannot bring them back. + revokeOAuthOnSuspend bool + // describe fills in the audit event type and metadata, which depend on the + // row read inside the transaction. + describe func(before, after User, event *AuditEvent) +} + +func (s *UserStore) applyUpdate(id string, email, displayName *string, role *Role, status *UserStatus, event *AuditEvent, opts userUpdateOptions) (User, bool, error) { ctx, cancel := DetachedWriteContext(context.Background()) defer cancel() conn, err := s.db.Conn(ctx) if err != nil { - return User{}, fmt.Errorf("auth: open user conn: %w", err) + return User{}, false, fmt.Errorf("auth: open user conn: %w", err) } defer conn.Close() if _, err := conn.ExecContext(ctx, "BEGIN IMMEDIATE"); err != nil { - return User{}, fmt.Errorf("auth: begin user update: %w", err) + return User{}, false, fmt.Errorf("auth: begin user update: %w", err) } committed := false defer func() { @@ -213,10 +234,10 @@ func (s *UserStore) update(id string, email, displayName *string, role *Role, st q := generated.New(conn) row, err := q.GetUserByID(ctx, id) if errors.Is(err, sql.ErrNoRows) { - return User{}, ErrUserNotFound + return User{}, false, ErrUserNotFound } if err != nil { - return User{}, fmt.Errorf("auth: get user by id: %w", err) + return User{}, false, fmt.Errorf("auth: get user by id: %w", err) } before := toUser(row) @@ -229,23 +250,26 @@ func (s *UserStore) update(id string, email, displayName *string, role *Role, st } if role != nil { if !ValidRole(string(*role)) { - return User{}, fmt.Errorf("auth: invalid role %q", *role) + return User{}, false, fmt.Errorf("auth: invalid role %q", *role) } existing.Role = *role } if status != nil { if !ValidUserStatus(string(*status)) { - return User{}, fmt.Errorf("auth: invalid status %q", *status) + return User{}, false, fmt.Errorf("auth: invalid status %q", *status) } existing.Status = *status } + if opts.skipUnchanged && existing.Email == before.Email && existing.DisplayName == before.DisplayName && existing.Role == before.Role && existing.Status == before.Status { + return before, false, nil + } if row.Role == "admin" && row.Status == string(UserStatusActive) && (existing.Status != UserStatusActive || existing.Role != "admin") { admins, err := q.CountActiveAdmins(ctx) if err != nil { - return User{}, fmt.Errorf("auth: count active admins: %w", err) + return User{}, false, fmt.Errorf("auth: count active admins: %w", err) } if admins <= 1 { - return User{}, ErrLastActiveAdmin + return User{}, false, ErrLastActiveAdmin } } @@ -260,35 +284,43 @@ func (s *UserStore) update(id string, email, displayName *string, role *Role, st }) if err != nil { if appstore.IsUniqueConstraint(err) { - return User{}, fmt.Errorf("%w: %v", ErrUserConflict, err) + return User{}, false, fmt.Errorf("%w: %v", ErrUserConflict, err) } - return User{}, fmt.Errorf("auth: update user: %w", err) + return User{}, false, fmt.Errorf("auth: update user: %w", err) } securityChanged := before.Email != existing.Email || before.Role != existing.Role || before.Status != existing.Status if securityChanged { if err := q.IncrementUserAuthVersion(ctx, generated.IncrementUserAuthVersionParams{UpdatedAt: now, ID: id}); err != nil { - return User{}, fmt.Errorf("auth: increment auth version: %w", err) + return User{}, false, fmt.Errorf("auth: increment auth version: %w", err) } if _, err := conn.ExecContext(ctx, `DELETE FROM sessions WHERE user_id = ?`, id); err != nil { - return User{}, fmt.Errorf("auth: revoke user sessions: %w", err) + return User{}, false, fmt.Errorf("auth: revoke user sessions: %w", err) } u, err = q.GetUserByID(ctx, id) if err != nil { - return User{}, fmt.Errorf("auth: reload user after revocation: %w", err) + return User{}, false, fmt.Errorf("auth: reload user after revocation: %w", err) + } + } + if opts.revokeOAuthOnSuspend && before.Status == UserStatusActive && existing.Status != UserStatusActive { + if err := revokeUserOAuth(ctx, conn, id); err != nil { + return User{}, false, err } } if event != nil { + if opts.describe != nil { + opts.describe(before, existing, event) + } event.TargetType = "user" event.TargetID = id if err := recordAudit(ctx, conn, *event); err != nil { - return User{}, err + return User{}, false, err } } if _, err := conn.ExecContext(ctx, "COMMIT"); err != nil { - return User{}, fmt.Errorf("auth: commit user update: %w", err) + return User{}, false, fmt.Errorf("auth: commit user update: %w", err) } committed = true - return toUser(u), nil + return toUser(u), true, nil } // DeleteWithAudit removes a user and all of its browser sessions by ID. @@ -419,11 +451,8 @@ func (s *UserStore) revokeAllSessions(id string, event *AuditEvent) error { if _, err := conn.ExecContext(ctx, `DELETE FROM sessions WHERE user_id = ?`, id); err != nil { return fmt.Errorf("auth: delete user sessions: %w", err) } - if _, err := conn.ExecContext(ctx, `UPDATE oauth_tokens SET revoked_at = COALESCE(revoked_at, ?) WHERE user_id = ?`, time.Now().UTC().Unix(), id); err != nil { - return fmt.Errorf("auth: revoke user OAuth tokens: %w", err) - } - if _, err := conn.ExecContext(ctx, `DELETE FROM oauth_authorization_codes WHERE user_id = ?`, id); err != nil { - return fmt.Errorf("auth: delete user OAuth authorization codes: %w", err) + if err := revokeUserOAuth(ctx, conn, id); err != nil { + return err } if event != nil { event.TargetType = "user" @@ -439,6 +468,16 @@ func (s *UserStore) revokeAllSessions(id string, event *AuditEvent) error { return nil } +func revokeUserOAuth(ctx context.Context, conn *sql.Conn, id string) error { + if _, err := conn.ExecContext(ctx, `UPDATE oauth_tokens SET revoked_at = COALESCE(revoked_at, ?) WHERE user_id = ?`, time.Now().UTC().Unix(), id); err != nil { + return fmt.Errorf("auth: revoke user OAuth tokens: %w", err) + } + if _, err := conn.ExecContext(ctx, `DELETE FROM oauth_authorization_codes WHERE user_id = ?`, id); err != nil { + return fmt.Errorf("auth: delete user OAuth authorization codes: %w", err) + } + return nil +} + // CreateFirstAdminWithAudit atomically creates the first admin user. // Returns ErrSetupComplete if users already exist (race-safe). func (s *UserStore) CreateFirstAdminWithAudit(email, displayName string, event AuditEvent) (User, error) { @@ -464,11 +503,11 @@ func (s *UserStore) createFirstAdmin(email, displayName string, event *AuditEven }() q := generated.New(conn) - count, err := q.CountUsers(ctx) + empty, err := noUsersExist(ctx, q) if err != nil { - return User{}, fmt.Errorf("auth: check user count: %w", err) + return User{}, err } - if count > 0 { + if !empty { return User{}, ErrSetupComplete } @@ -497,6 +536,17 @@ func (s *UserStore) createFirstAdmin(email, displayName string, event *AuditEven // ErrSetupComplete is returned when setup is attempted but users already exist. var ErrSetupComplete = errors.New("setup already complete") +// noUsersExist is the empty-database check. Callers must hold a BEGIN IMMEDIATE +// transaction, so nothing else can create a user between the check and the +// insert that depends on it. +func noUsersExist(ctx context.Context, q *generated.Queries) (bool, error) { + count, err := q.CountUsers(ctx) + if err != nil { + return false, fmt.Errorf("auth: check user count: %w", err) + } + return count == 0, nil +} + func newCreateUserParams(email, displayName string, role Role) (generated.CreateUserParams, error) { id, err := appid.New() if err != nil { diff --git a/internal/config/config.go b/internal/config/config.go index bf4b84f5a..67291ad08 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -177,6 +177,8 @@ type Config struct { SessionIdleTTL time.Duration `group:"auth" env:"FANOUT_SESSION_IDLE_TTL" default:"12h"` // SessionAbsoluteTTL limits total session lifetime; it must be at least FANOUT_SESSION_IDLE_TTL. SessionAbsoluteTTL time.Duration `group:"auth" env:"FANOUT_SESSION_ABSOLUTE_TTL" default:"168h"` + // SCIMToken enables SCIM 2.0 user provisioning under /scim/v2 and turns off browser setup; requires OIDC mode and at least 32 characters. + SCIMToken string `group:"auth" env:"FANOUT_SCIM_TOKEN" secret:"true"` // OIDCIssuerURL selects the identity provider issuer; required in OIDC mode. Fanout starts while it is unreachable and retries discovery; a mismatched issuer fails startup. OIDCIssuerURL string `group:"auth" env:"FANOUT_OIDC_ISSUER_URL"` // OIDCClientID identifies Fanout's client registration; required in OIDC mode. @@ -360,6 +362,15 @@ func (c Config) Validate() error { return fmt.Errorf("FANOUT_SELF_SIGNUP requires SMTP") } } + if c.SCIMToken != "" { + // SCIM links each account to (issuer, subject), which needs an issuer. + if authMode != "oidc" { + return fmt.Errorf("FANOUT_SCIM_TOKEN requires FANOUT_AUTH_MODE=oidc") + } + if len(c.SCIMToken) < 32 || strings.ContainsAny(c.SCIMToken, " \t\r\n") { + return fmt.Errorf("FANOUT_SCIM_TOKEN must be at least 32 characters with no whitespace") + } + } if authMode == "oidc" { issuer, err := url.Parse(strings.TrimSpace(c.OIDCIssuerURL)) if err != nil || issuer.Scheme != "https" || issuer.Host == "" { diff --git a/internal/config/config_test.go b/internal/config/config_test.go index efb9e1b6a..102fd9eb0 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -7,6 +7,7 @@ import ( "path/filepath" "reflect" "runtime" + "slices" "strings" "testing" "time" @@ -636,3 +637,65 @@ func TestLoadIngestToken(t *testing.T) { } }) } + +func TestLoadSCIMToken(t *testing.T) { + const name = "FANOUT_SCIM_TOKEN" + valid := strings.Repeat("s", 32) + oidc := append(validEnvironment(), + "FANOUT_AUTH_MODE=oidc", + "FANOUT_OIDC_ISSUER_URL=https://issuer.example.com", + "FANOUT_OIDC_CLIENT_ID=client", + "FANOUT_OIDC_CLIENT_SECRET=secret", + "FANOUT_PUBLIC_URL=https://fanout.example.com", + ) + + t.Run("absent by default", func(t *testing.T) { + cfg, err := Load(LoadOptions{Environ: oidc}) + if err != nil { + t.Fatal(err) + } + if cfg.SCIMToken != "" { + t.Fatal("SCIM token must default to empty") + } + }) + + t.Run("environment value", func(t *testing.T) { + cfg, err := Load(LoadOptions{Environ: append(slices.Clone(oidc), name+"="+valid)}) + if err != nil { + t.Fatal(err) + } + if cfg.SCIMToken != valid { + t.Fatal("SCIM token was not loaded from the environment") + } + }) + + t.Run("file value", func(t *testing.T) { + path := filepath.Join(t.TempDir(), "scim-token") + if err := os.WriteFile(path, []byte(valid+"\n"), 0o600); err != nil { + t.Fatal(err) + } + cfg, err := Load(LoadOptions{Environ: append(slices.Clone(oidc), name+"_FILE="+path)}) + if err != nil { + t.Fatal(err) + } + if cfg.SCIMToken != valid { + t.Fatal("SCIM token was not loaded from its file") + } + }) + + t.Run("requires OIDC mode", func(t *testing.T) { + _, err := Load(LoadOptions{Environ: append(validEnvironment(), name+"="+valid)}) + if err == nil || !strings.Contains(err.Error(), "FANOUT_AUTH_MODE=oidc") { + t.Fatalf("Load = %v", err) + } + }) + + for label, token := range map[string]string{"short": strings.Repeat("s", 31), "whitespace": strings.Repeat("s", 32) + " x"} { + t.Run(label, func(t *testing.T) { + _, err := Load(LoadOptions{Environ: append(slices.Clone(oidc), name+"="+token)}) + if err == nil || !strings.Contains(err.Error(), name) || strings.Contains(err.Error(), token) { + t.Fatalf("Load = %v", err) + } + }) + } +} diff --git a/site/src/content/docs/docs/concepts/authentication.mdx b/site/src/content/docs/docs/concepts/authentication.mdx index c0f12920c..425ffa746 100644 --- a/site/src/content/docs/docs/concepts/authentication.mdx +++ b/site/src/content/docs/docs/concepts/authentication.mdx @@ -123,6 +123,39 @@ need `Fanout-Request: 1` or a matching Origin/Referer; cross-site browser reques are rejected. Session expiry or revocation requires signing in again. Delete the temporary jar when finished and sign out to revoke that session. +## SCIM provisioning + +Set `FANOUT_SCIM_TOKEN` (or `FANOUT_SCIM_TOKEN_FILE`) so an identity provider or +automation can create, update and deactivate accounts. It requires +`FANOUT_AUTH_MODE=oidc` and at least 32 characters. Without a token the routes +do not exist. + +With a token, Fanout prints no setup banner and `/api/auth/setup` returns `410`; +the first administrator comes from SCIM. + +Fanout implements a small subset of SCIM 2.0 under `/scim/v2`. Send +`Authorization: Bearer `. Responses and errors use +`application/scim+json` and the RFC 7644 formats. + +- `POST /scim/v2/Users` creates an account from `externalId`, `userName` (the + email address) and one `roles` value of `admin`, `operator` or `viewer`. The + account and its identity at the configured issuer are written together, so the + first OIDC login needs no match by email. Repeating the request returns the + existing account with `200` and changes nothing. +- `GET /scim/v2/Users?filter=externalId eq ""` finds an account. + `userName eq ""` also works. Other filters return `invalidFilter`. +- `PATCH /scim/v2/Users/{id}` changes `active`, the role, the email and + `displayName`. Resending the current values writes nothing. + +An email held by a different account returns `409`. While there are no users, +only an active administrator can be created. Deactivating or demoting the last +active administrator returns `409`. + +Deactivation revokes the user's browser sessions and MCP tokens. Reactivation +restores neither, and keeps the identity link. See +[docs/authentication.md](https://github.com/labstack/fanout/blob/main/docs/authentication.md#scim-provisioning) +for the full contract. + ## Recover local sign-in Run with the server's environment and data directory: diff --git a/site/src/content/docs/docs/reference/api.mdx b/site/src/content/docs/docs/reference/api.mdx index 2101702e0..2589edf0c 100644 --- a/site/src/content/docs/docs/reference/api.mdx +++ b/site/src/content/docs/docs/reference/api.mdx @@ -161,6 +161,10 @@ Operational responses at `/healthz`, `/readyz` and `/metrics` keep their bodies. | `POST` | `/oauth/register` | protocol handshake | | `POST` | `/oauth/token` | protocol handshake | | `GET` | `/readyz` | none | +| `GET` | `/scim/v2/Users` | SCIM bearer token, when `FANOUT_SCIM_TOKEN` is set | +| `POST` | `/scim/v2/Users` | SCIM bearer token, when `FANOUT_SCIM_TOKEN` is set | +| `GET` | `/scim/v2/Users/:id` | SCIM bearer token, when `FANOUT_SCIM_TOKEN` is set | +| `PATCH` | `/scim/v2/Users/:id` | SCIM bearer token, when `FANOUT_SCIM_TOKEN` is set | ## What the requirements mean diff --git a/site/src/content/docs/docs/reference/configuration/auth.mdx b/site/src/content/docs/docs/reference/configuration/auth.mdx index b8097c70a..c22795bfb 100644 --- a/site/src/content/docs/docs/reference/configuration/auth.mdx +++ b/site/src/content/docs/docs/reference/configuration/auth.mdx @@ -31,6 +31,7 @@ Vendor credentials and endpoints keep the vendor's documented names. | `FANOUT_OIDC_EMAIL_VERIFICATION` | string | `required` | | `FANOUT_OIDC_ISSUER_URL` | string | — | | `FANOUT_OIDC_OPERATOR_GROUPS` | string | — | +| `FANOUT_SCIM_TOKEN` or `FANOUT_SCIM_TOKEN_FILE` | string · secret | — | | `FANOUT_SELF_SIGNUP` | boolean | `false` | | `FANOUT_SESSION_ABSOLUTE_TTL` | duration | `168h` | | `FANOUT_SESSION_IDLE_TTL` | duration | `12h` | @@ -89,6 +90,10 @@ Selects the identity provider issuer; required in OIDC mode. Fanout starts while Lists identity-provider groups mapped to operator, separated by commas. +### `FANOUT_SCIM_TOKEN` + +Enables SCIM 2.0 user provisioning under /scim/v2 and turns off browser setup; requires OIDC mode and at least 32 characters. + ### `FANOUT_SELF_SIGNUP` Allows verified email addresses to create viewer accounts; requires local auth and SMTP. From 07b75cb9dc45e0c69930cb367b514a957f8aa590 Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Sun, 8 Nov 2026 11:32:51 -0800 Subject: [PATCH 2/2] fix(auth): end OAuth access on every suspension and keep SCIM lookups out of logs The request log recorded the full URI, so a SCIM filter put an email address or subject in the logs. SCIM requests are now logged without their query. Only SCIM deactivation revoked OAuth tokens, so suspending from the browser route left tokens that worked again after reactivation. Every transition out of active now revokes them. A repeated SCIM deactivation also removes any session or credential still live on an already-suspended account. --- cmd/fanout/main.go | 29 +-- docs/authentication.md | 10 +- internal/api/request_log.go | 51 +++++ internal/api/scim_test.go | 189 ++++++++++++++++++ internal/auth/oauth_store_test.go | 5 +- internal/auth/provisioning.go | 13 +- internal/auth/provisioning_test.go | 22 ++ internal/auth/user_store.go | 73 +++++-- .../docs/docs/concepts/authentication.mdx | 4 +- 9 files changed, 338 insertions(+), 58 deletions(-) create mode 100644 internal/api/request_log.go diff --git a/cmd/fanout/main.go b/cmd/fanout/main.go index 4e69282ad..3d344cb75 100644 --- a/cmd/fanout/main.go +++ b/cmd/fanout/main.go @@ -17,7 +17,6 @@ import ( "net/url" "os" "os/signal" - "regexp" "runtime" "strings" "syscall" @@ -51,8 +50,6 @@ import ( "github.com/labstack/fanout/internal/ui" ) -var tokenRedactRe = regexp.MustCompile(`token=[^&]+`) - // version is set at build time via -ldflags "-X main.version=...". var version = "dev" @@ -245,31 +242,7 @@ func main() { slog.Info("trusted proxy IP extraction enabled", "header", "X-Forwarded-For", "cidrs", cfg.TrustedProxyCIDRs) } e.Use(middleware.Recover()) - e.Use(middleware.RequestLoggerWithConfig(middleware.RequestLoggerConfig{ - LogURI: true, - LogStatus: true, - LogLatency: true, - LogMethod: true, - LogRemoteIP: true, - LogUserAgent: true, - HandleError: true, - LogValuesFunc: func(c *echo.Context, v middleware.RequestLoggerValues) error { - uri := v.URI - if strings.Contains(uri, "token=") { - uri = tokenRedactRe.ReplaceAllString(uri, "token=REDACTED") - } - attrs := []any{"method", v.Method, "uri", uri, "status", v.Status, "latency", v.Latency} - if v.Error != nil { - attrs = []any{"method", v.Method, "route", c.Path(), "status", v.Status, "latency", v.Latency, "err", v.Error} - } - if v.Status >= 500 { - slog.Error("request", attrs...) - } else { - slog.Info("request", attrs...) - } - return nil - }, - })) + e.Use(api.RequestLogger()) api.RegisterAuthMiddleware(e, userStore, browserSessions, auditStore, cfg) diff --git a/docs/authentication.md b/docs/authentication.md index c943e4b3d..ccb6f0475 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -144,7 +144,8 @@ when there are no users. `{"status":"active"}`. Unknown fields return `400`. Email, role, and status changes revoke browser -sessions. Suspension also blocks sign-in and OAuth token use. Demotion, +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. The first-run `POST /api/auth/setup` request uses `display_name` alongside `email` and `setup_token`. @@ -379,7 +380,12 @@ runs in the same write transaction as the update. Deactivation suspends the account. In one transaction it revokes the user's browser sessions, revokes their MCP OAuth access and refresh tokens, and deletes their pending OAuth authorization codes. Reactivation restores none of these, so -the user signs in and connects MCP clients again. +the user signs in and connects MCP clients again. Deactivating an account that +is already suspended removes anything still live and writes a `session.revoked` +event; if nothing is live it writes nothing. + +Requests to `/scim/v2` are logged without their query string, because a filter +holds an email address or subject. Every change writes an audit event: `user.provisioned` and `identity.linked` on creation, then `user.suspended`, `user.reactivated`, `role.changed` or diff --git a/internal/api/request_log.go b/internal/api/request_log.go new file mode 100644 index 000000000..e511e4a55 --- /dev/null +++ b/internal/api/request_log.go @@ -0,0 +1,51 @@ +package api + +import ( + "log/slog" + "regexp" + "strings" + + "github.com/labstack/echo/v5" + "github.com/labstack/echo/v5/middleware" +) + +var tokenRedactRe = regexp.MustCompile(`token=[^&]+`) + +// RequestLogger logs each request without credentials or directory lookups. +func RequestLogger() echo.MiddlewareFunc { + return middleware.RequestLoggerWithConfig(middleware.RequestLoggerConfig{ + LogURI: true, + LogStatus: true, + LogLatency: true, + LogMethod: true, + LogRemoteIP: true, + LogUserAgent: true, + HandleError: true, + LogValuesFunc: func(c *echo.Context, v middleware.RequestLoggerValues) error { + uri := loggedRequestURI(c.Request().URL.Path, v.URI) + attrs := []any{"method", v.Method, "uri", uri, "status", v.Status, "latency", v.Latency} + if v.Error != nil { + attrs = []any{"method", v.Method, "route", c.Path(), "status", v.Status, "latency", v.Latency, "err", v.Error} + } + if v.Status >= 500 { + slog.Error("request", attrs...) + } else { + slog.Info("request", attrs...) + } + return nil + }, + }) +} + +// loggedRequestURI drops the query from SCIM requests, whose filter holds an +// email address or subject, and redacts tokens elsewhere. +func loggedRequestURI(path, uri string) string { + if isSCIMPath(path) { + uri, _, _ = strings.Cut(uri, "?") + return uri + } + if strings.Contains(uri, "token=") { + return tokenRedactRe.ReplaceAllString(uri, "token=REDACTED") + } + return uri +} diff --git a/internal/api/scim_test.go b/internal/api/scim_test.go index ceeae5106..fa4d8e5b2 100644 --- a/internal/api/scim_test.go +++ b/internal/api/scim_test.go @@ -620,6 +620,195 @@ func TestSCIMDoesNotLogToken(t *testing.T) { } } +func TestSCIMFilterValuesAreNotLogged(t *testing.T) { + var logs bytes.Buffer + previous := slog.Default() + slog.SetDefault(slog.New(slog.NewTextHandler(&logs, &slog.HandlerOptions{Level: slog.LevelDebug}))) + t.Cleanup(func() { slog.SetDefault(previous) }) + + sqlite, err := appstore.NewSQLite(":memory:") + if err != nil { + t.Fatalf("NewSQLite: %v", err) + } + t.Cleanup(func() { _ = sqlite.Close() }) + cfg := scimTestConfig() + users := auth.NewUserStore(sqlite.DB) + sessions := auth.NewBrowserSessions(sqlite.DB, 12*time.Hour, 7*24*time.Hour, false) + e := echo.New() + e.HTTPErrorHandler = HTTPErrorHandler + // The logger is outermost, as in production, so refused requests count. + e.Use(RequestLogger()) + RegisterAuthMiddleware(e, users, sessions, auth.NewAuditStore(sqlite.DB), cfg) + RegisterSCIMRoutes(e, cfg, users, auth.NewIdentityStore(sqlite.DB)) + + for _, filter := range []string{`userName eq "person@example.com"`, `externalId eq "opaque-subject-value"`} { + target := scimUsersPath + "?filter=" + url.QueryEscape(filter) + if rec := serve(t, e, http.MethodGet, target, "", scimHeaders()); rec.Code != http.StatusOK { + t.Fatalf("filter = %d %s", rec.Code, rec.Body.String()) + } + if rec := serve(t, e, http.MethodGet, target, "", nil); rec.Code != http.StatusUnauthorized { + t.Fatalf("unauthenticated filter = %d", rec.Code) + } + } + logged := logs.String() + if !strings.Contains(logged, "uri="+scimUsersPath) { + t.Fatalf("request was not logged: %s", logged) + } + for _, secret := range []string{"person", "example.com", "opaque-subject-value", "filter"} { + if strings.Contains(logged, secret) { + t.Fatalf("%q reached the log: %s", secret, logged) + } + } +} + +func TestLoggedRequestURI(t *testing.T) { + for _, tc := range []struct{ path, uri, want string }{ + {"/api/auth/link/verify", "/api/auth/link/verify?token=secret&x=1", "/api/auth/link/verify?token=REDACTED&x=1"}, + {"/api/traces", "/api/traces?limit=5", "/api/traces?limit=5"}, + {scimUsersPath, scimUsersPath + "?filter=abc&token=def", scimUsersPath}, + } { + if got := loggedRequestURI(tc.path, tc.uri); got != tc.want { + t.Errorf("loggedRequestURI(%q) = %q, want %q", tc.uri, got, tc.want) + } + } +} + +// issueMCPGrant returns credentials for the signed-in user: request headers +// carrying its access token and the form that refreshes it. +func issueMCPGrant(t *testing.T, e *echo.Echo, cookie *http.Cookie) (map[string]string, string) { + t.Helper() + client := registerOAuthClient(t, e) + verifier, challenge := pkcePair() + code := approveAndGetCode(t, e, authorizeParams(client.ClientID, mcpReadScope, challenge), cookie) + tokens := decodeTokens(t, exchangeCode(t, e, client.ClientID, code, testRedirectURI, verifier)) + form := url.Values{"grant_type": {"refresh_token"}, "client_id": {client.ClientID}, "refresh_token": {tokens["refresh_token"].(string)}}.Encode() + return map[string]string{"Authorization": "Bearer " + tokens["access_token"].(string)}, form +} + +func assertMCPRejected(t *testing.T, e *echo.Echo, stage string, bearer map[string]string, form string) { + t.Helper() + if rec := serve(t, e, http.MethodPost, "/mcp", testReadMCPCall, bearer); rec.Code != http.StatusUnauthorized { + t.Fatalf("%s: MCP access token = %d %s, want 401", stage, rec.Code, rec.Body.String()) + } + rec := serve(t, e, http.MethodPost, "/oauth/token", form, formHeaders) + if rec.Code != http.StatusBadRequest || !strings.Contains(rec.Body.String(), "invalid_grant") { + t.Fatalf("%s: refresh = %d %s, want invalid_grant", stage, rec.Code, rec.Body.String()) + } +} + +func (s *scimServer) count(t *testing.T, query string, args ...any) int { + t.Helper() + var count int + if err := s.db.DB.QueryRow(query, args...).Scan(&count); err != nil { + t.Fatalf("%s: %v", query, err) + } + return count +} + +// signedInMember creates an administrator's account and a member with a live +// browser session. +func (s *scimServer) signedInMember(t *testing.T) (auth.User, *http.Cookie, auth.User, *http.Cookie) { + t.Helper() + ownerResource := s.seed(t, "owner", "owner@example.com", "admin") + memberResource := s.seed(t, "member", "member@example.com", "admin") + owner, err := s.users.GetByID(ownerResource.ID) + if err != nil { + t.Fatalf("GetByID: %v", err) + } + member, err := s.users.GetByID(memberResource.ID) + if err != nil { + t.Fatalf("GetByID: %v", err) + } + return owner, oauthCookieForUser(t, s.e, owner), member, oauthCookieForUser(t, s.e, member) +} + +func TestBrowserSuspensionRevokesMCPTokens(t *testing.T) { + s := newSCIMServer(t) + RegisterUserRoutes(s.e, s.users, auth.SMTPConfig{}, scimTestConfig()) + _, ownerCookie, member, memberCookie := s.signedInMember(t) + probed, probedForm := issueMCPGrant(t, s.e, memberCookie) + unused, unusedForm := issueMCPGrant(t, s.e, memberCookie) + + setStatus := func(status string) { + t.Helper() + headers := map[string]string{"Content-Type": "application/json", "Fanout-Request": "1"} + rec := serve(t, s.e, http.MethodPatch, "/api/users/"+member.ID+"/status", `{"status":"`+status+`"}`, headers, ownerCookie) + if rec.Code != http.StatusOK { + t.Fatalf("set status %s = %d %s", status, rec.Code, rec.Body.String()) + } + } + setStatus("suspended") + assertMCPRejected(t, s.e, "after suspension", probed, probedForm) + if got := s.count(t, `SELECT COUNT(*) FROM oauth_tokens WHERE user_id = ? AND revoked_at IS NULL`, member.ID); got != 0 { + t.Fatalf("live tokens after suspension = %d, want 0", got) + } + setStatus("active") + assertMCPRejected(t, s.e, "after reactivation", unused, unusedForm) +} + +func TestSCIMRepeatDeactivationRemovesRemainingAccess(t *testing.T) { + s := newSCIMServer(t) + _, _, member, memberCookie := s.signedInMember(t) + bearer, form := issueMCPGrant(t, s.e, memberCookie) + client := registerOAuthClient(t, s.e) + _, challenge := pkcePair() + approveAndGetCode(t, s.e, authorizeParams(client.ClientID, mcpReadScope, challenge), memberCookie) + + // An account suspended without revocation still holds all three. + if _, err := s.db.DB.Exec(`UPDATE users SET status = 'suspended' WHERE id = ?`, member.ID); err != nil { + t.Fatalf("suspend: %v", err) + } + remaining := map[string]string{ + "sessions": `SELECT COUNT(*) FROM sessions WHERE user_id = ?`, + "tokens": `SELECT COUNT(*) FROM oauth_tokens WHERE user_id = ? AND revoked_at IS NULL`, + "codes": `SELECT COUNT(*) FROM oauth_authorization_codes WHERE user_id = ?`, + } + for name, query := range remaining { + if s.count(t, query, member.ID) == 0 { + t.Fatalf("fixture has no live %s", name) + } + } + + path := scimUsersPath + "/" + member.ID + body := scimPatchBody(`{"op":"replace","path":"active","value":false}`) + if rec := s.do(t, http.MethodPatch, path, body); rec.Code != http.StatusOK || decodeSCIMResource(t, rec).Active { + t.Fatalf("repeat deactivation = %d %s", rec.Code, rec.Body.String()) + } + for name, query := range remaining { + if got := s.count(t, query, member.ID); got != 0 { + t.Fatalf("live %s after repeat = %d, want 0", name, got) + } + } + assertMCPRejected(t, s.e, "after repeat", bearer, form) + if got := s.auditCount(t, "session.revoked", member.ID); got != 1 { + t.Fatalf("session.revoked events = %d, want 1", got) + } + + if rec := s.do(t, http.MethodPatch, path, body); rec.Code != http.StatusOK { + t.Fatalf("second repeat = %d %s", rec.Code, rec.Body.String()) + } + if got := s.auditCount(t, "session.revoked", member.ID); got != 1 { + t.Fatalf("a repeat with nothing live wrote an event: %d", got) + } +} + +// Revocation is not the only defense: these credentials are never revoked. +func TestSuspendedUserIsRejectedWithoutRevocation(t *testing.T) { + s := newSCIMServer(t) + _, _, member, memberCookie := s.signedInMember(t) + bearer, form := issueMCPGrant(t, s.e, memberCookie) + if _, err := s.db.DB.Exec(`UPDATE users SET status = 'suspended' WHERE id = ?`, member.ID); err != nil { + t.Fatalf("suspend: %v", err) + } + if got := s.count(t, `SELECT COUNT(*) FROM oauth_tokens WHERE user_id = ? AND revoked_at IS NULL`, member.ID); got == 0 { + t.Fatal("fixture expected live tokens") + } + if rec := serve(t, s.e, http.MethodGet, "/api/auth/me", "", nil, memberCookie); rec.Code != http.StatusUnauthorized { + t.Fatalf("session = %d, want 401", rec.Code) + } + assertMCPRejected(t, s.e, "suspended without revocation", bearer, form) +} + func TestSCIMRoutesAbsentWithoutToken(t *testing.T) { cfg := scimTestConfig() cfg.SCIMToken = "" diff --git a/internal/auth/oauth_store_test.go b/internal/auth/oauth_store_test.go index ec64f7dbf..63de5c4d2 100644 --- a/internal/auth/oauth_store_test.go +++ b/internal/auth/oauth_store_test.go @@ -327,8 +327,9 @@ func TestOAuthStoreRejectsWrongAudienceAndSuspendedRefresh(t *testing.T) { if _, err := store.VerifyAccessToken(t.Context(), pair.AccessToken, "https://other.example/mcp"); !errors.Is(err, ErrInvalidOAuthToken) { t.Fatalf("wrong audience = %v, want invalid token", err) } - status := UserStatusSuspended - if _, err := users.UpdateWithAudit(user.ID, nil, nil, nil, &status, AuditEvent{EventType: "user.updated", Outcome: "success"}); err != nil { + // Suspend directly, leaving the token unrevoked, so this exercises the + // status check at refresh rather than the revocation done at suspension. + if _, err := sqlite.DB.Exec(`UPDATE users SET status = 'suspended' WHERE id = ?`, user.ID); err != nil { t.Fatalf("suspend user: %v", err) } if _, err := store.RotateRefreshToken(t.Context(), client.ClientID, pair.RefreshToken, resource, ""); !errors.Is(err, ErrInvalidOAuthGrant) { diff --git a/internal/auth/provisioning.go b/internal/auth/provisioning.go index c1c270344..2c6a160d5 100644 --- a/internal/auth/provisioning.go +++ b/internal/auth/provisioning.go @@ -149,14 +149,15 @@ type UserChange struct { // UpdateProvisioned applies a directory update in one write transaction, // including the last-active-administrator check. A change to the current state // is reported with changed false and writes nothing, so it is safe to repeat. -// Suspending also revokes the user's OAuth tokens, which a later reactivation -// does not restore. The identity link is never touched. +// The exception is repeating a suspension while a session or OAuth credential +// is still live: those are removed and audited. The identity link is never +// touched. func (s *UserStore) UpdateProvisioned(id string, change UserChange, source AuditEvent) (User, bool, error) { event := source event.Outcome = "success" return s.applyUpdate(id, change.Email, change.DisplayName, change.Role, change.Status, &event, userUpdateOptions{ - skipUnchanged: true, - revokeOAuthOnSuspend: true, + skipUnchanged: true, + convergeSuspended: true, describe: func(before, after User, event *AuditEvent) { event.EventType, event.Metadata = describeProvisionedUpdate(before, after, source.Metadata) }, @@ -186,6 +187,10 @@ func describeProvisionedUpdate(before, after User, base map[string]any) (AuditEv eventType := AuditEventType("user.updated") switch { + case len(changed) == 0: + // Only a repeated suspension that found live access gets here. + eventType = "session.revoked" + fields["reason"] = "repeated_suspension" case before.Status == UserStatusActive && after.Status != UserStatusActive: eventType = "user.suspended" case before.Status != UserStatusActive && after.Status == UserStatusActive: diff --git a/internal/auth/provisioning_test.go b/internal/auth/provisioning_test.go index 3951fa22a..dfa112a5b 100644 --- a/internal/auth/provisioning_test.go +++ b/internal/auth/provisioning_test.go @@ -347,3 +347,25 @@ func TestUpdateProvisionedSuspensionRevokesOAuthAndKeepsIdentity(t *testing.T) { t.Fatalf("live tokens after reactivation = %d, want 0", got) } } + +func TestAdministratorSuspensionRevokesOAuth(t *testing.T) { + db := fileSQLite(t) + users := NewUserStore(db.DB) + user, err := users.CreateWithAudit("member@example.com", "", RoleViewer, AuditEvent{EventType: "user.created", Outcome: "success"}) + if err != nil { + t.Fatalf("create: %v", err) + } + if _, err := db.DB.Exec(`INSERT INTO oauth_clients (client_id, client_name, redirect_uris_json, grant_types_json, response_types_json, token_endpoint_auth_method, created_at) VALUES ('client-1', 'Client', '[]', '[]', '[]', 'none', 1)`); err != nil { + t.Fatalf("insert client: %v", err) + } + if _, err := db.DB.Exec(`INSERT INTO oauth_tokens (token_hash, kind, client_id, user_id, scope, resource, expires_at, created_at, family_id) VALUES ('hash-1', 'access', 'client-1', ?, 's', 'res', 9999999999, 1, 'family-1')`, user.ID); err != nil { + t.Fatalf("insert token: %v", err) + } + status := UserStatusSuspended + if _, err := users.UpdateWithAudit(user.ID, nil, nil, nil, &status, AuditEvent{EventType: "user.suspended", Outcome: "success"}); err != nil { + t.Fatalf("suspend: %v", err) + } + if got := countRows(t, db, `SELECT COUNT(*) FROM oauth_tokens WHERE user_id = ? AND revoked_at IS NULL`, user.ID); got != 0 { + t.Fatalf("live tokens = %d, want 0", got) + } +} diff --git a/internal/auth/user_store.go b/internal/auth/user_store.go index 64408ba49..deec6d614 100644 --- a/internal/auth/user_store.go +++ b/internal/auth/user_store.go @@ -203,10 +203,9 @@ type userUpdateOptions struct { // session or token revocation and no audit event, so a provisioner can // resend the same state. skipUnchanged bool - // revokeOAuthOnSuspend revokes the user's OAuth tokens and authorization - // codes when the account leaves the active state, so a later reactivation - // cannot bring them back. - revokeOAuthOnSuspend bool + // convergeSuspended makes a repeated suspension of an already-suspended + // account remove any browser session or OAuth credential still live. + convergeSuspended bool // describe fills in the audit event type and metadata, which depend on the // row read inside the transaction. describe func(before, after User, event *AuditEvent) @@ -260,9 +259,6 @@ func (s *UserStore) applyUpdate(id string, email, displayName *string, role *Rol } existing.Status = *status } - if opts.skipUnchanged && existing.Email == before.Email && existing.DisplayName == before.DisplayName && existing.Role == before.Role && existing.Status == before.Status { - return before, false, nil - } if row.Role == "admin" && row.Status == string(UserStatusActive) && (existing.Status != UserStatusActive || existing.Role != "admin") { admins, err := q.CountActiveAdmins(ctx) if err != nil { @@ -273,6 +269,20 @@ func (s *UserStore) applyUpdate(id string, email, displayName *string, role *Rol } } + // Access ends on every transition out of active, so a later reactivation + // cannot bring old credentials back. + removedAccess := int64(0) + repeatedSuspension := opts.convergeSuspended && status != nil && before.Status != UserStatusActive + if existing.Status != UserStatusActive && (before.Status == UserStatusActive || repeatedSuspension) { + if removedAccess, err = revokeUserAccess(ctx, conn, id); err != nil { + return User{}, false, err + } + } + unchanged := existing.Email == before.Email && existing.DisplayName == before.DisplayName && existing.Role == before.Role && existing.Status == before.Status + if opts.skipUnchanged && unchanged && removedAccess == 0 { + return before, false, nil + } + now := userTimestamp(time.Now()) u, err := q.UpdateUser(ctx, generated.UpdateUserParams{ Email: existing.Email, @@ -289,7 +299,7 @@ func (s *UserStore) applyUpdate(id string, email, displayName *string, role *Rol return User{}, false, fmt.Errorf("auth: update user: %w", err) } securityChanged := before.Email != existing.Email || before.Role != existing.Role || before.Status != existing.Status - if securityChanged { + if securityChanged || removedAccess > 0 { if err := q.IncrementUserAuthVersion(ctx, generated.IncrementUserAuthVersionParams{UpdatedAt: now, ID: id}); err != nil { return User{}, false, fmt.Errorf("auth: increment auth version: %w", err) } @@ -301,11 +311,6 @@ func (s *UserStore) applyUpdate(id string, email, displayName *string, role *Rol return User{}, false, fmt.Errorf("auth: reload user after revocation: %w", err) } } - if opts.revokeOAuthOnSuspend && before.Status == UserStatusActive && existing.Status != UserStatusActive { - if err := revokeUserOAuth(ctx, conn, id); err != nil { - return User{}, false, err - } - } if event != nil { if opts.describe != nil { opts.describe(before, existing, event) @@ -451,7 +456,7 @@ func (s *UserStore) revokeAllSessions(id string, event *AuditEvent) error { if _, err := conn.ExecContext(ctx, `DELETE FROM sessions WHERE user_id = ?`, id); err != nil { return fmt.Errorf("auth: delete user sessions: %w", err) } - if err := revokeUserOAuth(ctx, conn, id); err != nil { + if _, err := revokeUserOAuth(ctx, conn, id); err != nil { return err } if event != nil { @@ -468,14 +473,42 @@ func (s *UserStore) revokeAllSessions(id string, event *AuditEvent) error { return nil } -func revokeUserOAuth(ctx context.Context, conn *sql.Conn, id string) error { - if _, err := conn.ExecContext(ctx, `UPDATE oauth_tokens SET revoked_at = COALESCE(revoked_at, ?) WHERE user_id = ?`, time.Now().UTC().Unix(), id); err != nil { - return fmt.Errorf("auth: revoke user OAuth tokens: %w", err) +// revokeUserAccess ends every browser session and OAuth credential of a user +// and reports how many were still live. +func revokeUserAccess(ctx context.Context, conn *sql.Conn, id string) (int64, error) { + result, err := conn.ExecContext(ctx, `DELETE FROM sessions WHERE user_id = ?`, id) + if err != nil { + return 0, fmt.Errorf("auth: revoke user sessions: %w", err) + } + sessions, err := result.RowsAffected() + if err != nil { + return 0, fmt.Errorf("auth: count revoked sessions: %w", err) + } + credentials, err := revokeUserOAuth(ctx, conn, id) + if err != nil { + return 0, err + } + return sessions + credentials, nil +} + +func revokeUserOAuth(ctx context.Context, conn *sql.Conn, id string) (int64, error) { + tokens, err := conn.ExecContext(ctx, `UPDATE oauth_tokens SET revoked_at = ? WHERE user_id = ? AND revoked_at IS NULL`, time.Now().UTC().Unix(), id) + if err != nil { + return 0, fmt.Errorf("auth: revoke user OAuth tokens: %w", err) } - if _, err := conn.ExecContext(ctx, `DELETE FROM oauth_authorization_codes WHERE user_id = ?`, id); err != nil { - return fmt.Errorf("auth: delete user OAuth authorization codes: %w", err) + revoked, err := tokens.RowsAffected() + if err != nil { + return 0, fmt.Errorf("auth: count revoked OAuth tokens: %w", err) } - return nil + codes, err := conn.ExecContext(ctx, `DELETE FROM oauth_authorization_codes WHERE user_id = ?`, id) + if err != nil { + return 0, fmt.Errorf("auth: delete user OAuth authorization codes: %w", err) + } + deleted, err := codes.RowsAffected() + if err != nil { + return 0, fmt.Errorf("auth: count deleted OAuth authorization codes: %w", err) + } + return revoked + deleted, nil } // CreateFirstAdminWithAudit atomically creates the first admin user. diff --git a/site/src/content/docs/docs/concepts/authentication.mdx b/site/src/content/docs/docs/concepts/authentication.mdx index 425ffa746..8c281ce4c 100644 --- a/site/src/content/docs/docs/concepts/authentication.mdx +++ b/site/src/content/docs/docs/concepts/authentication.mdx @@ -86,8 +86,8 @@ roles with `PATCH /api/users/{id}/role` and `{"role":"viewer"}`. Suspend with `PATCH /api/users/{id}/status` and `{"status":"suspended"}`; restore with `{"status":"active"}`. Unknown fields and invalid statuses return `400`. Email, role and status changes revoke browser sessions. Suspension blocks local -and OIDC sign-in and OAuth token use. Reactivation does not restore revoked -sessions. The last active administrator cannot be demoted, suspended or deleted. +and OIDC sign-in and revokes the user's OAuth tokens. Reactivation restores +neither sessions nor tokens. The last active administrator cannot be demoted, suspended or deleted. `GET /api/users` returns a `users` array. `DELETE /api/users/{id}` removes an account and cascades to its sessions, OAuth grants and owned dashboards. Use