diff --git a/.env.example b/.env.example index 2fbe451d..4429cc6a 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 f3c6552c..78e34448 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 41fd3fff..3d344cb7 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" @@ -221,7 +218,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) @@ -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) @@ -345,6 +318,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 +764,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 00000000..1c02ab60 --- /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 3915da7d..ccb6f047 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`. @@ -303,16 +304,108 @@ 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. 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 +`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 fa9f89c7..3c6342f1 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 49261a0e..bec5ebd7 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 ed1ac6c8..68b408b3 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 a0f54e85..0d485689 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 12ac456c..7aa4cfb3 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 870c9298..81801d4b 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/request_log.go b/internal/api/request_log.go new file mode 100644 index 00000000..e511e4a5 --- /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.go b/internal/api/scim.go new file mode 100644 index 00000000..d081ffc8 --- /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 00000000..fa4d8e5b --- /dev/null +++ b/internal/api/scim_test.go @@ -0,0 +1,858 @@ +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 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 = "" + 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 7fdc5b05..0cefb4d6 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 8dcb3db4..8c22eff3 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/oauth_store_test.go b/internal/auth/oauth_store_test.go index ec64f7db..63de5c4d 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 new file mode 100644 index 00000000..2c6a160d --- /dev/null +++ b/internal/auth/provisioning.go @@ -0,0 +1,213 @@ +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. +// 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, + convergeSuspended: 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 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: + 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 00000000..dfa112a5 --- /dev/null +++ b/internal/auth/provisioning_test.go @@ -0,0 +1,371 @@ +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) + } +} + +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 ffa23d5c..deec6d61 100644 --- a/internal/auth/user_store.go +++ b/internal/auth/user_store.go @@ -192,16 +192,36 @@ 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 + // 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) +} + +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 +233,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,26 +249,40 @@ 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 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 } } + // 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, @@ -260,35 +294,38 @@ 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 securityChanged || removedAccess > 0 { 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 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 +456,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 +473,44 @@ func (s *UserStore) revokeAllSessions(id string, event *AuditEvent) error { return nil } +// 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) + } + revoked, err := tokens.RowsAffected() + if err != nil { + return 0, fmt.Errorf("auth: count revoked OAuth tokens: %w", err) + } + 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. // Returns ErrSetupComplete if users already exist (race-safe). func (s *UserStore) CreateFirstAdminWithAudit(email, displayName string, event AuditEvent) (User, error) { @@ -464,11 +536,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 +569,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 bf4b84f5..67291ad0 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 efb9e1b6..102fd9eb 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 c0f12920..8c281ce4 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 @@ -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 2101702e..2589edf0 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 b8097c70..c22795bf 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.