Skip to content

Delegated sign-in and app-minted sessions - #2

Merged
astherath merged 1 commit into
mainfrom
feat/delegated-signin
Oct 20, 2026
Merged

astherath merged 1 commit into
mainfrom
feat/delegated-signin

Conversation

@astherath

Copy link
Copy Markdown
Contributor

Lets another site act as a sign-in provider for canvas-cloud, and lets a linked app mint a session for one of its users.

Endpoint

POST /v1/apps/self/users/{subject}/sessions (app key alone, optional {} body) → 201 {token: "cvs_…", user_id, expires_at}, with Cache-Control: no-store.

  • The token is an ordinary session: same create_session path, table and 30-day sliding expiry as login and OIDC.
  • Refusals:
    • X-Canvas-User → 400
    • not an app key → 401
    • no trust_email → 403 trust_email_required
    • subject not provisioned by this app → 404 unknown_subject
    • disabled user → 403 account_disabled
    • per-app GCRA limit limits.app_sessions_per_minute (default 60, env CANVAS_CLOUD_LIMITS__APP_SESSIONS_PER_MINUTE) → 429 rate_limited
  • Records an audit row (app.user.session, detail {subject}, never the token) and metrics app_sessions_created_total / app_sessions_rate_limited_total.
  • /v1/info adds app_sessions to features and app_sessions_per_minute to limits.

Config

[[delegated_sign_in]]
id = "portal"            # [a-z0-9_-], 1-32, unique, not an [[oidc]] id
name = "Team portal"     # optional, defaults to id
start_url = "https://portal.example.com/canvas-signin"  # https, or http only on loopback; no fragment, credentials or redirect_uri
  • These providers are listed after [[oidc]] in GET /v1/auth/oidc → providers and in /v1/info → auth.oidc (still an array). Each entry is {id, name, start: "/v1/auth/oidc/{id}/start", kind: "delegated", start_url}.
  • OIDC entries gain kind: "oidc". This is additive.
  • GET /v1/auth/oidc/{id}/start?redirect_uri=X for a delegated id:
    • checks that X is http(s), same origin as public_url, with no fragment or credentials; otherwise 400 redirect_uri_not_allowed;
    • then answers 302 to start_url?…&redirect_uri=X (no-store, Referrer-Policy: no-referrer, no cookie or state).
  • The delegate replies X#token=cvs_… or X#error=…, so the browser protocol is the same as OIDC. Clients (canvas-app parseProviders, /account) work unchanged because start stays server-relative.
  • canvas-cloud doctor prints one sign-in line per provider.

Docs

  • auth.md: new "Delegated sign-in" section, covering the protocol and the redirect check the delegate MUST do.
  • apps.md, configuration.md, operations.md (metrics), security.md, architecture.md.
  • OpenAPI: new route, OidcProvider.kind / start_url, AppSession.
  • CHANGELOG under Unreleased.

Tests

  • New apps/tests/sessions.rs: mint, expiry, user agent, audit; the token works as the user; every refusal; per-app rate limit.
  • New accounts/tests/delegated.rs: listing with kind; the start redirect keeps the existing query; bad redirect_uri cases.
  • End to end in canvas-cloud/tests/app.rs: listing → start → provision → mint → /v1/auth/me → logout.
  • Config unit tests for validation errors.
  • cargo fmt --check, clippy -D warnings and the full workspace test suite pass locally (268 tests). Also smoke-tested on a real server with doctor, /v1/info, start, mint and /auth/me.

- POST /v1/apps/self/users/{subject}/sessions: a trust_email linked app mints an
  ordinary cvs_ session for one of its users (201 {token, user_id, expires_at},
  Cache-Control: no-store). 404 unknown_subject, 403 account_disabled /
  trust_email_required, per-app limit limits.app_sessions_per_minute (default 60),
  audit app.user.session, metrics app_sessions_created_total /
  app_sessions_rate_limited_total. /v1/info features gain app_sessions.
- [[delegated_sign_in]] {id, name, start_url}: validated at load, listed after
  [[oidc]] in /v1/info auth.oidc and GET /v1/auth/oidc with kind "delegated";
  OIDC entries gain kind "oidc". GET /v1/auth/oidc/{id}/start checks
  redirect_uri (same origin as public_url, no fragment) and redirects to
  start_url?redirect_uri=..., so the browser protocol is the same as OIDC.
  /account renders them as buttons; doctor lists sign-in providers.
- Docs: auth.md (Delegated sign-in), apps.md, configuration.md, operations.md,
  security.md, architecture.md, OpenAPI, CHANGELOG.
@astherath
astherath merged commit 2fc5653 into main Oct 20, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant