Feature: Auth Manager

[RyanTheRobothead]

• Create madsci_auth_manager and a corresponding AuthClient
• The Auth Manager should add support for:
  • Users: an individual user of the system
  • Projects: allows for shared ownership of different system objects by different users
• Should support local users
• Should optionally support authentication via globus and orcid (OAuth/OpenID?)
• Should support gating access/usage of various objects via ownership_info, validated using AuthClient
• Should support token-based auth
• Need to add support for HTTPS to prevent man-in-the-middle attacks.

[Dozgulbas]

@LuckierDodge I believe we want to implement ORCID authentication with this?

[RyanTheRobothead]

Seems like it would be a good first Oauth provider, yeah

[RyanTheRobothead]

This article is a little old, but I think we can take away some useful design insights from it: https://web.archive.org/web/20250914173553/http://habitatchronicles.com/2017/05/what-are-capabilities/

[RyanTheRobothead]

Research Update & OpenSpec Proposal

We've started fleshing this out and pushed a foundational OpenSpec change:

• Branch: auth_manager_foundation
• Change directory: openspec/changes/auth-manager-foundation/

Why now

This is becoming a hard dependency for several other initiatives — layered location ownership (#210), the SiLA2 migration's node trust model (#293/#294), and any future federated/multi-tenant lab work all need an authoritative identity & ownership system underneath them.

Current state of MADSci (from research)

Aspect	Status	Notes
Identity types	Partial	OwnershipInfo, UserInfo, ProjectInfo exist in madsci.common.types.auth_types but are pure-context metadata
Authentication	None	No JWT, API key, bearer token, or credential checks on any FastAPI endpoint
Authorization	None	No permission/ACL system; NodeCapabilities is descriptive metadata only
Inter-service auth	None	httpx clients send no auth headers; no node registration handshake
Ownership propagation	In-process only	ownership_context() uses contextvars; never crosses HTTP boundaries
Encryption-in-transit	Optional	HTTPS supported in URLs but not enforced; no docs/templates for TLS termination

Design principles (build, don't roll)

Per the issue's guidance about not rolling our own crypto, we're standing on battle-tested libraries and standards:

• JWT (RS256) access tokens via Authlib — stateless verification across services, asymmetric signing so consumers never hold a forging secret, JWKS for key rotation
• Argon2id via argon2-cffi for password hashing (OWASP-recommended)
• OAuth 2.0 client-credentials grant for service-to-service identity (managers ↔ managers, nodes ↔ managers)
• PostgreSQL via SQLModel for relational identity data (matches Resource Manager pattern; reuses SQLAlchemyHandler so tests can run on in-memory SQLite)
• OIDC via Authlib for the eventual Globus/ORCID federation (designed-for, not implemented in this foundation)

Scope of the foundation change

In scope:

• madsci_auth_manager service (port 8007) — users, projects, service accounts, node identities, roles/permissions, audit log
• Token endpoints (password, refresh, client_credentials grants), JWKS, introspection, revocation, key rotation
• AuthClient in madsci_client with JWKS caching + auto-refresh + ambient propagation
• Opt-in AuthMiddleware on AbstractManagerBase that binds validated JWT claims into OwnershipInfo
• RBAC with project-scoped grants and a @requires(permission=..., project_from=...) decorator
• Bootstrap CLI (madsci auth bootstrap|user|project|manager|node|credentials|keys)
• Default-off rollout: auth_enabled=False initially, two-stage opt-in (auth_required=False migration mode → auth_required=True)

Deferred to follow-on changes (called out so reviewers know what's coming):

• Globus + ORCID OIDC federation
• mTLS for node→manager trust (coordinate with SiLA2 work)
• UI / dashboard login flow
• Comprehensive @requires rollout across every existing manager endpoint
• Multi-lab / federated Auth Manager topology

Phased plan

Phase	Scope	Tracking
0	Design + OpenSpec proposal	✅ This proposal
1	Auth Manager skeleton, local users, JWT issuance	This proposal
2	AuthClient + middleware + ambient propagation	This proposal
3	RBAC + @requires mechanism + ownership-claim binding	This proposal
4	Service-account + node-identity registration	This proposal
5	Globus / ORCID OIDC federation	Follow-on
6	mTLS for nodes (coord. with SiLA2)	Follow-on
7	HTTPS hardening guides + per-manager rollout	Follow-on

Open questions in the design

A few decisions still need stakeholder input — captured in design.md § Open Questions:

1. Token aud scoping — single aud=lab_id or per-service array?
2. Node enrollment UX — pre-provisioned by operator, or self-enrollment with a bootstrap token?
3. Backwards-compat for caller-asserted OwnershipInfo — keep it (with deprecation warning) until auth_required=False is removed?
4. Interaction with enable_registry_resolution — is the registry orthogonal to auth?
5. lab_id as the security boundary for iss/aud — confirm before locking the claim schema

Comments / pushback welcome. Once we converge on the open questions, we'll move into implementation via /opsx:apply.

[RyanTheRobothead]

Progress Update — Foundation Proposal Locked

The auth-manager-foundation OpenSpec change has converged through a review round and is ready for implementation.

What changed since the initial post

All five Phase-0 design questions resolved (Decisions 8–12 in design.md):

#	Decision	Choice
8	Token aud scoping	Single aud = lab_id for v1; per-principal narrowing deferred to follow-on
9	Node identity issuance UX	Pre-provisioned by operator for v1; enrollment-token flow (Kubernetes/Tailscale style) deferred
10	OwnershipInfo back-compat	Accept caller-asserted with sampled deprecation warning when auth disabled; removal coupled to the same release that removes auth_required=False
11	Registry interaction	Fully orthogonal in v1; identity registry stays unchanged
12	Tenancy boundary	Lab-scoped Auth Manager (1:1 with Lab Manager); lab_id is the security boundary; cross-lab user identity deferred to upstream-IdP follow-on (Globus/ORCID)

Review pass incorporated (4 significant + 7 minor + 2 nit points):

Significant fixes pinned into the spec:

• jti deny-list distribution mechanism: poll-based GET /deny-list with ETag/If-None-Match, default 30s interval, revocation SLA bounded by poll interval + clock skew
• Persisted deny-list backed by a revoked_access_tokens table — revoked tokens stay revoked across Auth Manager restart
• Local audit-log fallback at consuming managers (drain on Auth Manager recovery, bounded with rotation + warning so loss is loud rather than silent)
• /token endpoint rate-limiting via existing RateLimitMiddleware + unsupported_grant_type 400 per RFC 6749
• Tightened body-vs-claims OwnershipInfo precedence: principal-bound claim fields never fall back to body; operational identifiers (experiment/workflow/step) are still body-supplied
• Dedicated manager_id claim for service-account tokens (preserving canonical OAuth sub semantics)
• Explicit OwnershipInfo.from_jwt_claims() field-mapping spec

Operator-doc additions: 0600 file mode for .madsci/secrets/, .gitignore treatment, X-Forwarded-For handling for accurate audit source IPs, audit retention/PII guidance, alerting on the audit-log rotation warning event.

Final shape of the foundation

Capability	Spec
auth-identity-model	User, Project, ServiceAccount, NodeIdentity, Role/Permission, audit log + local fallback
auth-token-lifecycle	RS256 JWT with iss=lab_auth_url, aud=lab_id, sub canonical, manager_id/node_id/user_id operational claims; password/refresh/client-credentials grants; JWKS; introspection; persisted deny-list with bounded revocation SLA; rate-limited /token
auth-manager-service	madsci_auth_manager package on port 8007, AbstractManagerBase[AuthManagerSettings], PostgreSQL via SQLAlchemyHandler, lab-scoped at bootstrap, full CLI surface
auth-client-integration	AuthClient with JWKS cache + auto-refresh + deny-list polling, ambient propagation via create_httpx_client, opt-in AuthMiddleware, @requires(permission=..., project_from=...) decorator

Branch and review state

• Branch: auth_manager_foundation (7 commits, docs-only)
• Review verdict: approved with minor revisions (all addressed); no remaining blocking items
• Open questions: zero — all five resolved into Decisions 8–12

Follow-on changes already captured (task 15.4)

These will become their own issues / OpenSpec proposals once the foundation lands:

• Globus / ORCID upstream-IdP federation (resolves cross-lab user identity)
• mTLS for nodes (coordinated with SiLA2 trust model in Project: SiLA2 Migration #293/Research: SiLA2 standards audit and node API mapping (SiLA2 Migration) #294)
• Per-manager @requires rollout across every existing endpoint
• Per-principal aud narrowing for service accounts and nodes
• Node enrollment-token flow for dynamic environments
• Optional atomic madsci registry add + madsci auth node register CLI convenience
• Deprecation timeline for auth_required=False and caller-asserted OwnershipInfo

Next step

Implementation kicks off via /opsx:apply — task list in tasks.md (15 task groups, ~85 checkboxes, ordered by dependency). Will open a draft PR once the first tasks land code.