[jbouder]

Closes #153

Summary

nebari-operator v0.2.0 (released 2026-10-21) is the first release that enforces a NebariApp's auth.groups at the gateway (nebari-operator#198, #209, #214, #215). This PR moves access.groups enforcement there and strips enforcement out of the apps-authz sidecar.

Operator

• Pin bumped from v0.1.0-alpha.20 to v0.2.0 (.nebari-operator-version, NebariOperatorContract). The dev Makefile reads the pin and now re-clones its cached nebari-operator checkout when the pin changes. The cached one was on alpha.19.
• A restricted App's NebariApp carries auth.groups (as written) with enforceAtGateway: true. forwardAccessToken is no longer set, so app pods (untrusted code) never receive the user's token.
• The sidecar runs only in Apps that can idle or run an image. A restricted App that does neither has no sidecar, and a Python task there moves from 8081 to 8080 ($PORT).
• The operator refuses access.groups entries that name no group (/, blank). nebari-operator would turn those into a deny-all policy (GroupsEmpty). Commas are now allowed, since nothing joins the list into an env var any more.
• RoutingReady now carries the NebariApp's reason, so GroupsNotResolved (a path missing in Keycloak), GroupsEmpty and GroupsClaimConflict show up on the App.
• The --keycloak-url, --keycloak-internal-url and --keycloak-realm flags are removed (only the sidecar used them), along with the chart args.

apps-authz sidecar

• The sidecar is now passthrough only: verify.go/jwks.go and the go-oidc/go-jose dependencies are gone. It proxies every request and serves /activity.
• It refuses to start if AUTHZ_GROUPS, AUTHZ_ISSUERS, AUTHZ_JWKS_URL or AUTHZ_CLIENT_ID is set. With a newer image and an older operator, a restricted App stays down instead of running open. AUTHZ_PASSTHROUGH is ignored.

Full-path group matching (API, UI, MCP)

• finance == /finance, and /finance does not admit someone who is only in /finance/analysts. apps-api (groups.py), the operator (groupPath) and the UI (groupPath) all mirror nebari-operator's groups.NormalizePath.
• apps-api matches api.adminGroups and access.managers.groups as full paths, and /auth/me reports groups as full paths. It already stripped the leading / before, so the v0.2.0 claim change was handled. This makes subgroup handling exact. It also rejects group entries that name no group.
• The UI validates the groups field and explains the rule. The MCP launch_app and review_access text say so too.

Docs: architecture (with a gateway vs sidecar table), configuration ("NebariApp fields the chart emits"), launching apps (Access control), troubleshooting, runbook (new "Group access" section), getting started, CRD/API reference, upgrading, README, AGENTS.md, the skill and the examples are all updated. upgrading.md covers:

• upgrading nebari-operator first
• the one-time re-login from the renamed access-token cookie
• the switch of the groups claim to full paths, including subgroups that were listed by bare name
• pods rolling once
• the token no longer reaching the app

NebariApp contract changes from v0.1.0-alpha.20 to v0.2.0

I diffed api/v1/nebariapp_types.go and the CRD between the two tags. Besides auth.groups enforcement, the changes are:

• auth.groups items gained minLength: 1. The pack's validation is stricter than that.
• New optional fields landingPage.iconLight/iconDark and status.serviceDiscovery.iconLight/iconDark (v0.1.0). They are additive and the pack doesn't set them.
• New AuthReady/Ready reasons: GroupsNotResolved, GroupsRequireKeycloak, GroupsClaimConflict, GroupsEnforcedByApplication, GroupsEmpty. New events: GroupsMappersRemoved, Configured.
• Behavior changes:
  • every client's groups mapper now emits full paths
  • groups mappers added by hand are deleted
  • a bare-name entry creates a top-level Keycloak group, while a path is never created
  • every app's client is reprovisioned once
• KEYCLOAK_EXTERNAL_URL must be set on nebari-operator for Envoy Gateway v1.9.1+ (v0.1.2). This is operator config; the pack doesn't need to change.

None of these changes break a field the pack emits.

Security note

The gateway is now the only group check, and the sidecar used to refuse non-members even for in-cluster traffic. The docs recommend apps.networkPolicy.enabled (ingress only from the gateway namespace). If the pack is upgraded before nebari-operator, restricted Apps are open to every signed-in user, so upgrading.md says to upgrade nebari-operator first. The operator can't detect the nebari-operator version without new CRD read RBAC, which this PR doesn't add.

How it was tested

These are local quality gates only. Nothing ran on a cluster.

• operator: go build, go vet, go test ./... -race (internal coverage 90.1%, floor 89), golangci-lint run (0 issues), envtest suite (-tags envtest, k8s 1.37.0) passes, controller-gen v0.21.0 regenerated the CRD, gen_crd_types.py was run, and check_crd_compat.py passes.
• authz: go mod tidy -diff, go vet, go build, golangci-lint run, go test -race (internal coverage 96.8%, floor 95).
• api: uv lock --check, pytest with coverage (316 passed, 91.9%), ruff check, ruff format --check, mypy.
• mcp: pytest with coverage (71 passed, 90.2%), ruff, mypy.
• ui: npm run check:ci, build, npm run size (192.1/245 kB), test:coverage (288 passed), and test:e2e (150 passed).
• docs: bun test test and bun run build.
• chart: helm lint, helm template (default and examples/nebari-values.yaml), helm-docs README regenerated.
• repo: check_doc_paths.py, check_versions.py.
• Not run locally: pip-audit / npm audit (no dependency changes beyond dropping the authz Go deps), actionlint / zizmor (no workflow changes), kubeconform and promtool.

Follow-ups (not in this PR)

• Verify on a cluster running nebari-operator v0.2.0: a group member is admitted, a non-member gets 403 from the gateway, and a public App and an idling App (including a restricted idling App and its activator page) still work. Also check the one-time re-login.
• Bump nebari-local to nebari-operator v0.2.0 and an apps-pack build with this change, and bump gitops/apps/apps-pack.yaml there.
• Audit existing Apps, access.managers.groups and api.adminGroups on live clusters for subgroups listed by bare name (query in upgrading.md).

🤖 Generated with Claude Code

[github-actions]

📄 Docs preview for feat/gateway-group-enforcement:
https://feat-gateway-group-enforceme.apps-pack.pages.dev