From 3c9f280eaa52c5c3be2989eb2801b35856e189f7 Mon Sep 17 00:00:00 2001
From: Rajat Saxena <hi@sub.rajatsaxena.dev>
Date: Sat, 14 Nov 2026 13:02:02 +0530
Subject: [PATCH] feat: add school-scoped learner saml single sign-on

Schools on a plan with the learner_sso feature (every school in oss mode)
can let learners sign in through their own SAML identity provider.

- api: SP-initiated SAML with a signed assertion, RSA-SHA256, a stable
  subject, replay protection and audited failures; connections move
  through draft, active, suspended and disabled, and a change to what a
  connection trusts sends it back to draft to be tested again
- api: email domains are verified by DNS TXT and rechecked weekly; schools
  can require SSO for their domains; turning a method off ends its sessions
- admin: login providers settings, SSO connection setup with a test
  sign-in and hints for common provider mistakes
- storefront: "Sign in with <label>" on the sign-in and checkout forms
- uses @codelitdev/platform and @codelitdev/billing 0.11.0 for domain
  verification and plan features
- docs: self-hosting SSO guide and learner sign-in notes; a project skill
  to browser-test against Keycloak
---
 .../skills/test-sso-with-keycloak/SKILL.md    |   49 +
 .../test-sso-with-keycloak/keycloak-sso.sh    |  115 +
 .github/dependabot.yml                        |   12 +
 .../app/settings/login-providers/page.tsx     |    1 +
 .../sso/[connectionId]/page.tsx               |   26 +
 apps/admin/app/settings/page.tsx              |   19 +-
 .../components/permission-denied-feedback.tsx |    9 +-
 .../settings/login-provider-settings.tsx      |  390 ++
 .../settings/recent-sign-in-dialog.tsx        |   58 +
 .../settings/sso-connection-settings.tsx      |  769 +++
 apps/admin/lib/school-api.ts                  |   74 +
 apps/admin/lib/sso.test.ts                    |  267 +
 apps/admin/lib/sso.ts                         |  316 +
 apps/api/drizzle/0000_baseline.sql            |  132 +-
 apps/api/drizzle/meta/0000_snapshot.json      | 1353 +++-
 apps/api/openapi.json                         | 6136 +++++++++++++++--
 apps/api/package.json                         |    9 +-
 apps/api/src/activity-types.ts                |    1 +
 apps/api/src/auth/authenticate.ts             |   12 +
 apps/api/src/auth/operation-policy.ts         |   27 +
 apps/api/src/auth/options.ts                  |   14 +
 apps/api/src/billing.ts                       |   12 +-
 apps/api/src/communities.ts                   |    9 +-
 apps/api/src/contacts-create.test.ts          |    7 +-
 apps/api/src/db/schema/index.ts               |    1 +
 apps/api/src/db/schema/integrations.ts        |    3 +-
 apps/api/src/db/schema/school-sso.ts          |  244 +
 apps/api/src/db/schema/schools.ts             |   34 +-
 apps/api/src/dispatch.ts                      |   45 +-
 apps/api/src/express-app.ts                   |   18 +
 apps/api/src/integration-provisioning.ts      |   75 +-
 apps/api/src/invitations.ts                   |   47 +
 apps/api/src/learner-auth.test.ts             |   38 +-
 apps/api/src/learner-session-user-id.test.ts  |   57 +
 apps/api/src/learner-sign-in.ts               |   47 +-
 apps/api/src/learner-sso-flow.test.ts         |  345 +
 apps/api/src/learner-sso-routes.ts            |  123 +
 apps/api/src/learner-sso-sign-in.ts           |  466 ++
 apps/api/src/learner-sso.test.ts              |  695 ++
 apps/api/src/learner-sso.ts                   |  387 ++
 apps/api/src/learners.ts                      |  179 +-
 apps/api/src/login-methods.test.ts            |  166 +
 apps/api/src/login-methods.ts                 |  117 +
 .../src/mcp-tools/operation-descriptions.ts   |    8 +
 apps/api/src/openapi.ts                       |    1 +
 apps/api/src/plan-features.test.ts            |  219 +
 apps/api/src/plan-features.ts                 |  227 +
 apps/api/src/school-emails.test.ts            |    1 +
 apps/api/src/schools.ts                       |    1 +
 apps/api/src/shadow-users.ts                  |  105 +
 apps/api/src/sign-in-policy.test.ts           |  366 +
 apps/api/src/sign-in-policy.ts                |  195 +
 apps/api/src/space-access.ts                  |   16 +-
 apps/api/src/spaces.ts                        |   22 +-
 apps/api/src/sso-admin-routes.ts              |  150 +
 apps/api/src/sso-admin.test.ts                |  387 ++
 apps/api/src/sso-admin.ts                     |  756 ++
 apps/api/src/sso-config.test.ts               |   40 +
 apps/api/src/sso-config.ts                    |  117 +
 apps/api/src/sso-email.ts                     |   41 +
 apps/api/src/sso-events.ts                    |   84 +
 apps/api/src/sso-jobs.test.ts                 |  127 +
 apps/api/src/sso-jobs.ts                      |  215 +
 apps/api/src/sso-protocol/certificates.ts     |   26 +
 apps/api/src/sso-protocol/dom.ts              |   33 +
 apps/api/src/sso-protocol/index.ts            |   11 +
 apps/api/src/sso-protocol/metadata.test.ts    |  134 +
 apps/api/src/sso-protocol/metadata.ts         |   95 +
 apps/api/src/sso-protocol/saml.test.ts        |  555 ++
 apps/api/src/sso-protocol/saml.ts             |  499 ++
 apps/api/src/sso-protocol/test-idp.ts         |  220 +
 apps/api/src/sso-protocol/types.ts            |   75 +
 apps/api/src/sso-protocol/url.ts              |   24 +
 apps/api/src/sso-protocol/xml.ts              |   85 +
 apps/api/src/test-billing-plan.ts             |  116 +
 apps/api/src/test-learner-auth.ts             |    6 +-
 apps/api/src/test-sso-flow.ts                 |  163 +
 apps/api/src/test-sso.ts                      |   93 +
 apps/api/src/ui-surface.test.ts               |    2 +-
 apps/api/src/worker.ts                        |   12 +
 .../schools/[schoolId]/auth/sso/route.test.ts |   82 +
 .../app/schools/[schoolId]/auth/sso/route.ts  |   52 +
 .../components/auth/external-login-button.tsx |    6 +-
 .../components/checkout-login-form.tsx        |   30 +-
 .../components/public-checkout-session.tsx    |    4 +
 .../components/public-login-block.tsx         |   44 +-
 apps/storefront/lib/learner-sign-in.ts        |   15 +
 apps/storefront/lib/login-methods.test.ts     |   60 +
 apps/storefront/lib/login-methods.ts          |   67 +
 bun.lock                                      |   53 +-
 docs/user-deletion.md                         |    9 +
 docs/wip/rewrite-sso-implementation.md        |  706 ++
 frontlit/docs/learners/sign-in.md             |    6 +-
 frontlit/docs/self-hosting/configuration.md   |    2 +-
 frontlit/docs/self-hosting/index.md           |    6 +
 frontlit/docs/self-hosting/single-sign-on.md  |  186 +
 package.json                                  |    4 +-
 packages/api-contract/src/index.ts            |  306 +-
 packages/api-contract/src/mcp-parity.ts       |  132 +
 99 files changed, 19136 insertions(+), 765 deletions(-)
 create mode 100644 .claude/skills/test-sso-with-keycloak/SKILL.md
 create mode 100755 .claude/skills/test-sso-with-keycloak/keycloak-sso.sh
 create mode 100644 apps/admin/app/settings/login-providers/page.tsx
 create mode 100644 apps/admin/app/settings/login-providers/sso/[connectionId]/page.tsx
 create mode 100644 apps/admin/components/settings/login-provider-settings.tsx
 create mode 100644 apps/admin/components/settings/recent-sign-in-dialog.tsx
 create mode 100644 apps/admin/components/settings/sso-connection-settings.tsx
 create mode 100644 apps/admin/lib/school-api.ts
 create mode 100644 apps/admin/lib/sso.test.ts
 create mode 100644 apps/admin/lib/sso.ts
 create mode 100644 apps/api/src/db/schema/school-sso.ts
 create mode 100644 apps/api/src/learner-session-user-id.test.ts
 create mode 100644 apps/api/src/learner-sso-flow.test.ts
 create mode 100644 apps/api/src/learner-sso-routes.ts
 create mode 100644 apps/api/src/learner-sso-sign-in.ts
 create mode 100644 apps/api/src/learner-sso.test.ts
 create mode 100644 apps/api/src/learner-sso.ts
 create mode 100644 apps/api/src/login-methods.test.ts
 create mode 100644 apps/api/src/login-methods.ts
 create mode 100644 apps/api/src/plan-features.test.ts
 create mode 100644 apps/api/src/plan-features.ts
 create mode 100644 apps/api/src/shadow-users.ts
 create mode 100644 apps/api/src/sign-in-policy.test.ts
 create mode 100644 apps/api/src/sign-in-policy.ts
 create mode 100644 apps/api/src/sso-admin-routes.ts
 create mode 100644 apps/api/src/sso-admin.test.ts
 create mode 100644 apps/api/src/sso-admin.ts
 create mode 100644 apps/api/src/sso-config.test.ts
 create mode 100644 apps/api/src/sso-config.ts
 create mode 100644 apps/api/src/sso-email.ts
 create mode 100644 apps/api/src/sso-events.ts
 create mode 100644 apps/api/src/sso-jobs.test.ts
 create mode 100644 apps/api/src/sso-jobs.ts
 create mode 100644 apps/api/src/sso-protocol/certificates.ts
 create mode 100644 apps/api/src/sso-protocol/dom.ts
 create mode 100644 apps/api/src/sso-protocol/index.ts
 create mode 100644 apps/api/src/sso-protocol/metadata.test.ts
 create mode 100644 apps/api/src/sso-protocol/metadata.ts
 create mode 100644 apps/api/src/sso-protocol/saml.test.ts
 create mode 100644 apps/api/src/sso-protocol/saml.ts
 create mode 100644 apps/api/src/sso-protocol/test-idp.ts
 create mode 100644 apps/api/src/sso-protocol/types.ts
 create mode 100644 apps/api/src/sso-protocol/url.ts
 create mode 100644 apps/api/src/sso-protocol/xml.ts
 create mode 100644 apps/api/src/test-billing-plan.ts
 create mode 100644 apps/api/src/test-sso-flow.ts
 create mode 100644 apps/api/src/test-sso.ts
 create mode 100644 apps/storefront/app/schools/[schoolId]/auth/sso/route.test.ts
 create mode 100644 apps/storefront/app/schools/[schoolId]/auth/sso/route.ts
 create mode 100644 apps/storefront/lib/login-methods.test.ts
 create mode 100644 apps/storefront/lib/login-methods.ts
 create mode 100644 docs/wip/rewrite-sso-implementation.md
 create mode 100644 frontlit/docs/self-hosting/single-sign-on.md

diff --git a/.claude/skills/test-sso-with-keycloak/SKILL.md b/.claude/skills/test-sso-with-keycloak/SKILL.md
new file mode 100644
index 000000000..d1fea76b2
--- /dev/null
+++ b/.claude/skills/test-sso-with-keycloak/SKILL.md
@@ -0,0 +1,49 @@
+---
+name: test-sso-with-keycloak
+description: Browser-test learner SAML single sign-on end to end against a real Keycloak IdP on the local stack. Use after any change to learner SSO (apps/api/src/sso-protocol, learner-sso-*, sso-admin, sign-in policy, the admin SSO settings or the storefront SSO button), or when asked to test SSO with a real identity provider.
+---
+
+# Test learner SSO with Keycloak
+
+Unit tests and the mock IdP in `apps/api/src/sso-protocol/test-idp.ts` sign responses with our own helpers, so they can't catch how a real IdP behaves. After changing learner SSO, also run this browser test against Keycloak. Testing against Keycloak has already found a turned-off connection that could never be turned back on, and the fact that Keycloak's default client signs only the Response (which we refuse).
+
+Everything runs through `keycloak-sso.sh` in this folder. Run it from the repository root: `.claude/skills/test-sso-with-keycloak/keycloak-sso.sh <command>`. It reads `PUBLIC_API_URL` and `DATABASE_URL` from `apps/api/.env`.
+
+## Requirements
+
+- Docker, and the local stack running: API, worker, admin and storefront, with `SEED=1` and `BILLING_MODE=oss` in `apps/api/.env`.
+- **Keycloak must be served over HTTPS with a certificate the browser trusts.** The API only accepts `https` IdP URLs, and the browser refuses self-signed certificates. By default the script serves Keycloak with `tailscale serve` (tailnet-only) on port 9443 under this machine's Tailscale name. Choose another port with `KC_TS_PORT` if 9443 is taken, and never use `tailscale funnel`. Without Tailscale, put Keycloak behind any trusted HTTPS proxy and set `KC_PUBLIC_URL`.
+- A browser tool. Use a separate (incognito) profile for the learner, so admin and learner cookies stay apart.
+
+## Run the test
+
+1. `keycloak-sso.sh up`. It prints the IdP metadata URL and the learner login, `lena` / `Lena-pass-123` (email `lena.kc@acme.test`).
+2. In the admin, sign in as the seeded owner, `owner@example.com`. The sign-in code is printed in the API log (`[CourseLit OTP]`).
+3. Open **Settings → Login providers → Single sign-on → Set up**. Paste the output of `keycloak-sso.sh metadata`, set a button label, and select **Create**. Note the connection ID (`sso_…`) in the page URL.
+   - A school can show only one SSO connection. If one exists, delete it first. The IdP entity ID can't be changed, so a Keycloak with a different hostname also needs a new connection.
+4. `keycloak-sso.sh point <connection>`.
+5. In the admin, add the domain `acme.test`. `.test` domains can't hold a real DNS record, so run `keycloak-sso.sh verify-domain <connection>`, then reload the page.
+6. Select **Test connection** and sign in at Keycloak as `lena`. The result should show the provider, a persistent subject, `lena.kc@acme.test`, "Lena Keycloak", and "On a verified domain".
+7. Select **Turn on**.
+8. As the learner, open the school's storefront `/login`, for example `http://school-a.localhost:<storefront port>/login`. Select **Sign in with** followed by the label, sign in at Keycloak, and expect to land on `/dashboard`. `/api/v1/learner/me` should return `lena.kc@acme.test`.
+
+## Checks worth repeating
+
+- Signing in again reuses the same identity: still one row in `school_sso_identities` and one school account.
+- The learner's `school_sessions` row has `sso_connection_id` set. No Better Auth `session` row exists for the shadow user, whose email is `sso-…@users.invalid`.
+- **Require SSO for these domains**: an email code for `someone@acme.test` is refused on the storefront, while other domains still work.
+- **Turn off** ends the learner's session at once (`/learner/me` returns 401).
+- Changing the subject attribute, sign-in URL or certificates on a turned-off connection makes it **Draft**, so it can be tested and turned on again.
+- `keycloak-sso.sh signing response-only`, then **Test connection**: it fails with `signature_invalid` and the hint about signing the assertion. Restore with `keycloak-sso.sh signing assertion`.
+- Saving SSO settings with an old admin sign-in asks the owner to sign in again.
+
+## Gotchas
+
+- Admin writes need a recent sign-in. If the sign-in dialog appears, sign in again and repeat the change.
+- `psql -c "a; b"` runs as one transaction: if one statement fails, the earlier updates roll back.
+- Keycloak's session sends `SessionNotOnOrAfter` (10 hours by default), so SSO sessions end sooner than the 7-day default. That's expected.
+- Deleting a connection keeps its learners. Their shadow users stay until they sign in another way.
+
+## Clean up
+
+Always run `keycloak-sso.sh down` when you finish. It removes the Keycloak container and the `tailscale serve` port, which is a change to the machine's Tailscale config. Close the browser tabs you opened.
diff --git a/.claude/skills/test-sso-with-keycloak/keycloak-sso.sh b/.claude/skills/test-sso-with-keycloak/keycloak-sso.sh
new file mode 100755
index 000000000..1b7bb1416
--- /dev/null
+++ b/.claude/skills/test-sso-with-keycloak/keycloak-sso.sh
@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# Local Keycloak SAML IdP for browser-testing learner SSO.
+#
+#   keycloak-sso.sh up                    start Keycloak with realm "acme" and learner "lena"
+#   keycloak-sso.sh point <connection>    point the Keycloak client at a CourseLit connection
+#   keycloak-sso.sh verify-domain <connection> [domain]
+#                                         mark a domain verified (default acme.test; no real DNS)
+#   keycloak-sso.sh signing assertion|response-only
+#                                         what Keycloak signs (we require a signed assertion)
+#   keycloak-sso.sh metadata              print the IdP metadata XML (paste it into the admin)
+#   keycloak-sso.sh down                  remove Keycloak and the HTTPS proxy
+#
+# Settings (environment):
+#   KC_PUBLIC_URL  HTTPS origin the browser uses for Keycloak. Default: this
+#                  machine's Tailscale name on port KC_TS_PORT, served with
+#                  `tailscale serve` (tailnet-only). The API only accepts https
+#                  IdP URLs, and the browser must trust the certificate.
+#   KC_TS_PORT     Tailscale serve port when KC_PUBLIC_URL is unset. Default 9443.
+#   KC_HTTP_PORT   Local port Keycloak listens on. Default 8180.
+#   API_ENV        API env file for PUBLIC_API_URL and DATABASE_URL. Default apps/api/.env.
+set -euo pipefail
+
+ROOT=$(git rev-parse --show-toplevel)
+API_ENV=${API_ENV:-$ROOT/apps/api/.env}
+CONTAINER=courselit-sso-keycloak
+KC_HTTP_PORT=${KC_HTTP_PORT:-8180}
+KC_TS_PORT=${KC_TS_PORT:-9443}
+REALM=acme
+
+env_value() { grep -E "^$1=" "$API_ENV" | tail -1 | cut -d= -f2- | tr -d '"'"'"; }
+
+public_url() {
+  if [[ -n "${KC_PUBLIC_URL:-}" ]]; then echo "${KC_PUBLIC_URL%/}"; return; fi
+  local name
+  name=$(tailscale status --self --json | bun -e 'const d=JSON.parse(await Bun.stdin.text()); console.log(d.Self.DNSName.replace(/\.$/, ""))')
+  echo "https://$name:$KC_TS_PORT"
+}
+
+kcadm() { docker exec "$CONTAINER" /opt/keycloak/bin/kcadm.sh "$@"; }
+login() { kcadm config credentials --server http://localhost:8080 --realm master --user admin --password admin >/dev/null; }
+client_uuid() { kcadm get clients -r "$REALM" --fields id,protocol | bun -e 'const c=JSON.parse(await Bun.stdin.text()).find(x=>x.protocol==="saml"); if(!c) process.exit(1); console.log(c.id)'; }
+
+sql() {
+  local url; url=$(env_value DATABASE_URL)
+  if command -v psql >/dev/null; then psql "$url" -v ON_ERROR_STOP=1 -tAc "$1"; return; fi
+  # No local psql: use the container that publishes the database port.
+  local parts; parts=$(bun -e 'const u=new URL(process.argv[1]); console.log(u.port||"5432", decodeURIComponent(u.username), u.pathname.slice(1))' "$url")
+  read -r port user db <<<"$parts"
+  docker exec "$(docker ps -q --filter "publish=$port" | head -1)" psql -U "$user" -d "$db" -v ON_ERROR_STOP=1 -tAc "$1"
+}
+
+case "${1:-}" in
+  up)
+    url=$(public_url)
+    docker rm -f "$CONTAINER" >/dev/null 2>&1 || true
+    docker run -d --name "$CONTAINER" -p "127.0.0.1:$KC_HTTP_PORT:8080" \
+      -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
+      quay.io/keycloak/keycloak:26.4 start-dev --hostname="$url" --proxy-headers=xforwarded --http-enabled=true >/dev/null
+    [[ -z "${KC_PUBLIC_URL:-}" ]] && tailscale serve --bg --https="$KC_TS_PORT" "http://127.0.0.1:$KC_HTTP_PORT" >/dev/null
+    until curl -sf "$url/realms/master" >/dev/null; do sleep 2; done
+    login
+    kcadm create realms -s realm=$REALM -s enabled=true >/dev/null
+    kcadm create users -r $REALM -s username=lena -s email=lena.kc@acme.test -s emailVerified=true \
+      -s firstName=Lena -s lastName=Keycloak -s enabled=true >/dev/null
+    kcadm set-password -r $REALM --username lena --new-password 'Lena-pass-123'
+    # Keycloak's default client signs only the Response; we require a signed assertion.
+    cid=$(kcadm create clients -r $REALM -s clientId=placeholder -s protocol=saml -s enabled=true \
+      -s frontchannelLogout=false \
+      -s 'attributes."saml.server.signature"=true' -s 'attributes."saml.assertion.signature"=true' \
+      -s 'attributes."saml.client.signature"=false' -s 'attributes."saml.signature.algorithm"=RSA_SHA256' \
+      -s 'attributes."saml_name_id_format"=persistent' -s 'attributes."saml.force.name.id.format"=true' -i)
+    for p in email firstName lastName; do
+      kcadm create "clients/$cid/protocol-mappers/models" -r $REALM -s name=$p -s protocol=saml \
+        -s protocolMapper=saml-user-property-mapper -s "config.\"user.attribute\"=$p" \
+        -s "config.\"attribute.name\"=$p" -s 'config."attribute.nameformat"=Basic' >/dev/null
+    done
+    echo "Keycloak is up: $url (admin / admin). Learner: lena / Lena-pass-123 (lena.kc@acme.test)"
+    echo "IdP metadata URL: $url/realms/$REALM/protocol/saml/descriptor"
+    ;;
+  point)
+    conn=${2:?connection public id, e.g. sso_01...}
+    api=$(env_value PUBLIC_API_URL); sp="${api%/}/learner-login/sso/$conn"
+    login; cid=$(client_uuid)
+    kcadm update "clients/$cid" -r $REALM -s "clientId=$sp/metadata" -s "redirectUris=[\"$sp/acs\"]" \
+      -s "attributes.\"saml_assertion_consumer_url_post\"=$sp/acs"
+    echo "Keycloak client now uses entity ID $sp/metadata and ACS $sp/acs"
+    ;;
+  verify-domain)
+    conn=${2:?connection public id}; domain=${3:-acme.test}
+    sql "UPDATE school_sso_domains d SET verified_at = now(), consecutive_check_failures = 0
+         FROM school_sso_connections c
+         WHERE c.id = d.connection_id AND c.public_id = '$conn' AND d.domain = '$domain'
+         RETURNING d.domain"
+    ;;
+  signing)
+    case "${2:-}" in
+      assertion) value=true ;;
+      response-only) value=false ;;
+      *) echo "usage: $0 signing assertion|response-only" >&2; exit 2 ;;
+    esac
+    login; cid=$(client_uuid)
+    kcadm update "clients/$cid" -r $REALM -s "attributes.\"saml.assertion.signature\"=$value"
+    echo "Keycloak signs: ${2}"
+    ;;
+  metadata)
+    curl -sf "$(public_url)/realms/$REALM/protocol/saml/descriptor"; echo
+    ;;
+  down)
+    [[ -z "${KC_PUBLIC_URL:-}" ]] && tailscale serve --https="$KC_TS_PORT" off >/dev/null 2>&1 || true
+    docker rm -f "$CONTAINER" >/dev/null 2>&1 || true
+    echo "Keycloak removed"
+    ;;
+  *)
+    sed -n '2,20p' "$0"; exit 2 ;;
+esac
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 7872d5f73..945788f47 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -1,6 +1,10 @@
 # Product-owned. Opens one grouped pull request when a CodeLit Platform
 # release is published; all @codelitdev packages release under one version.
 # The platform conformance workflow gates the pull request.
+#
+# The SAML libraries learner SSO signs people in with are pinned exactly and
+# have had signature-bypass vulnerabilities, so they get their own grouped
+# pull request to review and merge quickly.
 version: 2
 updates:
   - package-ecosystem: "bun"
@@ -9,7 +13,15 @@ updates:
       interval: "daily"
     allow:
       - dependency-name: "@codelitdev/*"
+      - dependency-name: "@node-saml/node-saml"
+      - dependency-name: "xml-crypto"
+      - dependency-name: "@xmldom/xmldom"
     groups:
       codelit-platform:
         patterns:
           - "@codelitdev/*"
+      saml:
+        patterns:
+          - "@node-saml/node-saml"
+          - "xml-crypto"
+          - "@xmldom/xmldom"
diff --git a/apps/admin/app/settings/login-providers/page.tsx b/apps/admin/app/settings/login-providers/page.tsx
new file mode 100644
index 000000000..bee8ff302
--- /dev/null
+++ b/apps/admin/app/settings/login-providers/page.tsx
@@ -0,0 +1 @@
+export { default } from "../page";
diff --git a/apps/admin/app/settings/login-providers/sso/[connectionId]/page.tsx b/apps/admin/app/settings/login-providers/sso/[connectionId]/page.tsx
new file mode 100644
index 000000000..1e1dcd357
--- /dev/null
+++ b/apps/admin/app/settings/login-providers/sso/[connectionId]/page.tsx
@@ -0,0 +1,26 @@
+"use client";
+
+import { useParams } from "next/navigation";
+import { Suspense } from "react";
+import { AuthGate } from "@/components/auth-gate";
+import { SsoConnectionSettings } from "@/components/settings/sso-connection-settings";
+
+/** One SSO connection of the school. */
+export default function SsoConnectionPage() {
+  const params = useParams<{ connectionId: string }>();
+  return (
+    <AuthGate>
+      <div className="page-shell">
+        <div>
+          <h1 className="text-2xl font-bold tracking-tight">Single sign-on</h1>
+          <p className="mt-1 text-sm text-muted-foreground">
+            Let learners sign in through your own identity provider.
+          </p>
+        </div>
+        <Suspense fallback={null}>
+          <SsoConnectionSettings connectionId={params.connectionId} />
+        </Suspense>
+      </div>
+    </AuthGate>
+  );
+}
diff --git a/apps/admin/app/settings/page.tsx b/apps/admin/app/settings/page.tsx
index 25b575694..9d4f0325c 100644
--- a/apps/admin/app/settings/page.tsx
+++ b/apps/admin/app/settings/page.tsx
@@ -10,6 +10,7 @@ import {
   Globe,
   Info,
   Key,
+  LogIn,
   Mail,
   Palette,
   RotateCcw,
@@ -26,6 +27,7 @@ import { AiAssistantSettings } from "@/components/settings/ai-assistant-settings
 import { ApiKeySettings } from "@/components/settings/api-key-settings";
 import { BrandingSettings } from "@/components/settings/branding-settings";
 import { EmailDeliveryNotice } from "@/components/mails/email-delivery-notice";
+import { LoginProviderSettings } from "@/components/settings/login-provider-settings";
 import { NotificationSettings } from "@/components/settings/notification-settings";
 import { TeamSettings } from "@/components/settings/team-settings";
 import { CodeInjectionSettings } from "@/components/website/code-injection-settings";
@@ -58,7 +60,7 @@ import {
 import { Textarea } from "@/components/ui/codelit/textarea";
 import currencies from "@/data/currencies.json";
 
-const GENERAL_SETTINGS_TABS = ["payment", "team", "notifications", "api-keys", "ai-assistants"] as const;
+const GENERAL_SETTINGS_TABS = ["payment", "team", "notifications", "login-providers", "api-keys", "ai-assistants"] as const;
 const MAIL_SETTINGS_TABS = ["delivery"] as const;
 const WEBSITE_SETTINGS_TABS = ["branding", "code-injection", "domain"] as const;
 type SettingsMode = "general" | "website" | "mails";
@@ -144,7 +146,7 @@ export function SettingsPage({ mode = "general" }: { mode?: SettingsMode }) {
             }
           : {
               title: "Settings",
-              description: "Manage payments, team access, notifications, and API keys for this school.",
+              description: "Manage payments, team access, notifications, login providers, and API keys for this school.",
             };
 
   function selectWebsiteTab(tab: string) {
@@ -421,6 +423,11 @@ export function SettingsPage({ mode = "general" }: { mode?: SettingsMode }) {
                       label: "Notifications",
                       icon: <Bell className="size-4" />,
                     },
+                    {
+                      value: "login-providers",
+                      label: "Login providers",
+                      icon: <LogIn className="size-4" />,
+                    },
                     // API keys belong to the school; only its owner manages them.
                     ...(isOwner
                       ? [{ value: "api-keys", label: "API keys", icon: <Key className="size-4" /> }]
@@ -734,6 +741,14 @@ export function SettingsPage({ mode = "general" }: { mode?: SettingsMode }) {
           ) : null}
           </PlatformTabsContent>
 
+          <PlatformTabsContent value="login-providers" className="w-full">
+          {mode === "general" && selectedTab === "login-providers" ? (
+            <div className="w-full pt-4">
+              <LoginProviderSettings />
+            </div>
+          ) : null}
+          </PlatformTabsContent>
+
           <PlatformTabsContent value="api-keys" className="w-full">
           {mode === "general" && selectedTab === "api-keys" && isOwner ? (
             <div className="w-full pt-4">
diff --git a/apps/admin/components/permission-denied-feedback.tsx b/apps/admin/components/permission-denied-feedback.tsx
index 810143987..d760b8f82 100644
--- a/apps/admin/components/permission-denied-feedback.tsx
+++ b/apps/admin/components/permission-denied-feedback.tsx
@@ -5,6 +5,7 @@ import { toast } from "sonner";
 
 export const PERMISSION_DENIED_MESSAGE =
   "You do not have permission to perform that action.";
+const SELF_EXPLAINING_REASONS = new Set(["recent_authentication_required", "plan_required"]);
 const PERMISSION_DENIED_TOAST_ID = "courselit-permission-denied";
 
 export function showPermissionDeniedToast() {
@@ -38,7 +39,13 @@ export function PermissionDeniedFeedback() {
     ) => {
       const response = await originalFetch(input, init);
       if (response.status === 403 && isCourseLitAdminApiRequest(input)) {
-        showPermissionDeniedToast();
+        // Some 403s are not about permission; the screen explains those itself.
+        const reason = await response
+          .clone()
+          .json()
+          .then((body: { details?: { reason?: unknown } }) => body?.details?.reason)
+          .catch(() => null);
+        if (!SELF_EXPLAINING_REASONS.has(reason as string)) showPermissionDeniedToast();
       }
       return response;
     };
diff --git a/apps/admin/components/settings/login-provider-settings.tsx b/apps/admin/components/settings/login-provider-settings.tsx
new file mode 100644
index 000000000..9631a3cfd
--- /dev/null
+++ b/apps/admin/components/settings/login-provider-settings.tsx
@@ -0,0 +1,390 @@
+"use client";
+
+import { Badge } from "@codelitdev/design-system";
+import { KeyRound, Mail, ShieldCheck } from "lucide-react";
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { type ReactNode, useCallback, useEffect, useState } from "react";
+import { toast } from "sonner";
+import { CourseLitLoading } from "@/components/loading";
+import { RecentSignInDialog } from "@/components/settings/recent-sign-in-dialog";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Button } from "@/components/ui/codelit/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/codelit/dialog";
+import { Input } from "@/components/ui/codelit/input";
+import { Label } from "@/components/ui/codelit/label";
+import { Switch } from "@/components/ui/codelit/switch";
+import { Textarea } from "@/components/ui/codelit/textarea";
+import { schoolRequest, useSelectedSchool } from "@/lib/school-api";
+import {
+  type LoginMethod,
+  RECENT_AUTHENTICATION_REASON,
+  type SchoolLoginMethods,
+  SSO_STATUS_LABELS,
+  type SsoConnection,
+  errorReason,
+  methodsAfterToggle,
+  primarySsoConnection,
+  ssoErrorMessage,
+  ssoStatusKind,
+  wouldLeaveNoMethod,
+} from "@/lib/sso";
+
+const METHOD_LABELS: Record<LoginMethod, string> = { email: "Email codes", google: "Google" };
+
+function MethodRow({
+  icon,
+  title,
+  description,
+  control,
+}: {
+  icon: ReactNode;
+  title: string;
+  description: ReactNode;
+  control: ReactNode;
+}) {
+  return (
+    <div className="flex items-start justify-between gap-4 p-4">
+      <div className="flex min-w-0 items-start gap-3">
+        <div className="mt-0.5 text-muted-foreground">{icon}</div>
+        <div className="min-w-0 space-y-1">
+          <p className="text-sm font-medium leading-none">{title}</p>
+          <div className="text-sm text-muted-foreground">{description}</div>
+        </div>
+      </div>
+      <div className="flex shrink-0 items-center gap-2">{control}</div>
+    </div>
+  );
+}
+
+function ssoBadge(connection: SsoConnection | null) {
+  const kind = ssoStatusKind(connection);
+  const variant =
+    kind === "active" ? "success" : kind === "suspended" ? "warning" : kind === "draft" ? "neutral" : "outline";
+  return <Badge variant={variant}>{SSO_STATUS_LABELS[kind]}</Badge>;
+}
+
+/** Settings → Login providers: how learners can sign in to this school's website. */
+export function LoginProviderSettings() {
+  const router = useRouter();
+  const { loading: schoolLoading, schoolId, isOwner } = useSelectedSchool();
+  const [methods, setMethods] = useState<SchoolLoginMethods | null>(null);
+  const [connections, setConnections] = useState<SsoConnection[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [saving, setSaving] = useState(false);
+  const [confirmOff, setConfirmOff] = useState<LoginMethod | null>(null);
+  const [createOpen, setCreateOpen] = useState(false);
+  const [reauth, setReauth] = useState(false);
+
+  const load = useCallback(async () => {
+    if (!schoolId) return;
+    setError(null);
+    try {
+      const [loginMethods, sso] = await Promise.all([
+        schoolRequest<SchoolLoginMethods>(schoolId, "/api/v1/school/login-methods"),
+        schoolRequest<{ items: SsoConnection[] }>(schoolId, "/api/v1/sso/connections"),
+      ]);
+      if (!loginMethods.ok || !loginMethods.body) throw new Error("Unable to load sign-in methods.");
+      setMethods(loginMethods.body);
+      setConnections(sso.ok ? (sso.body?.items ?? []) : []);
+    } catch (caught) {
+      setError(caught instanceof Error ? caught.message : "Unable to load sign-in methods.");
+    } finally {
+      setLoading(false);
+    }
+  }, [schoolId]);
+
+  useEffect(() => {
+    if (schoolId) void load();
+    else if (!schoolLoading) setLoading(false);
+  }, [schoolId, schoolLoading, load]);
+
+  async function saveMethods(next: LoginMethod[]) {
+    if (!schoolId || saving) return;
+    setSaving(true);
+    try {
+      const result = await schoolRequest<SchoolLoginMethods>(schoolId, "/api/v1/school/login-methods", {
+        method: "PATCH",
+        body: { loginMethods: next },
+      });
+      if (!result.ok || !result.body) {
+        if (result.status === 403) return;
+        throw new Error(ssoErrorMessage(result.body, "We couldn't save that. Please try again."));
+      }
+      setMethods(result.body);
+      toast.success("Sign-in methods saved.");
+    } catch (caught) {
+      toast.error(caught instanceof Error ? caught.message : "Something went wrong.");
+    } finally {
+      setSaving(false);
+      setConfirmOff(null);
+    }
+  }
+
+  function toggle(method: LoginMethod, on: boolean) {
+    if (!methods) return;
+    if (on) {
+      void saveMethods(methodsAfterToggle(methods, method, true));
+      return;
+    }
+    if (wouldLeaveNoMethod(methods, method)) {
+      toast.error("At least one sign-in method has to stay on.");
+      return;
+    }
+    setConfirmOff(method);
+  }
+
+  if (loading || schoolLoading) {
+    return <CourseLitLoading label="Loading sign-in methods…" className="justify-start" />;
+  }
+  if (error || !methods) {
+    return (
+      <Card>
+        <CardContent className="flex items-center justify-between gap-4 p-6">
+          <p className="text-sm text-destructive">{error ?? "Unable to load sign-in methods."}</p>
+          <Button variant="outline" onClick={() => void load()}>
+            Try again
+          </Button>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  const sso = primarySsoConnection(connections);
+  const emailOn = methods.loginMethods.includes("email");
+  const googleOn = methods.loginMethods.includes("google");
+
+  return (
+    <div className="space-y-4">
+      <Card>
+        <CardHeader>
+          <CardTitle>Login providers</CardTitle>
+          <CardDescription>
+            Choose how learners sign in to your school&apos;s website. At least one has to stay on.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="divide-y p-0">
+          <MethodRow
+            icon={<Mail className="size-4" />}
+            title={METHOD_LABELS.email}
+            description="Learners get a one-time code by email."
+            control={
+              <Switch
+                checked={emailOn}
+                disabled={saving}
+                aria-label="Email codes"
+                onCheckedChange={(on) => toggle("email", on)}
+              />
+            }
+          />
+          <MethodRow
+            icon={<KeyRound className="size-4" />}
+            title={METHOD_LABELS.google}
+            description={
+              methods.googleAvailable
+                ? "Learners sign in with their Google account."
+                : "Google sign-in isn't set up on this platform."
+            }
+            control={
+              <Switch
+                checked={googleOn && methods.googleAvailable}
+                disabled={saving || (!methods.googleAvailable && !googleOn)}
+                aria-label="Google"
+                onCheckedChange={(on) => toggle("google", on)}
+              />
+            }
+          />
+          <MethodRow
+            icon={<ShieldCheck className="size-4" />}
+            title="Single sign-on (SSO)"
+            description={
+              sso
+                ? `${sso.displayName}. Learners sign in through your identity provider (Okta, Entra ID, Google Workspace and similar).`
+                : "Let learners sign in through your own identity provider (Okta, Entra ID, Google Workspace and similar)."
+            }
+            control={
+              <>
+                {ssoBadge(sso)}
+                {sso ? (
+                  <Button asChild variant="outline" size="sm">
+                    <Link href={`/settings/login-providers/sso/${encodeURIComponent(sso.id)}`}>
+                      {isOwner ? "Manage" : "View"}
+                    </Link>
+                  </Button>
+                ) : isOwner ? (
+                  <Button size="sm" onClick={() => setCreateOpen(true)}>
+                    Set up
+                  </Button>
+                ) : null}
+              </>
+            }
+          />
+        </CardContent>
+      </Card>
+      {!isOwner ? (
+        <p className="text-sm text-muted-foreground">Only the school owner can set up or change SSO.</p>
+      ) : null}
+
+      <Dialog open={confirmOff !== null} onOpenChange={(open) => !open && setConfirmOff(null)}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Turn off {confirmOff ? METHOD_LABELS[confirmOff] : ""}?</DialogTitle>
+            <DialogDescription>
+              Learners who signed in this way will be signed out. They can sign in again with another method.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <Button type="button" variant="outline" onClick={() => setConfirmOff(null)}>
+              Cancel
+            </Button>
+            <Button
+              type="button"
+              disabled={saving}
+              onClick={() => confirmOff && void saveMethods(methodsAfterToggle(methods, confirmOff, false))}
+            >
+              Turn off
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      {schoolId ? (
+        <CreateConnectionDialog
+          open={createOpen}
+          onOpenChange={setCreateOpen}
+          schoolId={schoolId}
+          onNeedsSignIn={() => setReauth(true)}
+          onCreated={(connection) =>
+            router.push(`/settings/login-providers/sso/${encodeURIComponent(connection.id)}`)
+          }
+        />
+      ) : null}
+      <RecentSignInDialog open={reauth} onOpenChange={setReauth} />
+    </div>
+  );
+}
+
+function CreateConnectionDialog({
+  open,
+  onOpenChange,
+  schoolId,
+  onCreated,
+  onNeedsSignIn,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  schoolId: string;
+  onCreated: (connection: SsoConnection) => void;
+  onNeedsSignIn: () => void;
+}) {
+  const [displayName, setDisplayName] = useState("");
+  const [metadataXml, setMetadataXml] = useState("");
+  const [entityId, setEntityId] = useState("");
+  const [working, setWorking] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function create() {
+    if (working) return;
+    setWorking(true);
+    setError(null);
+    try {
+      const result = await schoolRequest<SsoConnection>(schoolId, "/api/v1/sso/connections", {
+        method: "POST",
+        body: {
+          displayName: displayName.trim(),
+          ...(metadataXml.trim() ? { metadataXml: metadataXml.trim() } : { idpEntityId: entityId.trim() }),
+        },
+      });
+      if (!result.ok || !result.body) {
+        if (errorReason(result.body) === RECENT_AUTHENTICATION_REASON) {
+          onOpenChange(false);
+          onNeedsSignIn();
+          return;
+        }
+        setError(ssoErrorMessage(result.body, "We couldn't create the connection."));
+        return;
+      }
+      onOpenChange(false);
+      onCreated(result.body);
+    } finally {
+      setWorking(false);
+    }
+  }
+
+  const ready = displayName.trim().length > 0 && (metadataXml.trim().length > 0 || entityId.trim().length > 0);
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Set up SSO</DialogTitle>
+          <DialogDescription>
+            Start with your provider&apos;s metadata. You can finish the rest on the next page.
+          </DialogDescription>
+        </DialogHeader>
+        <form
+          className="space-y-4"
+          onSubmit={(event) => {
+            event.preventDefault();
+            if (ready) void create();
+          }}
+        >
+          <div className="space-y-2">
+            <Label htmlFor="sso-create-name">Button label</Label>
+            <Input
+              id="sso-create-name"
+              value={displayName}
+              maxLength={100}
+              placeholder="Acme employees"
+              onChange={(event) => setDisplayName(event.target.value)}
+            />
+            <p className="text-xs text-muted-foreground">Learners see this on the sign-in button.</p>
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="sso-create-metadata">Provider metadata (XML)</Label>
+            <Textarea
+              id="sso-create-metadata"
+              rows={6}
+              value={metadataXml}
+              onChange={(event) => setMetadataXml(event.target.value)}
+              className="font-mono text-xs"
+            />
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="sso-create-entity">Or the provider&apos;s entity ID</Label>
+            <Input
+              id="sso-create-entity"
+              value={entityId}
+              disabled={metadataXml.trim().length > 0}
+              onChange={(event) => setEntityId(event.target.value)}
+            />
+            <p className="text-xs text-muted-foreground">
+              The entity ID can&apos;t be changed later. To use a different provider, create a new connection.
+            </p>
+          </div>
+          {error ? (
+            <p className="text-sm text-destructive" role="alert">
+              {error}
+            </p>
+          ) : null}
+          <DialogFooter>
+            <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+              Cancel
+            </Button>
+            <Button type="submit" disabled={!ready || working}>
+              Create
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/apps/admin/components/settings/recent-sign-in-dialog.tsx b/apps/admin/components/settings/recent-sign-in-dialog.tsx
new file mode 100644
index 000000000..b5b224a54
--- /dev/null
+++ b/apps/admin/components/settings/recent-sign-in-dialog.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import { useState } from "react";
+import { Button } from "@/components/ui/codelit/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/codelit/dialog";
+
+/**
+ * Shown when the API asks for a recent sign-in. Signing out and back in is the
+ * only way to refresh it, so it sends the admin to the sign-in page and back
+ * to the page they were on.
+ */
+export function RecentSignInDialog({
+  open,
+  onOpenChange,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const [working, setWorking] = useState(false);
+
+  async function signInAgain() {
+    setWorking(true);
+    try {
+      await fetch("/api/auth/sign-out", { method: "POST", credentials: "include" });
+    } finally {
+      const here = `${window.location.pathname}${window.location.search}`;
+      window.location.replace(`/login?next=${encodeURIComponent(here)}`);
+    }
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Sign in again to continue</DialogTitle>
+          <DialogDescription>
+            Changing how learners sign in needs a recent sign-in. Sign in again, then repeat the change.
+          </DialogDescription>
+        </DialogHeader>
+        <DialogFooter>
+          <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+            Cancel
+          </Button>
+          <Button type="button" disabled={working} onClick={() => void signInAgain()}>
+            Sign in again
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/apps/admin/components/settings/sso-connection-settings.tsx b/apps/admin/components/settings/sso-connection-settings.tsx
new file mode 100644
index 000000000..66c1bafc9
--- /dev/null
+++ b/apps/admin/components/settings/sso-connection-settings.tsx
@@ -0,0 +1,769 @@
+"use client";
+
+import { Badge } from "@codelitdev/design-system";
+import { AlertTriangle, Check, Copy, ExternalLink, Trash2 } from "lucide-react";
+import Link from "next/link";
+import { usePathname, useRouter, useSearchParams } from "next/navigation";
+import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
+import { toast } from "sonner";
+import { CourseLitLoading } from "@/components/loading";
+import { RecentSignInDialog } from "@/components/settings/recent-sign-in-dialog";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Button } from "@/components/ui/codelit/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/codelit/dialog";
+import { Input } from "@/components/ui/codelit/input";
+import { Label } from "@/components/ui/codelit/label";
+import { Switch } from "@/components/ui/codelit/switch";
+import { Textarea } from "@/components/ui/codelit/textarea";
+import { schoolRequest, useSelectedSchool } from "@/lib/school-api";
+import {
+  RECENT_AUTHENTICATION_REASON,
+  SSO_STATUS_LABELS,
+  SSO_TEST_QUERY_PARAM,
+  type SsoConnection,
+  type SsoDomain,
+  type SsoFormValues,
+  type SsoTestResult,
+  activationBlockers,
+  testAvailability,
+  testFailureHint,
+  buildUpdateBody,
+  changesTrust,
+  domainStatus,
+  errorReason,
+  formFromConnection,
+  parseSsoTestReturn,
+  sessionMinutesError,
+  showUpgradePrompt,
+  sortedAttributes,
+  ssoErrorMessage,
+  ssoStatusKind,
+  txtRecordDisplay,
+} from "@/lib/sso";
+
+const BASE = "/api/v1/sso/connections";
+
+function CopyField({ label, value }: { label: string; value: string }) {
+  const [copied, setCopied] = useState(false);
+  async function copy() {
+    try {
+      await navigator.clipboard.writeText(value);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    } catch {
+      toast.error("Couldn't copy. Select the value and copy it by hand.");
+    }
+  }
+  return (
+    <div className="space-y-1.5">
+      <Label>{label}</Label>
+      <div className="flex gap-2">
+        <Input readOnly value={value} className="font-mono text-xs" onFocus={(e) => e.currentTarget.select()} />
+        <Button type="button" variant="outline" className="shrink-0 px-3" aria-label={`Copy ${label}`} onClick={() => void copy()}>
+          {copied ? <Check className="size-4" /> : <Copy className="size-4" />}
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+function Notice({ children, tone = "warning" }: { children: ReactNode; tone?: "warning" | "info" }) {
+  return (
+    <div
+      className={`flex items-start gap-2 rounded-md border p-3 text-sm ${
+        tone === "warning" ? "border-amber-300 bg-amber-50 text-amber-900 dark:bg-amber-950 dark:text-amber-100" : "bg-muted"
+      }`}
+      role={tone === "warning" ? "alert" : undefined}
+    >
+      {tone === "warning" ? <AlertTriangle className="mt-0.5 size-4 shrink-0" /> : null}
+      <div>{children}</div>
+    </div>
+  );
+}
+
+function statusBadge(connection: SsoConnection) {
+  const kind = ssoStatusKind(connection);
+  const variant =
+    kind === "active" ? "success" : kind === "suspended" ? "warning" : kind === "draft" ? "neutral" : "outline";
+  return <Badge variant={variant}>{SSO_STATUS_LABELS[kind]}</Badge>;
+}
+
+function formatDate(value: string | null): string | null {
+  if (!value) return null;
+  const date = new Date(value);
+  return Number.isNaN(date.valueOf())
+    ? null
+    : new Intl.DateTimeFormat(undefined, { dateStyle: "medium", timeStyle: "short" }).format(date);
+}
+
+/** One SSO connection: what to give the provider, its settings, domains, a test, and turning it on. */
+export function SsoConnectionSettings({ connectionId }: { connectionId: string }) {
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const { loading: schoolLoading, schoolId, isOwner, billingAvailable } = useSelectedSchool();
+  const [connection, setConnection] = useState<SsoConnection | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [notFound, setNotFound] = useState(false);
+  const [form, setForm] = useState<SsoFormValues | null>(null);
+  const [saving, setSaving] = useState(false);
+  const [confirmSave, setConfirmSave] = useState(false);
+  const [busy, setBusy] = useState<string | null>(null);
+  const [reauth, setReauth] = useState(false);
+  const [confirm, setConfirm] = useState<"activate" | "disable" | "delete" | null>(null);
+  const [testResult, setTestResult] = useState<SsoTestResult | null>(null);
+  const [testMissing, setTestMissing] = useState(false);
+  const [newDomain, setNewDomain] = useState("");
+  const handledTest = useRef<string | null>(null);
+
+  const base = `${BASE}/${encodeURIComponent(connectionId)}`;
+
+  const apply = useCallback((next: SsoConnection, resetForm = true) => {
+    setConnection(next);
+    if (resetForm) setForm(formFromConnection(next));
+  }, []);
+
+  const load = useCallback(async () => {
+    if (!schoolId) return;
+    const result = await schoolRequest<SsoConnection>(schoolId, base);
+    if (result.status === 404) setNotFound(true);
+    else if (result.ok && result.body) apply(result.body);
+    else toast.error("Unable to load this connection.");
+    setLoading(false);
+  }, [schoolId, base, apply]);
+
+  useEffect(() => {
+    if (schoolId) void load();
+    else if (!schoolLoading) setLoading(false);
+  }, [schoolId, schoolLoading, load]);
+
+  // The API sends the admin back here with the test's request id.
+  const testId = parseSsoTestReturn(searchParams.toString());
+  useEffect(() => {
+    if (!schoolId || !isOwner || !testId || handledTest.current === testId) return;
+    handledTest.current = testId;
+    void (async () => {
+      const result = await schoolRequest<SsoTestResult>(
+        schoolId,
+        `${base}/test-results/${encodeURIComponent(testId)}`,
+      );
+      if (result.ok && result.body) setTestResult(result.body);
+      else setTestMissing(true);
+      const params = new URLSearchParams(searchParams.toString());
+      params.delete(SSO_TEST_QUERY_PARAM);
+      const query = params.toString();
+      router.replace(`${pathname}${query ? `?${query}` : ""}`, { scroll: false });
+      await load();
+    })();
+  }, [schoolId, isOwner, testId, base, searchParams, pathname, router, load]);
+
+  /** Runs a write; asks for a fresh sign-in when the API wants one. */
+  async function write<T>(
+    key: string,
+    path: string,
+    init: { method: string; body?: unknown },
+    failure: string,
+  ): Promise<{ ok: boolean; body: T | null }> {
+    if (!schoolId) return { ok: false, body: null };
+    setBusy(key);
+    try {
+      const result = await schoolRequest<T>(schoolId, path, init);
+      if (!result.ok) {
+        const reason = errorReason(result.body);
+        if (reason === RECENT_AUTHENTICATION_REASON) setReauth(true);
+        else if (result.status !== 403 || reason) toast.error(ssoErrorMessage(result.body, failure));
+        else toast.error("Only the school owner can change SSO.");
+      }
+      return { ok: result.ok, body: result.body };
+    } catch {
+      toast.error(failure);
+      return { ok: false, body: null };
+    } finally {
+      setBusy(null);
+    }
+  }
+
+  async function save() {
+    if (!connection || !form || saving) return;
+    const body = buildUpdateBody(connection, form);
+    if (Object.keys(body).length === 0) return;
+    setSaving(true);
+    const result = await write<SsoConnection>("save", base, { method: "PATCH", body }, "We couldn't save the changes.");
+    setSaving(false);
+    setConfirmSave(false);
+    if (result.ok && result.body) {
+      apply(result.body);
+      toast.success(
+        connection.status !== "draft" && result.body.status === "draft"
+          ? "Saved. The connection is back to draft. Test it again before turning it on."
+          : "Saved.",
+      );
+    }
+  }
+
+  async function addDomain() {
+    const domain = newDomain.trim();
+    if (!domain) return;
+    const result = await write<SsoDomain>("add-domain", `${base}/domains`, { method: "POST", body: { domain } }, "We couldn't add that domain.");
+    if (result.ok) {
+      setNewDomain("");
+      await load();
+    }
+  }
+
+  async function verifyDomain(domain: SsoDomain) {
+    const result = await write<SsoDomain>(
+      `verify:${domain.domain}`,
+      `${base}/domains/${encodeURIComponent(domain.domain)}/verify`,
+      { method: "POST", body: {} },
+      "We couldn't check the record. Please try again.",
+    );
+    if (result.ok && result.body) {
+      if (result.body.verified) toast.success(`${domain.domain} is verified.`);
+      else toast.error("We couldn't find the record yet. DNS changes can take a while to show up.");
+      await load();
+    }
+  }
+
+  async function removeDomain(domain: SsoDomain) {
+    const result = await write(
+      `remove:${domain.domain}`,
+      `${base}/domains/${encodeURIComponent(domain.domain)}`,
+      { method: "DELETE" },
+      "We couldn't remove that domain.",
+    );
+    if (result.ok) await load();
+  }
+
+  async function startTest() {
+    const url = new URL(window.location.href);
+    url.searchParams.delete(SSO_TEST_QUERY_PARAM);
+    const result = await write<{ url: string }>(
+      "test",
+      `${base}/test`,
+      { method: "POST", body: { returnUrl: url.toString() } },
+      "We couldn't start the test.",
+    );
+    if (result.ok && result.body?.url) window.location.assign(result.body.url);
+  }
+
+  async function saveEnforcement(required: boolean) {
+    const result = await write<SsoConnection>(
+      "enforcement",
+      base,
+      { method: "PATCH", body: { enforcement: required ? "required_for_domains" : "optional" } },
+      "We couldn't save that.",
+    );
+    if (result.ok && result.body) apply(result.body, false);
+  }
+
+  async function changeState(action: "activate" | "disable") {
+    const result = await write<SsoConnection>(action, `${base}/${action}`, { method: "POST", body: {} }, `We couldn't ${action} the connection.`);
+    setConfirm(null);
+    if (result.ok && result.body) {
+      apply(result.body, false);
+      toast.success(action === "activate" ? "SSO is on." : "SSO is off. Its learners were signed out.");
+    }
+  }
+
+  async function remove() {
+    const result = await write("delete", base, { method: "DELETE" }, "We couldn't delete the connection.");
+    setConfirm(null);
+    if (result.ok) {
+      toast.success("Connection deleted.");
+      router.replace("/settings/login-providers");
+    }
+  }
+
+  if (loading || schoolLoading) return <CourseLitLoading label="Loading SSO…" className="justify-start" />;
+  if (notFound || !connection || !form) {
+    return (
+      <Card>
+        <CardHeader>
+          <CardTitle>Connection not found</CardTitle>
+          <CardDescription>
+            <Link href="/settings/login-providers" className="underline">
+              Back to login providers
+            </Link>
+          </CardDescription>
+        </CardHeader>
+      </Card>
+    );
+  }
+
+  const readOnly = !isOwner;
+  const trustChange = changesTrust(connection, form);
+  const body = buildUpdateBody(connection, form);
+  const dirty = Object.keys(body).length > 0;
+  const minutesError = sessionMinutesError(form.maxSessionMinutes);
+  const warnsSignOut = connection.status !== "draft" && trustChange;
+  const blockers = activationBlockers(connection, { billingAvailable });
+  const upgrade = showUpgradePrompt(connection, billingAvailable);
+  const isActive = connection.status === "active";
+  const { canTest, note: testNote } = testAvailability(connection, { readOnly, dirty });
+  const hasVerifiedDomain = connection.domains.some((d) => d.verified);
+  const set = (patch: Partial<SsoFormValues>) => setForm({ ...form, ...patch });
+
+  return (
+    <div className="space-y-6">
+      <div className="space-y-1">
+        <Link href="/settings/login-providers" className="text-sm text-muted-foreground hover:underline">
+          Login providers
+        </Link>
+        <div className="flex items-center gap-3">
+          <h2 className="text-xl font-semibold tracking-tight">{connection.displayName}</h2>
+          {statusBadge(connection)}
+        </div>
+      </div>
+
+      {readOnly ? (
+        <Notice tone="info">Only the school owner can change SSO. You can see its settings here.</Notice>
+      ) : null}
+
+      <Card>
+        <CardHeader>
+          <CardTitle>1. Give these to your identity provider</CardTitle>
+          <CardDescription>Enter them where you set up the app (SAML) in Okta, Entra ID, Google Workspace or similar.</CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <CopyField label="ACS URL" value={connection.serviceProvider.acsUrl} />
+          <CopyField label="Entity ID" value={connection.serviceProvider.entityId} />
+          <CopyField label="Metadata URL" value={connection.serviceProvider.metadataUrl} />
+          <p className="text-sm text-muted-foreground">
+            If your provider asks for a file, open the metadata URL and save it.{" "}
+            <a href={connection.serviceProvider.metadataUrl} target="_blank" rel="noreferrer" className="inline-flex items-center gap-1 underline">
+              Open <ExternalLink className="size-3" />
+            </a>
+          </p>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>2. Your identity provider&apos;s settings</CardTitle>
+          <CardDescription>Paste its metadata, or fill in the fields below.</CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          {warnsSignOut ? (
+            <Notice>
+              {isActive ? "This connection is on. " : ""}
+              Changing the certificates, sign-in URL or subject attribute puts the connection back to draft and signs out
+              learners who used SSO. You will need to test it again before turning it on.
+            </Notice>
+          ) : null}
+          <div className="space-y-1.5">
+            <Label htmlFor="sso-name">Button label</Label>
+            <Input id="sso-name" value={form.displayName} maxLength={100} disabled={readOnly} onChange={(e) => set({ displayName: e.target.value })} />
+            <p className="text-xs text-muted-foreground">Learners see this on the sign-in button.</p>
+          </div>
+          {!readOnly ? (
+            <div className="space-y-1.5">
+              <Label htmlFor="sso-metadata">Metadata XML</Label>
+              <Textarea
+                id="sso-metadata"
+                rows={5}
+                value={form.metadataXml}
+                className="font-mono text-xs"
+                placeholder="Paste to replace the sign-in URL and certificates below"
+                onChange={(e) => set({ metadataXml: e.target.value })}
+              />
+            </div>
+          ) : null}
+          <div className="space-y-1.5">
+            <Label htmlFor="sso-entity">Provider entity ID</Label>
+            <Input id="sso-entity" readOnly disabled value={connection.idpEntityId ?? ""} />
+            <p className="text-xs text-muted-foreground">
+              This can&apos;t be changed. To use a different provider, delete this connection and create a new one.
+            </p>
+          </div>
+          <div className="space-y-1.5">
+            <Label htmlFor="sso-url">Sign-in URL</Label>
+            <Input
+              id="sso-url"
+              value={form.idpSsoUrl}
+              disabled={readOnly || form.metadataXml.trim().length > 0}
+              placeholder="https://"
+              onChange={(e) => set({ idpSsoUrl: e.target.value })}
+            />
+          </div>
+          <div className="space-y-1.5">
+            <Label htmlFor="sso-certs">Certificates</Label>
+            <Textarea
+              id="sso-certs"
+              rows={6}
+              value={form.certificates}
+              disabled={readOnly || form.metadataXml.trim().length > 0}
+              className="font-mono text-xs"
+              placeholder="-----BEGIN CERTIFICATE-----"
+              onChange={(e) => set({ certificates: e.target.value })}
+            />
+            <p className="text-xs text-muted-foreground">
+              PEM format. To rotate a certificate, add the new one next to the old one.
+            </p>
+          </div>
+          <div className="space-y-1.5">
+            <Label htmlFor="sso-subject">Subject attribute (optional)</Label>
+            <Input
+              id="sso-subject"
+              value={form.subjectAttribute}
+              disabled={readOnly}
+              placeholder="e.g. objectidentifier"
+              onChange={(e) => set({ subjectAttribute: e.target.value })}
+            />
+            <p className="text-xs text-muted-foreground">
+              Needed only if your provider can&apos;t send a persistent NameID. Use an attribute that never changes for a
+              person and is never reused. Don&apos;t use their email address.
+            </p>
+          </div>
+          {!readOnly ? (
+            <div className="flex items-center gap-3">
+              <Button
+                type="button"
+                disabled={!dirty || saving || form.displayName.trim().length === 0}
+                onClick={() => (warnsSignOut ? setConfirmSave(true) : void save())}
+              >
+                Save
+              </Button>
+              {dirty ? (
+                <Button type="button" variant="ghost" onClick={() => setForm(formFromConnection(connection))}>
+                  Discard changes
+                </Button>
+              ) : null}
+            </div>
+          ) : null}
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>3. Domains</CardTitle>
+          <CardDescription>
+            Only learners whose email is on a verified domain can sign in with SSO. Prove you own each domain with a DNS
+            record.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          {connection.domains.length === 0 ? (
+            <p className="text-sm text-muted-foreground">No domains yet.</p>
+          ) : null}
+          {connection.domains.map((domain) => {
+            const status = domainStatus(domain);
+            const record = txtRecordDisplay(domain);
+            return (
+              <div key={domain.domain} className="space-y-3 rounded-md border p-4">
+                <div className="flex flex-wrap items-center justify-between gap-2">
+                  <div className="flex items-center gap-2">
+                    <span className="font-medium">{domain.domain}</span>
+                    <Badge variant={status.tone === "success" ? "success" : status.tone === "warning" ? "warning" : "outline"}>
+                      {status.label}
+                    </Badge>
+                  </div>
+                  {!readOnly ? (
+                    <div className="flex gap-2">
+                      <Button
+                        type="button"
+                        size="sm"
+                        variant="outline"
+                        disabled={busy === `verify:${domain.domain}`}
+                        onClick={() => void verifyDomain(domain)}
+                      >
+                        {domain.verified ? "Check again" : "Verify"}
+                      </Button>
+                      <Button
+                        type="button"
+                        size="sm"
+                        variant="outline"
+                        aria-label={`Remove ${domain.domain}`}
+                        disabled={busy === `remove:${domain.domain}`}
+                        onClick={() => void removeDomain(domain)}
+                      >
+                        <Trash2 className="size-4" />
+                      </Button>
+                    </div>
+                  ) : null}
+                </div>
+                {domain.verified && domain.consecutiveCheckFailures > 0 ? (
+                  <Notice>
+                    We couldn&apos;t find the DNS record on the last check. If it stays missing, the domain stops working
+                    for SSO.
+                  </Notice>
+                ) : null}
+                {!domain.verified || domain.consecutiveCheckFailures > 0 ? (
+                  <div className="space-y-3">
+                    <p className="text-sm text-muted-foreground">Add this record at your DNS provider, then select Verify.</p>
+                    <div className="grid gap-3 sm:grid-cols-[auto_1fr]">
+                      <div className="space-y-1.5">
+                        <Label>Type</Label>
+                        <p className="flex h-9 items-center font-mono text-xs">{record.type}</p>
+                      </div>
+                      <CopyField label="Name" value={record.name} />
+                    </div>
+                    <CopyField label="Value" value={record.value} />
+                  </div>
+                ) : null}
+                {formatDate(domain.verifiedAt) && domain.verified ? (
+                  <p className="text-xs text-muted-foreground">Verified {formatDate(domain.verifiedAt)}</p>
+                ) : null}
+              </div>
+            );
+          })}
+          {!readOnly ? (
+            <form
+              className="flex gap-2"
+              onSubmit={(event) => {
+                event.preventDefault();
+                void addDomain();
+              }}
+            >
+              <Input
+                aria-label="Domain"
+                placeholder="example.com"
+                value={newDomain}
+                onChange={(e) => setNewDomain(e.target.value)}
+              />
+              <Button type="submit" variant="outline" disabled={!newDomain.trim() || busy === "add-domain"}>
+                Add domain
+              </Button>
+            </form>
+          ) : null}
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>4. Test the connection</CardTitle>
+          <CardDescription>
+            Sign in once through your provider to check the settings. Nobody is signed in to your school by a test.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          {connection.testedAt ? (
+            <p className="text-sm text-muted-foreground">
+              Last successful test: {formatDate(connection.testedAt)}.{" "}
+              {connection.testedCurrentConfiguration ? "" : "The settings changed since, so test again."}
+            </p>
+          ) : (
+            <p className="text-sm text-muted-foreground">Not tested yet.</p>
+          )}
+          {dirty && !readOnly ? <p className="text-sm text-muted-foreground">Save your changes before testing.</p> : null}
+          {testNote && !readOnly ? <p className="text-sm text-muted-foreground">{testNote}</p> : null}
+          {!readOnly ? (
+            <div>
+              <Button type="button" variant="outline" disabled={!canTest || busy === "test"} onClick={() => void startTest()}>
+                Test connection
+              </Button>
+            </div>
+          ) : null}
+          {testMissing ? (
+            <Notice>The test result is no longer available. Run the test again.</Notice>
+          ) : null}
+          {testResult ? <TestResult result={testResult} /> : null}
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>5. Who has to use SSO</CardTitle>
+          <CardDescription>These apply once the connection is on.</CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-5">
+          <div className="flex items-start justify-between gap-4">
+            <div className="space-y-1">
+              <Label htmlFor="sso-enforce">Require SSO for these domains</Label>
+              <p className="text-sm text-muted-foreground">
+                Learners with an email on a verified domain can only sign in with SSO. Anyone in those domains who is
+                signed in another way is signed out.
+              </p>
+            </div>
+            <Switch
+              id="sso-enforce"
+              checked={connection.enforcement === "required_for_domains"}
+              disabled={readOnly || busy === "enforcement" || (!hasVerifiedDomain && connection.enforcement === "optional")}
+              onCheckedChange={(on) => void saveEnforcement(on)}
+            />
+          </div>
+          {!hasVerifiedDomain && connection.enforcement === "optional" ? (
+            <p className="text-xs text-muted-foreground">Verify a domain to turn this on.</p>
+          ) : null}
+          <div className="space-y-1.5">
+            <Label htmlFor="sso-minutes">Longest session (minutes)</Label>
+            <Input
+              id="sso-minutes"
+              inputMode="numeric"
+              value={form.maxSessionMinutes}
+              disabled={readOnly}
+              placeholder="School default"
+              className="max-w-48"
+              onChange={(e) => set({ maxSessionMinutes: e.target.value })}
+            />
+            {minutesError ? <p className="text-xs text-destructive">{minutesError}</p> : null}
+            <p className="text-xs text-muted-foreground">
+              Learners sign in again after this long. Leave empty to use the school default. Saved with the button in
+              section 2.
+            </p>
+          </div>
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>6. Turn it on</CardTitle>
+          <CardDescription>
+            {isActive ? "SSO is on. Learners see the sign-in button." : "Learners can use SSO once the connection is on."}
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          {blockers.length > 0 ? (
+            <ul className="list-disc space-y-1 pl-5 text-sm text-muted-foreground">
+              {blockers.map((blocker) => (
+                <li key={`${blocker.code}:${blocker.message}`}>{blocker.message}</li>
+              ))}
+            </ul>
+          ) : null}
+          {upgrade ? (
+            <Notice tone="info">
+              <span className="font-medium">Business plan.</span> SSO is part of the Business plan.{" "}
+              <Link href="/account/billing" className="underline">
+                See plans
+              </Link>
+            </Notice>
+          ) : null}
+          {!readOnly ? (
+            <div className="flex flex-wrap gap-2">
+              {isActive ? (
+                <Button type="button" variant="outline" disabled={busy !== null} onClick={() => setConfirm("disable")}>
+                  Turn off
+                </Button>
+              ) : (
+                <Button
+                  type="button"
+                  disabled={busy !== null || blockers.length > 0 || dirty}
+                  onClick={() => setConfirm("activate")}
+                >
+                  Turn on
+                </Button>
+              )}
+              <Button type="button" variant="outline" disabled={busy !== null} onClick={() => setConfirm("delete")}>
+                <Trash2 className="mr-2 size-4" />
+                Delete
+              </Button>
+            </div>
+          ) : null}
+        </CardContent>
+      </Card>
+
+      <Dialog open={confirmSave} onOpenChange={setConfirmSave}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Save and sign out SSO learners?</DialogTitle>
+            <DialogDescription>
+              These changes put the connection back to draft and sign out learners who used SSO. Test it again before
+              turning it on.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <Button type="button" variant="outline" onClick={() => setConfirmSave(false)}>
+              Cancel
+            </Button>
+            <Button type="button" disabled={saving} onClick={() => void save()}>
+              Save changes
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      <Dialog open={confirm !== null} onOpenChange={(open) => !open && setConfirm(null)}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>
+              {confirm === "activate" ? "Turn on SSO?" : confirm === "disable" ? "Turn off SSO?" : "Delete this connection?"}
+            </DialogTitle>
+            <DialogDescription>
+              {confirm === "activate"
+                ? connection.enforcement === "required_for_domains"
+                  ? "Learners on your verified domains will have to use SSO. Anyone signed in another way is signed out."
+                  : "Learners will see the SSO button on your sign-in page."
+                : confirm === "disable"
+                  ? "Learners who signed in with SSO are signed out. They can sign in with another method."
+                  : "This removes the connection, its domains and the links between learners and their provider accounts. Learners who signed in with SSO are signed out. This can't be undone."}
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <Button type="button" variant="outline" onClick={() => setConfirm(null)}>
+              Cancel
+            </Button>
+            <Button
+              type="button"
+              disabled={busy !== null}
+              onClick={() => (confirm === "delete" ? void remove() : confirm && void changeState(confirm))}
+            >
+              {confirm === "activate" ? "Turn on" : confirm === "disable" ? "Turn off" : "Delete"}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      <RecentSignInDialog open={reauth} onOpenChange={setReauth} />
+    </div>
+  );
+}
+
+function TestResult({ result }: { result: SsoTestResult }) {
+  if (!result.ok) {
+    const hint = testFailureHint(result.reason);
+    return (
+      <Notice>
+        The test sign-in failed{result.reason ? ` (${result.reason})` : ""}.{" "}
+        {hint ?? "Check the provider's settings, then try again."}
+      </Notice>
+    );
+  }
+  const rows: [string, string | null][] = [
+    ["Provider", result.issuer],
+    ["Subject", result.subject],
+    ["Email", result.email],
+    ["Name", result.name],
+    [
+      "Email domain",
+      result.emailDomainVerified === null ? null : result.emailDomainVerified ? "On a verified domain" : "Not on a verified domain",
+    ],
+  ];
+  return (
+    <div className="space-y-3 rounded-md border p-4">
+      <p className="text-sm font-medium">The test sign-in worked. Your provider sent:</p>
+      <dl className="grid gap-x-4 gap-y-1 text-sm sm:grid-cols-[8rem_1fr]">
+        {rows
+          .filter(([, value]) => value)
+          .map(([label, value]) => (
+            <div key={label} className="contents">
+              <dt className="text-muted-foreground">{label}</dt>
+              <dd className="break-all font-mono text-xs">{value}</dd>
+            </div>
+          ))}
+      </dl>
+      {result.emailDomainVerified === false ? (
+        <Notice>The email isn&apos;t on a verified domain, so this person couldn&apos;t sign in. Verify the domain first.</Notice>
+      ) : null}
+      {Object.keys(result.attributes).length > 0 ? (
+        <details className="text-sm">
+          <summary className="cursor-pointer text-muted-foreground">All attributes</summary>
+          <dl className="mt-2 grid gap-x-4 gap-y-1 sm:grid-cols-[12rem_1fr]">
+            {sortedAttributes(result.attributes).map(([name, values]) => (
+              <div key={name} className="contents">
+                <dt className="break-all font-mono text-xs text-muted-foreground">{name}</dt>
+                <dd className="break-all font-mono text-xs">{values.join(", ")}</dd>
+              </div>
+            ))}
+          </dl>
+        </details>
+      ) : null}
+    </div>
+  );
+}
diff --git a/apps/admin/lib/school-api.ts b/apps/admin/lib/school-api.ts
new file mode 100644
index 000000000..790a19a84
--- /dev/null
+++ b/apps/admin/lib/school-api.ts
@@ -0,0 +1,74 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+export type ApiResult<T> = { ok: boolean; status: number; body: T | null };
+
+/** Calls the school API through the admin proxy for the selected school. */
+export async function schoolRequest<T>(
+  schoolId: string,
+  path: string,
+  init: { method?: string; body?: unknown } = {},
+): Promise<ApiResult<T>> {
+  const response = await fetch(path, {
+    method: init.method ?? "GET",
+    credentials: "include",
+    cache: "no-store",
+    headers: {
+      "x-school-id": schoolId,
+      ...(init.body === undefined ? {} : { "content-type": "application/json" }),
+    },
+    body: init.body === undefined ? undefined : JSON.stringify(init.body),
+  });
+  const body = (await response.json().catch(() => null)) as T | null;
+  return { ok: response.ok, status: response.status, body };
+}
+
+type SchoolItem = { id: string; name: string; isOwner?: boolean; selected?: boolean };
+
+/** The selected school, whether the viewer owns it, and whether hosted billing exists. */
+export function useSelectedSchool() {
+  const [state, setState] = useState<{
+    loading: boolean;
+    schoolId: string | null;
+    isOwner: boolean;
+    billingAvailable: boolean;
+  }>({ loading: true, schoolId: null, isOwner: false, billingAvailable: false });
+
+  useEffect(() => {
+    let active = true;
+    void (async () => {
+      try {
+        const response = await fetch("/api/v1/schools", { credentials: "include", cache: "no-store" });
+        const body = (response.ok ? await response.json() : { items: [] }) as { items?: SchoolItem[] };
+        const items = body.items ?? [];
+        const school = items.find((item) => item.selected) ?? items[0];
+        if (!school) {
+          if (active) setState((s) => ({ ...s, loading: false }));
+          return;
+        }
+        const isOwner = school.isOwner === true;
+        // Only the owner can read the plan; everyone else just doesn't see upgrade prompts.
+        let billingAvailable = false;
+        if (isOwner) {
+          const plan = await fetch("/api/v1/school/billing", {
+            credentials: "include",
+            cache: "no-store",
+            headers: { "x-school-id": school.id },
+          })
+            .then((r) => (r.ok ? r.json() : null))
+            .catch(() => null);
+          billingAvailable = (plan as { billingAvailable?: boolean } | null)?.billingAvailable === true;
+        }
+        if (active) setState({ loading: false, schoolId: school.id, isOwner, billingAvailable });
+      } catch {
+        if (active) setState((s) => ({ ...s, loading: false }));
+      }
+    })();
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  return state;
+}
diff --git a/apps/admin/lib/sso.test.ts b/apps/admin/lib/sso.test.ts
new file mode 100644
index 000000000..bd76c3fe9
--- /dev/null
+++ b/apps/admin/lib/sso.test.ts
@@ -0,0 +1,267 @@
+import { describe, expect, it } from "bun:test";
+import {
+  activationBlockers,
+  buildUpdateBody,
+  changesTrust,
+  domainStatus,
+  errorReason,
+  formFromConnection,
+  methodsAfterToggle,
+  parseSsoTestReturn,
+  primarySsoConnection,
+  sessionMinutesError,
+  showUpgradePrompt,
+  splitCertificates,
+  ssoErrorMessage,
+  testAvailability,
+  testFailureHint,
+  txtRecordDisplay,
+  wouldLeaveNoMethod,
+  type SchoolLoginMethods,
+  type SsoConnection,
+  type SsoDomain,
+} from "./sso";
+
+const domain = (overrides: Partial<SsoDomain> = {}): SsoDomain => ({
+  domain: "acme.com",
+  verified: false,
+  verifiedAt: null,
+  verificationRecord: { type: "TXT", name: "_courselit-verification.acme.com", value: "tok_123" },
+  consecutiveCheckFailures: 0,
+  lastCheckedAt: null,
+  ...overrides,
+});
+
+const connection = (overrides: Partial<SsoConnection> = {}): SsoConnection => ({
+  id: "sso_1",
+  protocol: "saml",
+  status: "draft",
+  displayName: "Acme",
+  enforcement: "optional",
+  maxSessionMinutes: null,
+  idpEntityId: "https://idp.acme.com",
+  idpSsoUrl: "https://idp.acme.com/sso",
+  idpCertificates: ["-----BEGIN CERTIFICATE-----\nAAAA\n-----END CERTIFICATE-----"],
+  subjectAttribute: null,
+  serviceProvider: { entityId: "e", acsUrl: "a", metadataUrl: "m" },
+  domains: [],
+  testedAt: null,
+  testedCurrentConfiguration: false,
+  planAvailable: true,
+  createdAt: "2026-01-01T00:00:00Z",
+  updatedAt: "2026-01-01T00:00:00Z",
+  ...overrides,
+});
+
+const methods = (overrides: Partial<SchoolLoginMethods> = {}): SchoolLoginMethods => ({
+  loginMethods: ["email", "google"],
+  googleAvailable: true,
+  sso: { active: false, displayName: null, planAvailable: true },
+  usable: ["email", "google"],
+  ...overrides,
+});
+
+describe("parseSsoTestReturn", () => {
+  const id = "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b";
+  it("reads the request id the API adds on return", () => {
+    expect(parseSsoTestReturn(`?ssoTest=${id}`)).toBe(id);
+    expect(parseSsoTestReturn(`a=1&ssoTest=${id}`)).toBe(id);
+  });
+  it("ignores missing or malformed ids", () => {
+    expect(parseSsoTestReturn("")).toBeNull();
+    expect(parseSsoTestReturn("?ssoTest=nope")).toBeNull();
+    expect(parseSsoTestReturn("?ssoTest=../x")).toBeNull();
+  });
+});
+
+describe("errors", () => {
+  it("reads the reason from an error body", () => {
+    expect(errorReason({ code: "forbidden", details: { reason: "plan_required" } })).toBe("plan_required");
+    expect(errorReason(null)).toBeNull();
+    expect(errorReason({ details: { reason: 3 } })).toBeNull();
+  });
+  it("maps reasons to plain messages", () => {
+    expect(ssoErrorMessage({ details: { reason: "unsafe_sso_url" } }, "x")).toContain("https://");
+    expect(ssoErrorMessage({ details: { reason: "metadata_invalid_xml" } }, "x")).toContain("metadata");
+    expect(ssoErrorMessage({ details: { reason: "unknown" } }, "fallback")).toBe("fallback");
+  });
+});
+
+describe("testAvailability", () => {
+  const editable = { readOnly: false, dirty: false };
+  it("allows tests on draft and active connections", () => {
+    expect(testAvailability(connection({ status: "draft" }), editable)).toEqual({ canTest: true, note: null });
+    expect(testAvailability(connection({ status: "active" }), editable)).toEqual({ canTest: true, note: null });
+  });
+  it("refuses turned-off and paused connections with a note, matching the API", () => {
+    const off = testAvailability(connection({ status: "disabled" }), editable);
+    expect(off.canTest).toBe(false);
+    expect(off.note).toContain("change its provider settings");
+    expect(testAvailability(connection({ status: "suspended" }), editable).canTest).toBe(false);
+  });
+  it("waits for saved, complete settings", () => {
+    expect(testAvailability(connection(), { readOnly: false, dirty: true })).toEqual({ canTest: false, note: null });
+    expect(testAvailability(connection(), { readOnly: true, dirty: false }).canTest).toBe(false);
+    expect(testAvailability(connection({ idpCertificates: [] }), editable).canTest).toBe(false);
+  });
+});
+
+describe("testFailureHint", () => {
+  it("explains the provider settings behind fixable failures", () => {
+    expect(testFailureHint("signature_invalid")).toContain("sign the assertion itself");
+    expect(testFailureHint("weak_algorithm")).toContain("RSA-SHA256");
+    expect(testFailureHint("unstable_subject")).toContain("persistent");
+  });
+  it("has nothing to add for other or missing reasons", () => {
+    expect(testFailureHint("request_already_used")).toBeNull();
+    expect(testFailureHint(null)).toBeNull();
+    expect(testFailureHint("toString")).toBeNull();
+  });
+});
+
+describe("activationBlockers", () => {
+  const ready = connection({
+    domains: [domain({ verified: true })],
+    testedAt: "2026-01-02T00:00:00Z",
+    testedCurrentConfiguration: true,
+  });
+
+  it("is empty when everything is in place or already active", () => {
+    expect(activationBlockers(ready, { billingAvailable: true })).toEqual([]);
+    expect(activationBlockers(connection({ status: "active" }), { billingAvailable: true })).toEqual([]);
+  });
+  it("lists what is missing, in order", () => {
+    const codes = activationBlockers(connection({ idpCertificates: [] }), { billingAvailable: true }).map(
+      (b) => b.code,
+    );
+    expect(codes).toEqual(["incomplete", "no_verified_domain", "not_tested"]);
+  });
+  it("says the settings changed when the test is stale", () => {
+    const [blocker] = activationBlockers(
+      { ...ready, testedCurrentConfiguration: false },
+      { billingAvailable: true },
+    );
+    expect(blocker.code).toBe("not_tested");
+    expect(blocker.message).toContain("changed");
+  });
+  it("puts the plan first, and words it for self-hosted schools", () => {
+    const noPlan = { ...ready, planAvailable: false };
+    expect(activationBlockers(noPlan, { billingAvailable: true })[0].message).toContain("Business");
+    expect(activationBlockers(noPlan, { billingAvailable: false })[0].message).not.toContain("Business");
+  });
+  it("blocks a suspended connection", () => {
+    expect(activationBlockers({ ...ready, status: "suspended" }, { billingAvailable: true })[0].code).toBe(
+      "suspended",
+    );
+  });
+});
+
+describe("showUpgradePrompt", () => {
+  it("only shows when billing exists and the plan lacks SSO", () => {
+    expect(showUpgradePrompt({ planAvailable: false, status: "draft" }, true)).toBe(true);
+    expect(showUpgradePrompt({ planAvailable: false, status: "draft" }, false)).toBe(false);
+    expect(showUpgradePrompt({ planAvailable: true, status: "draft" }, true)).toBe(false);
+  });
+});
+
+describe("domains", () => {
+  it("shows the TXT record to publish", () => {
+    expect(txtRecordDisplay(domain())).toEqual({
+      type: "TXT",
+      name: "_courselit-verification.acme.com",
+      value: "tok_123",
+    });
+  });
+  it("describes the state", () => {
+    expect(domainStatus(domain()).label).toBe("Not verified");
+    expect(domainStatus(domain({ verified: true })).tone).toBe("success");
+    expect(domainStatus(domain({ verified: true, consecutiveCheckFailures: 1 })).tone).toBe("warning");
+  });
+});
+
+describe("primarySsoConnection", () => {
+  it("prefers an active connection, then the newest", () => {
+    const a = connection({ id: "a", status: "draft" });
+    const b = connection({ id: "b", status: "active" });
+    const c = connection({ id: "c", status: "disabled" });
+    expect(primarySsoConnection([a, b, c])?.id).toBe("b");
+    expect(primarySsoConnection([a, c])?.id).toBe("c");
+    expect(primarySsoConnection([])).toBeNull();
+  });
+});
+
+describe("certificates and changes", () => {
+  it("splits several PEM blocks", () => {
+    const text =
+      "-----BEGIN CERTIFICATE-----\nAAAA\n-----END CERTIFICATE-----\n\n-----BEGIN CERTIFICATE-----\nBBBB\n-----END CERTIFICATE-----";
+    expect(splitCertificates(text)).toHaveLength(2);
+    expect(splitCertificates("  ")).toEqual([]);
+  });
+
+  it("does not flag a trust change when nothing changed", () => {
+    const c = connection();
+    expect(changesTrust(c, formFromConnection(c))).toBe(false);
+    expect(buildUpdateBody(c, formFromConnection(c))).toEqual({});
+  });
+
+  it("flags changes to URL, certificates, subject attribute and pasted metadata", () => {
+    const c = connection();
+    const base = formFromConnection(c);
+    expect(changesTrust(c, { ...base, idpSsoUrl: "https://other/sso" })).toBe(true);
+    expect(changesTrust(c, { ...base, certificates: "" })).toBe(true);
+    expect(changesTrust(c, { ...base, subjectAttribute: "oid" })).toBe(true);
+    expect(changesTrust(c, { ...base, metadataXml: "<xml/>" })).toBe(true);
+  });
+
+  it("does not flag the name, or session length", () => {
+    const c = connection();
+    const base = formFromConnection(c);
+    expect(changesTrust(c, { ...base, displayName: "New", maxSessionMinutes: "60" })).toBe(false);
+  });
+
+  it("sends only the changed fields", () => {
+    const c = connection();
+    const base = formFromConnection(c);
+    expect(buildUpdateBody(c, { ...base, displayName: "Acme staff", maxSessionMinutes: "60" })).toEqual({
+      displayName: "Acme staff",
+      maxSessionMinutes: 60,
+    });
+    expect(buildUpdateBody(c, { ...base, subjectAttribute: " oid " })).toEqual({ subjectAttribute: "oid" });
+    expect(buildUpdateBody(c, { ...base, subjectAttribute: "" })).toEqual({});
+  });
+
+  it("sends pasted metadata instead of the manual fields", () => {
+    const c = connection();
+    const base = formFromConnection(c);
+    expect(buildUpdateBody(c, { ...base, metadataXml: " <xml/> ", idpSsoUrl: "https://x/sso" })).toEqual({
+      metadataXml: "<xml/>",
+    });
+  });
+
+  it("validates the session length", () => {
+    expect(sessionMinutesError("")).toBeNull();
+    expect(sessionMinutesError("60")).toBeNull();
+    expect(sessionMinutesError("3")).not.toBeNull();
+    expect(sessionMinutesError("1.5")).not.toBeNull();
+    expect(sessionMinutesError("abc")).not.toBeNull();
+  });
+});
+
+describe("sign-in method toggles", () => {
+  it("computes the methods left", () => {
+    expect(methodsAfterToggle(methods(), "email", false)).toEqual(["google"]);
+    expect(methodsAfterToggle(methods({ loginMethods: ["email"] }), "google", true)).toEqual(["email", "google"]);
+  });
+  it("refuses to turn off the last usable method", () => {
+    expect(wouldLeaveNoMethod(methods({ loginMethods: ["email"] }), "email")).toBe(true);
+    expect(wouldLeaveNoMethod(methods(), "email")).toBe(false);
+  });
+  it("counts an active SSO connection", () => {
+    const m = methods({ loginMethods: ["email"], sso: { active: true, displayName: "Acme", planAvailable: true } });
+    expect(wouldLeaveNoMethod(m, "email")).toBe(false);
+  });
+  it("does not count Google when the platform has no keys", () => {
+    const m = methods({ loginMethods: ["email", "google"], googleAvailable: false });
+    expect(wouldLeaveNoMethod(m, "email")).toBe(true);
+  });
+});
diff --git a/apps/admin/lib/sso.ts b/apps/admin/lib/sso.ts
new file mode 100644
index 000000000..26ad18c4a
--- /dev/null
+++ b/apps/admin/lib/sso.ts
@@ -0,0 +1,316 @@
+import type {
+  schoolLoginMethodsSchema,
+  ssoConnectionSchema,
+  ssoConnectionTestResultSchema,
+  ssoDomainSchema,
+} from "@courselit/api-contract";
+
+export type SsoConnection = (typeof ssoConnectionSchema)["_output"];
+export type SsoDomain = (typeof ssoDomainSchema)["_output"];
+export type SsoTestResult = (typeof ssoConnectionTestResultSchema)["_output"];
+export type SchoolLoginMethods = (typeof schoolLoginMethodsSchema)["_output"];
+export type LoginMethod = "email" | "google";
+
+/** The query parameter the API adds when it sends the admin back from a test sign-in. */
+export const SSO_TEST_QUERY_PARAM = "ssoTest";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** The test request id the API put on the return URL, or null. */
+export function parseSsoTestReturn(search: string): string | null {
+  const value = new URLSearchParams(search).get(SSO_TEST_QUERY_PARAM);
+  return value && UUID.test(value) ? value : null;
+}
+
+/** The reason code in a platform error body, if any. */
+export function errorReason(body: unknown): string | null {
+  if (!body || typeof body !== "object") return null;
+  const details = (body as { details?: Record<string, unknown> }).details;
+  const reason = details?.reason;
+  return typeof reason === "string" ? reason : null;
+}
+
+export const RECENT_AUTHENTICATION_REASON = "recent_authentication_required";
+
+const REASON_MESSAGES: Record<string, string> = {
+  plan_required: "Your plan doesn't include single sign-on yet.",
+  connection_suspended: "This connection was paused because the plan changed. It comes back when the plan does.",
+  connection_not_testable: "This connection can't be tested right now.",
+  incomplete_configuration: "Add the sign-in URL and a certificate first.",
+  not_tested: "Test the connection with the current settings first.",
+  no_verified_domain: "Verify at least one domain first.",
+  another_connection_active: "Another connection is already on. Turn it off first.",
+  too_many_connections: "This school has reached the maximum number of connections.",
+  too_many_domains: "This connection has reached the maximum number of domains.",
+  domain_already_added: "That domain is already on this connection.",
+  invalid_domain: "Enter a domain like example.com.",
+  invalid_certificate: "One of the certificates isn't valid. Paste each one in PEM format.",
+  unsafe_sso_url: "The sign-in URL must start with https://.",
+  idp_entity_id_required: "Paste the provider's metadata, or enter its entity ID.",
+  idp_entity_id_immutable:
+    "This metadata is for a different provider. The entity ID can't change. Delete this connection and create a new one instead.",
+  return_url_not_allowed: "The test couldn't return to this page.",
+};
+
+/** A short, plain message for an API error. */
+export function ssoErrorMessage(body: unknown, fallback: string): string {
+  const reason = errorReason(body);
+  if (reason) {
+    if (REASON_MESSAGES[reason]) return REASON_MESSAGES[reason];
+    if (reason.startsWith("metadata_")) {
+      return "That metadata couldn't be read. Paste the full XML your provider gave you.";
+    }
+  }
+  return fallback;
+}
+
+export type SsoStatusKind = "active" | "draft" | "suspended" | "disabled" | "not_set_up";
+
+export function ssoStatusKind(connection: Pick<SsoConnection, "status"> | null | undefined): SsoStatusKind {
+  return connection ? connection.status : "not_set_up";
+}
+
+export const SSO_STATUS_LABELS: Record<SsoStatusKind, string> = {
+  active: "On",
+  draft: "Draft",
+  suspended: "Paused",
+  disabled: "Off",
+  not_set_up: "Not set up",
+};
+
+/** The connection to show on the sign-in methods list: an active one first, else the newest. */
+export function primarySsoConnection(items: readonly SsoConnection[]): SsoConnection | null {
+  return items.find((item) => item.status === "active") ?? items[items.length - 1] ?? null;
+}
+
+/**
+ * Whether a test sign-in can start, and if not, a note for the admin (null
+ * when the reason is already shown elsewhere, like unsaved changes). The API
+ * tests only draft and active connections; changing a turned-off
+ * connection's provider settings makes it a draft again.
+ */
+export function testAvailability(
+  connection: Pick<SsoConnection, "status" | "idpSsoUrl" | "idpCertificates">,
+  options: { readOnly: boolean; dirty: boolean },
+): { canTest: boolean; note: string | null } {
+  if (options.readOnly || options.dirty) return { canTest: false, note: null };
+  if (!connection.idpSsoUrl || connection.idpCertificates.length === 0) {
+    return { canTest: false, note: "Add the sign-in URL and a certificate first." };
+  }
+  if (connection.status === "suspended") {
+    return { canTest: false, note: "Single sign-on is paused because your plan doesn't include it." };
+  }
+  if (connection.status === "disabled") {
+    return {
+      canTest: false,
+      note: "The connection is off. Turn it on with the settings it was tested with, or change its provider settings to test it again.",
+    };
+  }
+  return { canTest: true, note: null };
+}
+
+const TEST_FAILURE_HINTS: Record<string, string> = {
+  status_not_success:
+    "Your provider refused the sign-in. Check that the person is assigned to the app in your provider.",
+  signature_invalid:
+    "Your provider has to sign the assertion itself, not only the response, with one of the certificates above. In Keycloak, turn on Sign assertions.",
+  weak_algorithm: "Your provider signed with SHA-1. Set its signature algorithm to RSA-SHA256.",
+  wrong_audience: "Your provider sent a different audience. Set its entity ID (audience) to the Entity ID in step 1.",
+  wrong_recipient: "Your provider sent the response to another address. Set its ACS URL to the one in step 1.",
+  wrong_destination: "Your provider sent the response to another address. Set its ACS URL to the one in step 1.",
+  wrong_issuer: "The response came from a different provider than the entity ID saved here.",
+  missing_subject: "Your provider didn't send a NameID. Set its NameID format to persistent.",
+  unstable_subject:
+    "Your provider's NameID isn't in the persistent format. Set its NameID format to persistent, or set a subject attribute.",
+  expired: "The response had already expired. Check that your provider's clock is right.",
+  not_yet_valid: "The response isn't valid yet. Check that your provider's clock is right.",
+};
+
+/** What to change after a failed test, for the reasons the admin can fix in the provider. */
+export function testFailureHint(reason: string | null | undefined): string | null {
+  return reason && Object.hasOwn(TEST_FAILURE_HINTS, reason) ? TEST_FAILURE_HINTS[reason]! : null;
+}
+
+export type ActivationBlocker =
+  | "suspended"
+  | "plan"
+  | "incomplete"
+  | "no_verified_domain"
+  | "not_tested";
+
+/**
+ * Why Activate is unavailable, in the order the admin should fix things.
+ * Empty when the connection can be turned on (or already is).
+ */
+export function activationBlockers(
+  connection: SsoConnection,
+  options: { billingAvailable: boolean },
+): { code: ActivationBlocker; message: string }[] {
+  if (connection.status === "active") return [];
+  const blockers: { code: ActivationBlocker; message: string }[] = [];
+  if (connection.status === "suspended") {
+    blockers.push({
+      code: "suspended",
+      message: "Paused because the plan changed. It turns back on when the plan includes single sign-on again.",
+    });
+  } else if (!connection.planAvailable) {
+    blockers.push({
+      code: "plan",
+      message: options.billingAvailable
+        ? "Single sign-on is part of the Business plan."
+        : "Single sign-on isn't available for this school.",
+    });
+  }
+  if (!connection.idpSsoUrl || connection.idpCertificates.length === 0) {
+    blockers.push({ code: "incomplete", message: "Add the provider's sign-in URL and a certificate." });
+  }
+  if (!connection.domains.some((domain) => domain.verified)) {
+    blockers.push({ code: "no_verified_domain", message: "Verify at least one domain." });
+  }
+  if (!connection.testedAt) {
+    blockers.push({ code: "not_tested", message: "Run a test sign-in." });
+  } else if (!connection.testedCurrentConfiguration) {
+    blockers.push({
+      code: "not_tested",
+      message: "The settings changed since the last test. Test the connection again.",
+    });
+  }
+  return blockers;
+}
+
+/** Whether to offer the Business plan upgrade prompt: the plan lacks SSO and this school can upgrade. */
+export function showUpgradePrompt(
+  connection: Pick<SsoConnection, "planAvailable" | "status">,
+  billingAvailable: boolean,
+): boolean {
+  return billingAvailable && !connection.planAvailable && connection.status !== "active";
+}
+
+/** What to publish at the DNS provider for a domain. */
+export function txtRecordDisplay(domain: Pick<SsoDomain, "verificationRecord">): {
+  type: string;
+  name: string;
+  value: string;
+} {
+  const { type, name, value } = domain.verificationRecord;
+  return { type, name, value };
+}
+
+/** Plain text for a domain's state. */
+export function domainStatus(domain: SsoDomain): { label: string; tone: "success" | "warning" | "neutral" } {
+  if (domain.verified) {
+    return domain.consecutiveCheckFailures > 0
+      ? { label: "Verified, record not found on last check", tone: "warning" }
+      : { label: "Verified", tone: "success" };
+  }
+  return { label: "Not verified", tone: "neutral" };
+}
+
+export type SsoFormValues = {
+  displayName: string;
+  idpSsoUrl: string;
+  certificates: string;
+  subjectAttribute: string;
+  metadataXml: string;
+  maxSessionMinutes: string;
+};
+
+/** Each PEM block (or bare base64 body) from the certificates box. */
+export function splitCertificates(text: string): string[] {
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+  const blocks = trimmed.match(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g);
+  if (blocks) return blocks.map((block) => block.trim());
+  return trimmed
+    .split(/\n\s*\n/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+export function formFromConnection(connection: SsoConnection): SsoFormValues {
+  return {
+    displayName: connection.displayName,
+    idpSsoUrl: connection.idpSsoUrl ?? "",
+    certificates: connection.idpCertificates.join("\n\n"),
+    subjectAttribute: connection.subjectAttribute ?? "",
+    metadataXml: "",
+    maxSessionMinutes: connection.maxSessionMinutes ? String(connection.maxSessionMinutes) : "",
+  };
+}
+
+const bare = (certificate: string) =>
+  certificate.replace(/-----(BEGIN|END) CERTIFICATE-----/g, "").replace(/\s+/g, "");
+
+/**
+ * Whether saving these values changes what the connection trusts (sign-in URL,
+ * certificates, subject attribute). On an active connection that puts it back
+ * to draft and signs out its learners.
+ */
+export function changesTrust(connection: SsoConnection, values: SsoFormValues): boolean {
+  if (values.metadataXml.trim()) return true;
+  if (values.idpSsoUrl.trim() !== (connection.idpSsoUrl ?? "")) return true;
+  if ((values.subjectAttribute.trim() || null) !== connection.subjectAttribute) return true;
+  const current = connection.idpCertificates.map(bare).sort().join("|");
+  const next = splitCertificates(values.certificates).map(bare).sort().join("|");
+  return current !== next;
+}
+
+/** The body for updateSsoConnection: only what changed. */
+export function buildUpdateBody(
+  connection: SsoConnection,
+  values: SsoFormValues,
+): Record<string, unknown> {
+  const body: Record<string, unknown> = {};
+  if (values.displayName.trim() !== connection.displayName) body.displayName = values.displayName.trim();
+  if (values.metadataXml.trim()) {
+    body.metadataXml = values.metadataXml.trim();
+  } else {
+    if (values.idpSsoUrl.trim() !== (connection.idpSsoUrl ?? "")) body.idpSsoUrl = values.idpSsoUrl.trim();
+    const current = connection.idpCertificates.map(bare).sort().join("|");
+    const certificates = splitCertificates(values.certificates);
+    if (certificates.map(bare).sort().join("|") !== current) body.idpCertificates = certificates;
+  }
+  const subject = values.subjectAttribute.trim() || null;
+  if (subject !== connection.subjectAttribute) body.subjectAttribute = subject;
+  const minutes = values.maxSessionMinutes.trim() ? Number(values.maxSessionMinutes) : null;
+  if (minutes !== connection.maxSessionMinutes) body.maxSessionMinutes = minutes;
+  return body;
+}
+
+/** An error for the session length field, or null when it is empty or valid. */
+export function sessionMinutesError(value: string): string | null {
+  if (!value.trim()) return null;
+  const minutes = Number(value);
+  if (!Number.isInteger(minutes) || minutes < 5 || minutes > 525_600) {
+    return "Enter a whole number of minutes between 5 and 525600, or leave it empty.";
+  }
+  return null;
+}
+
+/**
+ * Which sign-in methods turning one off would leave, so the page can refuse to
+ * turn off the last usable one before the API does.
+ */
+export function methodsAfterToggle(
+  methods: SchoolLoginMethods,
+  method: LoginMethod,
+  on: boolean,
+): LoginMethod[] {
+  const next = new Set<LoginMethod>(methods.loginMethods);
+  if (on) next.add(method);
+  else next.delete(method);
+  return (["email", "google"] as const).filter((item) => next.has(item));
+}
+
+/** Whether turning `method` off would leave nothing usable (SSO counts when active). */
+export function wouldLeaveNoMethod(methods: SchoolLoginMethods, method: LoginMethod): boolean {
+  const remaining = methodsAfterToggle(methods, method, false);
+  const googleUsable = methods.googleAvailable;
+  const usable = remaining.filter((item) => item !== "google" || googleUsable);
+  return usable.length === 0 && !methods.sso.active;
+}
+
+/** Test attributes, sorted by name, for display. */
+export function sortedAttributes(attributes: Record<string, string[]>): [string, string[]][] {
+  return Object.entries(attributes).sort(([a], [b]) => a.localeCompare(b));
+}
diff --git a/apps/api/drizzle/0000_baseline.sql b/apps/api/drizzle/0000_baseline.sql
index d11da80cf..d880fe28f 100644
--- a/apps/api/drizzle/0000_baseline.sql
+++ b/apps/api/drizzle/0000_baseline.sql
@@ -781,6 +781,8 @@ CREATE TABLE "school_auth_tickets" (
 	"school_account_id" uuid NOT NULL,
 	"user_id" text NOT NULL,
 	"authentication_method" text NOT NULL,
+	"sso_connection_id" uuid,
+	"session_expires_at" timestamp with time zone,
 	"expires_at" timestamp with time zone NOT NULL,
 	"consumed_at" timestamp with time zone,
 	"created_at" timestamp with time zone NOT NULL,
@@ -846,6 +848,7 @@ CREATE TABLE "school_sessions" (
 	"user_id" text NOT NULL,
 	"token_digest" text NOT NULL,
 	"authentication_method" text NOT NULL,
+	"sso_connection_id" uuid,
 	"authenticated_at" timestamp with time zone NOT NULL,
 	"expires_at" timestamp with time zone NOT NULL,
 	"created_at" timestamp with time zone NOT NULL,
@@ -859,6 +862,7 @@ CREATE TABLE "schools" (
 	"subdomain" text NOT NULL,
 	"status" text DEFAULT 'active' NOT NULL,
 	"locale" text DEFAULT 'en' NOT NULL,
+	"login_methods" text[] DEFAULT '{email}'::text[] NOT NULL,
 	"currency" text DEFAULT 'USD' NOT NULL,
 	"payment_settings_encrypted" text,
 	"code_injection_head" text DEFAULT '' NOT NULL,
@@ -866,7 +870,8 @@ CREATE TABLE "schools" (
 	"created_at" timestamp with time zone NOT NULL,
 	"updated_at" timestamp with time zone NOT NULL,
 	CONSTRAINT "schools_public_id_unique" UNIQUE("public_id"),
-	CONSTRAINT "schools_subdomain_unique" UNIQUE("subdomain")
+	CONSTRAINT "schools_subdomain_unique" UNIQUE("subdomain"),
+	CONSTRAINT "schools_login_methods_check" CHECK ("schools"."login_methods" <@ ARRAY['email', 'google']::text[])
 );
 --> statement-breakpoint
 CREATE TABLE "selected_schools" (
@@ -1630,10 +1635,133 @@ CREATE TABLE "section_drip_emails" (
 	"updated_at" timestamp with time zone NOT NULL
 );
 --> statement-breakpoint
+CREATE TABLE "school_sso_assertion_ids" (
+	"connection_id" uuid NOT NULL,
+	"assertion_id" text NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	CONSTRAINT "school_sso_assertion_ids_connection_id_assertion_id_pk" PRIMARY KEY("connection_id","assertion_id")
+);
+--> statement-breakpoint
+CREATE TABLE "school_sso_connections" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"public_id" text NOT NULL,
+	"school_id" uuid NOT NULL,
+	"protocol" text NOT NULL,
+	"status" text DEFAULT 'draft' NOT NULL,
+	"display_name" text NOT NULL,
+	"enforcement" text DEFAULT 'optional' NOT NULL,
+	"max_session_minutes" integer,
+	"idp_entity_id" text,
+	"idp_sso_url" text,
+	"idp_certificates" text[] DEFAULT '{}'::text[] NOT NULL,
+	"subject_attribute" text,
+	"oidc_issuer" text,
+	"oidc_client_id" text,
+	"oidc_client_secret" text,
+	"tested_at" timestamp with time zone,
+	"tested_config_digest" text,
+	"created_at" timestamp with time zone NOT NULL,
+	"updated_at" timestamp with time zone NOT NULL,
+	CONSTRAINT "school_sso_connections_public_id_unique" UNIQUE("public_id"),
+	CONSTRAINT "school_sso_connections_protocol_check" CHECK ("school_sso_connections"."protocol" IN ('saml', 'oidc')),
+	CONSTRAINT "school_sso_connections_status_check" CHECK ("school_sso_connections"."status" IN ('draft', 'active', 'suspended', 'disabled')),
+	CONSTRAINT "school_sso_connections_enforcement_check" CHECK ("school_sso_connections"."enforcement" IN ('optional', 'required_for_domains'))
+);
+--> statement-breakpoint
+CREATE TABLE "school_sso_domains" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"connection_id" uuid NOT NULL,
+	"school_id" uuid NOT NULL,
+	"domain" text NOT NULL,
+	"verification_token" text NOT NULL,
+	"verified_at" timestamp with time zone,
+	"consecutive_check_failures" integer DEFAULT 0 NOT NULL,
+	"last_checked_at" timestamp with time zone,
+	"created_at" timestamp with time zone NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "school_sso_events" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"school_id" uuid NOT NULL,
+	"connection_id" uuid,
+	"actor_school_account_id" uuid,
+	"action" text NOT NULL,
+	"reason" text,
+	"metadata" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"created_at" timestamp with time zone NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "school_sso_identities" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"school_id" uuid NOT NULL,
+	"connection_id" uuid NOT NULL,
+	"issuer" text NOT NULL,
+	"subject" text NOT NULL,
+	"school_account_id" uuid NOT NULL,
+	"last_email" text NOT NULL,
+	"last_signed_in_at" timestamp with time zone,
+	"created_at" timestamp with time zone NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "school_sso_requests" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"request_digest" text NOT NULL,
+	"school_id" uuid NOT NULL,
+	"connection_id" uuid NOT NULL,
+	"nonce_digest" text NOT NULL,
+	"return_origin" text NOT NULL,
+	"next_path" text NOT NULL,
+	"protocol_request_id" text,
+	"oidc_nonce" text,
+	"pkce_verifier" text,
+	"purpose" text DEFAULT 'sign_in' NOT NULL,
+	"started_by_school_account_id" uuid,
+	"test_result" jsonb,
+	"test_result_expires_at" timestamp with time zone,
+	"expires_at" timestamp with time zone NOT NULL,
+	"consumed_at" timestamp with time zone,
+	"created_at" timestamp with time zone NOT NULL,
+	CONSTRAINT "school_sso_requests_request_digest_unique" UNIQUE("request_digest"),
+	CONSTRAINT "school_sso_requests_purpose_check" CHECK ("school_sso_requests"."purpose" IN ('sign_in', 'test'))
+);
+--> statement-breakpoint
+CREATE TABLE "sso_shadow_users" (
+	"user_id" text PRIMARY KEY NOT NULL,
+	"school_id" uuid NOT NULL,
+	"created_at" timestamp with time zone NOT NULL
+);
+--> statement-breakpoint
 ALTER TABLE "section_drip_email_deliveries" ADD CONSTRAINT "section_drip_email_deliveries_school_id_schools_id_fk" FOREIGN KEY ("school_id") REFERENCES "public"."schools"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "section_drip_email_deliveries" ADD CONSTRAINT "section_drip_email_deliveries_section_id_product_sections_id_fk" FOREIGN KEY ("section_id") REFERENCES "public"."product_sections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "section_drip_email_deliveries" ADD CONSTRAINT "section_drip_email_deliveries_membership_id_learner_memberships_id_fk" FOREIGN KEY ("membership_id") REFERENCES "public"."learner_memberships"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "section_drip_emails" ADD CONSTRAINT "section_drip_emails_section_id_product_sections_id_fk" FOREIGN KEY ("section_id") REFERENCES "public"."product_sections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "section_drip_emails" ADD CONSTRAINT "section_drip_emails_school_id_schools_id_fk" FOREIGN KEY ("school_id") REFERENCES "public"."schools"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_sso_assertion_ids" ADD CONSTRAINT "school_sso_assertion_ids_connection_id_school_sso_connections_id_fk" FOREIGN KEY ("connection_id") REFERENCES "public"."school_sso_connections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_sso_connections" ADD CONSTRAINT "school_sso_connections_school_id_schools_id_fk" FOREIGN KEY ("school_id") REFERENCES "public"."schools"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_sso_domains" ADD CONSTRAINT "school_sso_domains_connection_id_school_sso_connections_id_fk" FOREIGN KEY ("connection_id") REFERENCES "public"."school_sso_connections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_sso_domains" ADD CONSTRAINT "school_sso_domains_school_id_schools_id_fk" FOREIGN KEY ("school_id") REFERENCES "public"."schools"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_sso_events" ADD CONSTRAINT "school_sso_events_school_id_schools_id_fk" FOREIGN KEY ("school_id") REFERENCES "public"."schools"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_sso_events" ADD CONSTRAINT "school_sso_events_connection_id_school_sso_connections_id_fk" FOREIGN KEY ("connection_id") REFERENCES "public"."school_sso_connections"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_sso_events" ADD CONSTRAINT "school_sso_events_actor_school_account_id_school_accounts_id_fk" FOREIGN KEY ("actor_school_account_id") REFERENCES "public"."school_accounts"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_sso_identities" ADD CONSTRAINT "school_sso_identities_school_id_schools_id_fk" FOREIGN KEY ("school_id") REFERENCES "public"."schools"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_sso_identities" ADD CONSTRAINT "school_sso_identities_connection_id_school_sso_connections_id_fk" FOREIGN KEY ("connection_id") REFERENCES "public"."school_sso_connections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_sso_identities" ADD CONSTRAINT "school_sso_identities_school_account_id_school_accounts_id_fk" FOREIGN KEY ("school_account_id") REFERENCES "public"."school_accounts"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_sso_requests" ADD CONSTRAINT "school_sso_requests_school_id_schools_id_fk" FOREIGN KEY ("school_id") REFERENCES "public"."schools"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_sso_requests" ADD CONSTRAINT "school_sso_requests_connection_id_school_sso_connections_id_fk" FOREIGN KEY ("connection_id") REFERENCES "public"."school_sso_connections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_sso_requests" ADD CONSTRAINT "school_sso_requests_started_by_school_account_id_school_accounts_id_fk" FOREIGN KEY ("started_by_school_account_id") REFERENCES "public"."school_accounts"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "sso_shadow_users" ADD CONSTRAINT "sso_shadow_users_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "sso_shadow_users" ADD CONSTRAINT "sso_shadow_users_school_id_schools_id_fk" FOREIGN KEY ("school_id") REFERENCES "public"."schools"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_auth_tickets" ADD CONSTRAINT "school_auth_tickets_sso_connection_id_school_sso_connections_id_fk" FOREIGN KEY ("sso_connection_id") REFERENCES "public"."school_sso_connections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "school_sessions" ADD CONSTRAINT "school_sessions_sso_connection_id_school_sso_connections_id_fk" FOREIGN KEY ("sso_connection_id") REFERENCES "public"."school_sso_connections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 CREATE UNIQUE INDEX "section_drip_email_deliveries_uidx" ON "section_drip_email_deliveries" USING btree ("section_id","membership_id");--> statement-breakpoint
-CREATE INDEX "school_login_codes_school_email_idx" ON "school_login_codes" USING btree ("school_id","email","created_at");
+CREATE INDEX "school_login_codes_school_email_idx" ON "school_login_codes" USING btree ("school_id","email","created_at");--> statement-breakpoint
+CREATE INDEX "school_sso_assertion_ids_expires_idx" ON "school_sso_assertion_ids" USING btree ("expires_at");--> statement-breakpoint
+CREATE INDEX "school_sso_connections_school_idx" ON "school_sso_connections" USING btree ("school_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "school_sso_connections_one_active_uidx" ON "school_sso_connections" USING btree ("school_id") WHERE "school_sso_connections"."status" = 'active';--> statement-breakpoint
+CREATE UNIQUE INDEX "school_sso_domains_school_domain_uidx" ON "school_sso_domains" USING btree ("school_id","domain");--> statement-breakpoint
+CREATE INDEX "school_sso_domains_connection_idx" ON "school_sso_domains" USING btree ("connection_id");--> statement-breakpoint
+CREATE INDEX "school_sso_events_school_created_idx" ON "school_sso_events" USING btree ("school_id","created_at");--> statement-breakpoint
+CREATE UNIQUE INDEX "school_sso_identities_connection_subject_uidx" ON "school_sso_identities" USING btree ("connection_id","subject");--> statement-breakpoint
+CREATE UNIQUE INDEX "school_sso_identities_connection_account_uidx" ON "school_sso_identities" USING btree ("connection_id","school_account_id");--> statement-breakpoint
+CREATE INDEX "school_sso_identities_account_idx" ON "school_sso_identities" USING btree ("school_account_id");--> statement-breakpoint
+CREATE INDEX "school_sso_requests_connection_idx" ON "school_sso_requests" USING btree ("connection_id");
diff --git a/apps/api/drizzle/meta/0000_snapshot.json b/apps/api/drizzle/meta/0000_snapshot.json
index cb6c74ac7..82a9afd85 100644
--- a/apps/api/drizzle/meta/0000_snapshot.json
+++ b/apps/api/drizzle/meta/0000_snapshot.json
@@ -1,5 +1,5 @@
 {
-  "id": "37b35a5c-0571-4933-a750-58e9fc4c055c",
+  "id": "8f68a5f8-20e9-4e22-bf51-f83cb1ec81dd",
   "prevId": "00000000-0000-0000-0000-000000000000",
   "version": "7",
   "dialect": "postgresql",
@@ -4704,6 +4704,13 @@
           "primaryKey": false,
           "notNull": true
         },
+        "refunded_amount_minor": {
+          "name": "refunded_amount_minor",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
         "occurred_at": {
           "name": "occurred_at",
           "type": "timestamp with time zone",
@@ -6315,74 +6322,1101 @@
           "name": "discussions",
           "type": "boolean",
           "primaryKey": false,
-          "notNull": true,
-          "default": false
+          "notNull": true,
+          "default": false
+        },
+        "new_lesson_status": {
+          "name": "new_lesson_status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'draft'"
+        },
+        "included_with_community": {
+          "name": "included_with_community",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "discussion_space_id": {
+          "name": "discussion_space_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by": {
+          "name": "created_by",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "published_at": {
+          "name": "published_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "products_school_slug_uidx": {
+          "name": "products_school_slug_uidx",
+          "columns": [
+            {
+              "expression": "school_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "slug",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "products_school_id_schools_id_fk": {
+          "name": "products_school_id_schools_id_fk",
+          "tableFrom": "products",
+          "tableTo": "schools",
+          "columnsFrom": [
+            "school_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "products_created_by_user_id_fk": {
+          "name": "products_created_by_user_id_fk",
+          "tableFrom": "products",
+          "tableTo": "user",
+          "columnsFrom": [
+            "created_by"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "no action",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "products_public_id_unique": {
+          "name": "products_public_id_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "public_id"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.rate_limit_events": {
+      "name": "rate_limit_events",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "school_id": {
+          "name": "school_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "scope": {
+          "name": "scope",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "action": {
+          "name": "action",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "subject_id": {
+          "name": "subject_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "fingerprint": {
+          "name": "fingerprint",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "rate_limit_events_lookup_idx": {
+          "name": "rate_limit_events_lookup_idx",
+          "columns": [
+            {
+              "expression": "school_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "scope",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "action",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "subject_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "rate_limit_events_fingerprint_idx": {
+          "name": "rate_limit_events_fingerprint_idx",
+          "columns": [
+            {
+              "expression": "school_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "scope",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "subject_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "fingerprint",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "rate_limit_events_school_id_schools_id_fk": {
+          "name": "rate_limit_events_school_id_schools_id_fk",
+          "tableFrom": "rate_limit_events",
+          "tableTo": "schools",
+          "columnsFrom": [
+            "school_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.school_sso_assertion_ids": {
+      "name": "school_sso_assertion_ids",
+      "schema": "",
+      "columns": {
+        "connection_id": {
+          "name": "connection_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "assertion_id": {
+          "name": "assertion_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "school_sso_assertion_ids_expires_idx": {
+          "name": "school_sso_assertion_ids_expires_idx",
+          "columns": [
+            {
+              "expression": "expires_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "school_sso_assertion_ids_connection_id_school_sso_connections_id_fk": {
+          "name": "school_sso_assertion_ids_connection_id_school_sso_connections_id_fk",
+          "tableFrom": "school_sso_assertion_ids",
+          "tableTo": "school_sso_connections",
+          "columnsFrom": [
+            "connection_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "school_sso_assertion_ids_connection_id_assertion_id_pk": {
+          "name": "school_sso_assertion_ids_connection_id_assertion_id_pk",
+          "columns": [
+            "connection_id",
+            "assertion_id"
+          ]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.school_sso_connections": {
+      "name": "school_sso_connections",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "public_id": {
+          "name": "public_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "school_id": {
+          "name": "school_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "protocol": {
+          "name": "protocol",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'draft'"
+        },
+        "display_name": {
+          "name": "display_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "enforcement": {
+          "name": "enforcement",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'optional'"
+        },
+        "max_session_minutes": {
+          "name": "max_session_minutes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "idp_entity_id": {
+          "name": "idp_entity_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "idp_sso_url": {
+          "name": "idp_sso_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "idp_certificates": {
+          "name": "idp_certificates",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::text[]"
+        },
+        "subject_attribute": {
+          "name": "subject_attribute",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "oidc_issuer": {
+          "name": "oidc_issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "oidc_client_id": {
+          "name": "oidc_client_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "oidc_client_secret": {
+          "name": "oidc_client_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "tested_at": {
+          "name": "tested_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "tested_config_digest": {
+          "name": "tested_config_digest",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "school_sso_connections_school_idx": {
+          "name": "school_sso_connections_school_idx",
+          "columns": [
+            {
+              "expression": "school_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "school_sso_connections_one_active_uidx": {
+          "name": "school_sso_connections_one_active_uidx",
+          "columns": [
+            {
+              "expression": "school_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"school_sso_connections\".\"status\" = 'active'",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "school_sso_connections_school_id_schools_id_fk": {
+          "name": "school_sso_connections_school_id_schools_id_fk",
+          "tableFrom": "school_sso_connections",
+          "tableTo": "schools",
+          "columnsFrom": [
+            "school_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "school_sso_connections_public_id_unique": {
+          "name": "school_sso_connections_public_id_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "public_id"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "school_sso_connections_protocol_check": {
+          "name": "school_sso_connections_protocol_check",
+          "value": "\"school_sso_connections\".\"protocol\" IN ('saml', 'oidc')"
+        },
+        "school_sso_connections_status_check": {
+          "name": "school_sso_connections_status_check",
+          "value": "\"school_sso_connections\".\"status\" IN ('draft', 'active', 'suspended', 'disabled')"
+        },
+        "school_sso_connections_enforcement_check": {
+          "name": "school_sso_connections_enforcement_check",
+          "value": "\"school_sso_connections\".\"enforcement\" IN ('optional', 'required_for_domains')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.school_sso_domains": {
+      "name": "school_sso_domains",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "connection_id": {
+          "name": "connection_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "school_id": {
+          "name": "school_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "domain": {
+          "name": "domain",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "verification_token": {
+          "name": "verification_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "verified_at": {
+          "name": "verified_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "consecutive_check_failures": {
+          "name": "consecutive_check_failures",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "last_checked_at": {
+          "name": "last_checked_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "school_sso_domains_school_domain_uidx": {
+          "name": "school_sso_domains_school_domain_uidx",
+          "columns": [
+            {
+              "expression": "school_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "domain",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "school_sso_domains_connection_idx": {
+          "name": "school_sso_domains_connection_idx",
+          "columns": [
+            {
+              "expression": "connection_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "school_sso_domains_connection_id_school_sso_connections_id_fk": {
+          "name": "school_sso_domains_connection_id_school_sso_connections_id_fk",
+          "tableFrom": "school_sso_domains",
+          "tableTo": "school_sso_connections",
+          "columnsFrom": [
+            "connection_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "school_sso_domains_school_id_schools_id_fk": {
+          "name": "school_sso_domains_school_id_schools_id_fk",
+          "tableFrom": "school_sso_domains",
+          "tableTo": "schools",
+          "columnsFrom": [
+            "school_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.school_sso_events": {
+      "name": "school_sso_events",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "school_id": {
+          "name": "school_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "connection_id": {
+          "name": "connection_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "actor_school_account_id": {
+          "name": "actor_school_account_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "action": {
+          "name": "action",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reason": {
+          "name": "reason",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "school_sso_events_school_created_idx": {
+          "name": "school_sso_events_school_created_idx",
+          "columns": [
+            {
+              "expression": "school_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "school_sso_events_school_id_schools_id_fk": {
+          "name": "school_sso_events_school_id_schools_id_fk",
+          "tableFrom": "school_sso_events",
+          "tableTo": "schools",
+          "columnsFrom": [
+            "school_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "school_sso_events_connection_id_school_sso_connections_id_fk": {
+          "name": "school_sso_events_connection_id_school_sso_connections_id_fk",
+          "tableFrom": "school_sso_events",
+          "tableTo": "school_sso_connections",
+          "columnsFrom": [
+            "connection_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "school_sso_events_actor_school_account_id_school_accounts_id_fk": {
+          "name": "school_sso_events_actor_school_account_id_school_accounts_id_fk",
+          "tableFrom": "school_sso_events",
+          "tableTo": "school_accounts",
+          "columnsFrom": [
+            "actor_school_account_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.school_sso_identities": {
+      "name": "school_sso_identities",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "school_id": {
+          "name": "school_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "connection_id": {
+          "name": "connection_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "issuer": {
+          "name": "issuer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "subject": {
+          "name": "subject",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "school_account_id": {
+          "name": "school_account_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_email": {
+          "name": "last_email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_signed_in_at": {
+          "name": "last_signed_in_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "school_sso_identities_connection_subject_uidx": {
+          "name": "school_sso_identities_connection_subject_uidx",
+          "columns": [
+            {
+              "expression": "connection_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "subject",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "school_sso_identities_connection_account_uidx": {
+          "name": "school_sso_identities_connection_account_uidx",
+          "columns": [
+            {
+              "expression": "connection_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "school_account_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "school_sso_identities_account_idx": {
+          "name": "school_sso_identities_account_idx",
+          "columns": [
+            {
+              "expression": "school_account_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "school_sso_identities_school_id_schools_id_fk": {
+          "name": "school_sso_identities_school_id_schools_id_fk",
+          "tableFrom": "school_sso_identities",
+          "tableTo": "schools",
+          "columnsFrom": [
+            "school_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "school_sso_identities_connection_id_school_sso_connections_id_fk": {
+          "name": "school_sso_identities_connection_id_school_sso_connections_id_fk",
+          "tableFrom": "school_sso_identities",
+          "tableTo": "school_sso_connections",
+          "columnsFrom": [
+            "connection_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "school_sso_identities_school_account_id_school_accounts_id_fk": {
+          "name": "school_sso_identities_school_account_id_school_accounts_id_fk",
+          "tableFrom": "school_sso_identities",
+          "tableTo": "school_accounts",
+          "columnsFrom": [
+            "school_account_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.school_sso_requests": {
+      "name": "school_sso_requests",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "request_digest": {
+          "name": "request_digest",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "school_id": {
+          "name": "school_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "connection_id": {
+          "name": "connection_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "nonce_digest": {
+          "name": "nonce_digest",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "return_origin": {
+          "name": "return_origin",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "next_path": {
+          "name": "next_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "protocol_request_id": {
+          "name": "protocol_request_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "oidc_nonce": {
+          "name": "oidc_nonce",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "pkce_verifier": {
+          "name": "pkce_verifier",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
         },
-        "included_with_community": {
-          "name": "included_with_community",
-          "type": "boolean",
+        "purpose": {
+          "name": "purpose",
+          "type": "text",
           "primaryKey": false,
           "notNull": true,
-          "default": false
+          "default": "'sign_in'"
         },
-        "discussion_space_id": {
-          "name": "discussion_space_id",
+        "started_by_school_account_id": {
+          "name": "started_by_school_account_id",
           "type": "uuid",
           "primaryKey": false,
           "notNull": false
         },
-        "created_by": {
-          "name": "created_by",
-          "type": "text",
+        "test_result": {
+          "name": "test_result",
+          "type": "jsonb",
           "primaryKey": false,
-          "notNull": true
+          "notNull": false
         },
-        "published_at": {
-          "name": "published_at",
+        "test_result_expires_at": {
+          "name": "test_result_expires_at",
           "type": "timestamp with time zone",
           "primaryKey": false,
           "notNull": false
         },
-        "created_at": {
-          "name": "created_at",
+        "expires_at": {
+          "name": "expires_at",
           "type": "timestamp with time zone",
           "primaryKey": false,
           "notNull": true
         },
-        "updated_at": {
-          "name": "updated_at",
+        "consumed_at": {
+          "name": "consumed_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
           "type": "timestamp with time zone",
           "primaryKey": false,
           "notNull": true
         }
       },
       "indexes": {
-        "products_school_slug_uidx": {
-          "name": "products_school_slug_uidx",
+        "school_sso_requests_connection_idx": {
+          "name": "school_sso_requests_connection_idx",
           "columns": [
             {
-              "expression": "school_id",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            },
-            {
-              "expression": "slug",
+              "expression": "connection_id",
               "isExpression": false,
               "asc": true,
               "nulls": "last"
             }
           ],
-          "isUnique": true,
+          "isUnique": false,
           "concurrently": false,
           "method": "btree",
           "with": {}
         }
       },
       "foreignKeys": {
-        "products_school_id_schools_id_fk": {
-          "name": "products_school_id_schools_id_fk",
-          "tableFrom": "products",
+        "school_sso_requests_school_id_schools_id_fk": {
+          "name": "school_sso_requests_school_id_schools_id_fk",
+          "tableFrom": "school_sso_requests",
           "tableTo": "schools",
           "columnsFrom": [
             "school_id"
@@ -6393,41 +7427,59 @@
           "onDelete": "cascade",
           "onUpdate": "no action"
         },
-        "products_created_by_user_id_fk": {
-          "name": "products_created_by_user_id_fk",
-          "tableFrom": "products",
-          "tableTo": "user",
+        "school_sso_requests_connection_id_school_sso_connections_id_fk": {
+          "name": "school_sso_requests_connection_id_school_sso_connections_id_fk",
+          "tableFrom": "school_sso_requests",
+          "tableTo": "school_sso_connections",
           "columnsFrom": [
-            "created_by"
+            "connection_id"
           ],
           "columnsTo": [
             "id"
           ],
-          "onDelete": "no action",
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "school_sso_requests_started_by_school_account_id_school_accounts_id_fk": {
+          "name": "school_sso_requests_started_by_school_account_id_school_accounts_id_fk",
+          "tableFrom": "school_sso_requests",
+          "tableTo": "school_accounts",
+          "columnsFrom": [
+            "started_by_school_account_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
           "onUpdate": "no action"
         }
       },
       "compositePrimaryKeys": {},
       "uniqueConstraints": {
-        "products_public_id_unique": {
-          "name": "products_public_id_unique",
+        "school_sso_requests_request_digest_unique": {
+          "name": "school_sso_requests_request_digest_unique",
           "nullsNotDistinct": false,
           "columns": [
-            "public_id"
+            "request_digest"
           ]
         }
       },
       "policies": {},
-      "checkConstraints": {},
+      "checkConstraints": {
+        "school_sso_requests_purpose_check": {
+          "name": "school_sso_requests_purpose_check",
+          "value": "\"school_sso_requests\".\"purpose\" IN ('sign_in', 'test')"
+        }
+      },
       "isRLSEnabled": false
     },
-    "public.rate_limit_events": {
-      "name": "rate_limit_events",
+    "public.sso_shadow_users": {
+      "name": "sso_shadow_users",
       "schema": "",
       "columns": {
-        "id": {
-          "name": "id",
-          "type": "uuid",
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
           "primaryKey": true,
           "notNull": true
         },
@@ -6437,36 +7489,6 @@
           "primaryKey": false,
           "notNull": true
         },
-        "user_id": {
-          "name": "user_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true
-        },
-        "scope": {
-          "name": "scope",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true
-        },
-        "action": {
-          "name": "action",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true
-        },
-        "subject_id": {
-          "name": "subject_id",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true
-        },
-        "fingerprint": {
-          "name": "fingerprint",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false
-        },
         "created_at": {
           "name": "created_at",
           "type": "timestamp with time zone",
@@ -6474,102 +7496,24 @@
           "notNull": true
         }
       },
-      "indexes": {
-        "rate_limit_events_lookup_idx": {
-          "name": "rate_limit_events_lookup_idx",
-          "columns": [
-            {
-              "expression": "school_id",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            },
-            {
-              "expression": "user_id",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            },
-            {
-              "expression": "scope",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            },
-            {
-              "expression": "action",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            },
-            {
-              "expression": "subject_id",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            },
-            {
-              "expression": "created_at",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            }
+      "indexes": {},
+      "foreignKeys": {
+        "sso_shadow_users_user_id_user_id_fk": {
+          "name": "sso_shadow_users_user_id_user_id_fk",
+          "tableFrom": "sso_shadow_users",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
           ],
-          "isUnique": false,
-          "concurrently": false,
-          "method": "btree",
-          "with": {}
-        },
-        "rate_limit_events_fingerprint_idx": {
-          "name": "rate_limit_events_fingerprint_idx",
-          "columns": [
-            {
-              "expression": "school_id",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            },
-            {
-              "expression": "user_id",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            },
-            {
-              "expression": "scope",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            },
-            {
-              "expression": "subject_id",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            },
-            {
-              "expression": "fingerprint",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            },
-            {
-              "expression": "created_at",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            }
+          "columnsTo": [
+            "id"
           ],
-          "isUnique": false,
-          "concurrently": false,
-          "method": "btree",
-          "with": {}
-        }
-      },
-      "foreignKeys": {
-        "rate_limit_events_school_id_schools_id_fk": {
-          "name": "rate_limit_events_school_id_schools_id_fk",
-          "tableFrom": "rate_limit_events",
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "sso_shadow_users_school_id_schools_id_fk": {
+          "name": "sso_shadow_users_school_id_schools_id_fk",
+          "tableFrom": "sso_shadow_users",
           "tableTo": "schools",
           "columnsFrom": [
             "school_id"
@@ -7400,6 +8344,18 @@
           "primaryKey": false,
           "notNull": true
         },
+        "sso_connection_id": {
+          "name": "sso_connection_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "session_expires_at": {
+          "name": "session_expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
         "expires_at": {
           "name": "expires_at",
           "type": "timestamp with time zone",
@@ -7459,6 +8415,19 @@
           ],
           "onDelete": "cascade",
           "onUpdate": "no action"
+        },
+        "school_auth_tickets_sso_connection_id_school_sso_connections_id_fk": {
+          "name": "school_auth_tickets_sso_connection_id_school_sso_connections_id_fk",
+          "tableFrom": "school_auth_tickets",
+          "tableTo": "school_sso_connections",
+          "columnsFrom": [
+            "sso_connection_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
         }
       },
       "compositePrimaryKeys": {},
@@ -7926,6 +8895,12 @@
           "primaryKey": false,
           "notNull": true
         },
+        "sso_connection_id": {
+          "name": "sso_connection_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
         "authenticated_at": {
           "name": "authenticated_at",
           "type": "timestamp with time zone",
@@ -8007,6 +8982,19 @@
           ],
           "onDelete": "cascade",
           "onUpdate": "no action"
+        },
+        "school_sessions_sso_connection_id_school_sso_connections_id_fk": {
+          "name": "school_sessions_sso_connection_id_school_sso_connections_id_fk",
+          "tableFrom": "school_sessions",
+          "tableTo": "school_sso_connections",
+          "columnsFrom": [
+            "sso_connection_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
         }
       },
       "compositePrimaryKeys": {},
@@ -8065,6 +9053,13 @@
           "notNull": true,
           "default": "'en'"
         },
+        "login_methods": {
+          "name": "login_methods",
+          "type": "text[]",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{email}'::text[]"
+        },
         "currency": {
           "name": "currency",
           "type": "text",
@@ -8125,7 +9120,12 @@
         }
       },
       "policies": {},
-      "checkConstraints": {},
+      "checkConstraints": {
+        "schools_login_methods_check": {
+          "name": "schools_login_methods_check",
+          "value": "\"schools\".\"login_methods\" <@ ARRAY['email', 'google']::text[]"
+        }
+      },
       "isRLSEnabled": false
     },
     "public.selected_schools": {
@@ -9419,6 +10419,13 @@
           "primaryKey": false,
           "notNull": true
         },
+        "refunded_amount_minor": {
+          "name": "refunded_amount_minor",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
         "occurred_at": {
           "name": "occurred_at",
           "type": "timestamp with time zone",
@@ -12569,4 +13576,4 @@
     "schemas": {},
     "tables": {}
   }
-}
+}
\ No newline at end of file
diff --git a/apps/api/openapi.json b/apps/api/openapi.json
index c308e9aee..7fff747f3 100644
--- a/apps/api/openapi.json
+++ b/apps/api/openapi.json
@@ -44962,18 +44962,28 @@
                         "type": "string",
                         "enum": [
                           "email",
-                          "google"
+                          "google",
+                          "sso"
                         ]
                       }
                     },
                     "hasGoogle": {
                       "type": "boolean"
+                    },
+                    "hasSso": {
+                      "type": "boolean"
+                    },
+                    "ssoDisplayName": {
+                      "type": "string",
+                      "nullable": true
                     }
                   },
                   "required": [
                     "schoolId",
                     "loginMethods",
-                    "hasGoogle"
+                    "hasGoogle",
+                    "hasSso",
+                    "ssoDisplayName"
                   ]
                 }
               }
@@ -57403,9 +57413,9 @@
         "security": []
       }
     },
-    "/v1/auth/tickets/consume": {
+    "/v1/learner/auth/sso": {
       "post": {
-        "summary": "Swap a sign-in ticket for a school session",
+        "summary": "Start single sign-on for a school website",
         "tags": [
           "Learners"
         ],
@@ -57417,14 +57427,24 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "ticket": {
+                  "host": {
                     "type": "string",
                     "minLength": 1,
+                    "maxLength": 260
+                  },
+                  "nonce": {
+                    "type": "string",
+                    "minLength": 32,
                     "maxLength": 200
+                  },
+                  "next": {
+                    "type": "string",
+                    "maxLength": 1000
                   }
                 },
                 "required": [
-                  "ticket"
+                  "host",
+                  "nonce"
                 ]
               }
             }
@@ -57438,44 +57458,13 @@
                 "schema": {
                   "type": "object",
                   "properties": {
-                    "id": {
-                      "type": "string"
-                    },
-                    "schoolId": {
-                      "type": "string"
-                    },
-                    "email": {
-                      "type": "string",
-                      "format": "email"
-                    },
-                    "name": {
-                      "type": "string"
-                    },
-                    "avatarMediaId": {
-                      "type": "string",
-                      "nullable": true
-                    },
-                    "image": {
+                    "url": {
                       "type": "string",
-                      "format": "uri",
-                      "nullable": true
-                    },
-                    "bio": {
-                      "type": "string"
-                    },
-                    "emailUpdatesEnabled": {
-                      "type": "boolean"
+                      "format": "uri"
                     }
                   },
                   "required": [
-                    "id",
-                    "schoolId",
-                    "email",
-                    "name",
-                    "avatarMediaId",
-                    "image",
-                    "bio",
-                    "emailUpdatesEnabled"
+                    "url"
                   ]
                 }
               }
@@ -57537,8 +57526,8 @@
               }
             }
           },
-          "401": {
-            "description": "401",
+          "403": {
+            "description": "403",
             "content": {
               "application/json": {
                 "schema": {
@@ -57592,40 +57581,65 @@
                 }
               }
             }
-          }
-        },
-        "security": []
-      }
-    },
-    "/v1/learner/auth/sign-out": {
-      "post": {
-        "tags": [
-          "Learners"
-        ],
-        "parameters": [],
-        "requestBody": {
-          "description": "Body",
-          "content": {
-            "application/json": {
-              "schema": {
-                "default": {},
-                "type": "object",
-                "properties": {}
-              }
-            }
-          }
-        },
-        "responses": {
-          "204": {
-            "description": "204",
+          },
+          "404": {
+            "description": "404",
             "content": {
               "application/json": {
-                "schema": {}
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
               }
             }
           },
-          "401": {
-            "description": "401",
+          "429": {
+            "description": "429",
             "content": {
               "application/json": {
                 "schema": {
@@ -57684,12 +57698,33 @@
         "security": []
       }
     },
-    "/v1/learner/me": {
-      "get": {
+    "/v1/auth/tickets/consume": {
+      "post": {
+        "summary": "Swap a sign-in ticket for a school session",
         "tags": [
           "Learners"
         ],
         "parameters": [],
+        "requestBody": {
+          "description": "Body",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "ticket": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200
+                  }
+                },
+                "required": [
+                  "ticket"
+                ]
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
             "description": "200",
@@ -57741,6 +57776,62 @@
               }
             }
           },
+          "400": {
+            "description": "400",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
           "401": {
             "description": "401",
             "content": {
@@ -57796,9 +57887,40 @@
                 }
               }
             }
+          }
+        },
+        "security": []
+      }
+    },
+    "/v1/learner/auth/sign-out": {
+      "post": {
+        "tags": [
+          "Learners"
+        ],
+        "parameters": [],
+        "requestBody": {
+          "description": "Body",
+          "content": {
+            "application/json": {
+              "schema": {
+                "default": {},
+                "type": "object",
+                "properties": {}
+              }
+            }
+          }
+        },
+        "responses": {
+          "204": {
+            "description": "204",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
           },
-          "403": {
-            "description": "403",
+          "401": {
+            "description": "401",
             "content": {
               "application/json": {
                 "schema": {
@@ -57855,48 +57977,14 @@
           }
         },
         "security": []
-      },
-      "patch": {
+      }
+    },
+    "/v1/learner/me": {
+      "get": {
         "tags": [
           "Learners"
         ],
         "parameters": [],
-        "requestBody": {
-          "description": "Body",
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "name": {
-                    "type": "string",
-                    "minLength": 1,
-                    "maxLength": 200
-                  },
-                  "avatarMediaId": {
-                    "type": "string",
-                    "nullable": true
-                  },
-                  "image": {
-                    "type": "string",
-                    "format": "uri",
-                    "nullable": true
-                  },
-                  "bio": {
-                    "type": "string",
-                    "maxLength": 2000
-                  },
-                  "emailUpdatesEnabled": {
-                    "type": "boolean"
-                  }
-                },
-                "required": [
-                  "name"
-                ]
-              }
-            }
-          }
-        },
         "responses": {
           "200": {
             "description": "200",
@@ -57948,62 +58036,6 @@
               }
             }
           },
-          "400": {
-            "description": "400",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "code": {
-                      "type": "string",
-                      "enum": [
-                        "unauthenticated",
-                        "credential_ambiguous",
-                        "tenant_required",
-                        "tenant_forbidden",
-                        "forbidden",
-                        "not_found",
-                        "conflict",
-                        "validation_failed",
-                        "rate_limited",
-                        "internal_error"
-                      ]
-                    },
-                    "message": {
-                      "type": "string"
-                    },
-                    "details": {
-                      "type": "object",
-                      "additionalProperties": {
-                        "oneOf": [
-                          {
-                            "type": "string"
-                          },
-                          {
-                            "type": "number"
-                          },
-                          {
-                            "type": "boolean"
-                          },
-                          {
-                            "type": "string",
-                            "format": "null",
-                            "nullable": true
-                          }
-                        ],
-                        "nullable": true
-                      }
-                    }
-                  },
-                  "required": [
-                    "code",
-                    "message"
-                  ]
-                }
-              }
-            }
-          },
           "401": {
             "description": "401",
             "content": {
@@ -58118,10 +58150,8 @@
           }
         },
         "security": []
-      }
-    },
-    "/v1/learner/memberships": {
-      "post": {
+      },
+      "patch": {
         "tags": [
           "Learners"
         ],
@@ -58133,21 +58163,38 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "productId": {
+                  "name": {
                     "type": "string",
-                    "minLength": 1
+                    "minLength": 1,
+                    "maxLength": 200
+                  },
+                  "avatarMediaId": {
+                    "type": "string",
+                    "nullable": true
+                  },
+                  "image": {
+                    "type": "string",
+                    "format": "uri",
+                    "nullable": true
+                  },
+                  "bio": {
+                    "type": "string",
+                    "maxLength": 2000
+                  },
+                  "emailUpdatesEnabled": {
+                    "type": "boolean"
                   }
                 },
                 "required": [
-                  "productId"
+                  "name"
                 ]
               }
             }
           }
         },
         "responses": {
-          "201": {
-            "description": "201",
+          "200": {
+            "description": "200",
             "content": {
               "application/json": {
                 "schema": {
@@ -58159,72 +58206,38 @@
                     "schoolId": {
                       "type": "string"
                     },
-                    "entityType": {
+                    "email": {
                       "type": "string",
-                      "enum": [
-                        "product",
-                        "community"
-                      ]
+                      "format": "email"
                     },
-                    "entityId": {
+                    "name": {
                       "type": "string"
                     },
-                    "paymentPlanId": {
-                      "type": "string",
-                      "nullable": true
-                    },
-                    "status": {
-                      "type": "string",
-                      "enum": [
-                        "active",
-                        "payment_failed",
-                        "expired",
-                        "pending",
-                        "rejected",
-                        "paused"
-                      ]
-                    },
-                    "role": {
-                      "type": "string",
-                      "enum": [
-                        "comment",
-                        "post",
-                        "moderate"
-                      ],
-                      "nullable": true
-                    },
-                    "subscriptionId": {
+                    "avatarMediaId": {
                       "type": "string",
                       "nullable": true
                     },
-                    "subscriptionMethod": {
+                    "image": {
                       "type": "string",
+                      "format": "uri",
                       "nullable": true
                     },
-                    "joiningReason": {
+                    "bio": {
                       "type": "string"
                     },
-                    "rejectionReason": {
-                      "type": "string",
-                      "nullable": true
-                    },
-                    "isIncludedInPlan": {
+                    "emailUpdatesEnabled": {
                       "type": "boolean"
                     }
                   },
                   "required": [
                     "id",
                     "schoolId",
-                    "entityType",
-                    "entityId",
-                    "paymentPlanId",
-                    "status",
-                    "role",
-                    "subscriptionId",
-                    "subscriptionMethod",
-                    "joiningReason",
-                    "rejectionReason",
-                    "isIncludedInPlan"
+                    "email",
+                    "name",
+                    "avatarMediaId",
+                    "image",
+                    "bio",
+                    "emailUpdatesEnabled"
                   ]
                 }
               }
@@ -58397,90 +58410,32 @@
                 }
               }
             }
-          },
-          "404": {
-            "description": "404",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "code": {
-                      "type": "string",
-                      "enum": [
-                        "unauthenticated",
-                        "credential_ambiguous",
-                        "tenant_required",
-                        "tenant_forbidden",
-                        "forbidden",
-                        "not_found",
-                        "conflict",
-                        "validation_failed",
-                        "rate_limited",
-                        "internal_error"
-                      ]
-                    },
-                    "message": {
-                      "type": "string"
-                    },
-                    "details": {
-                      "type": "object",
-                      "additionalProperties": {
-                        "oneOf": [
-                          {
-                            "type": "string"
-                          },
-                          {
-                            "type": "number"
-                          },
-                          {
-                            "type": "boolean"
-                          },
-                          {
-                            "type": "string",
-                            "format": "null",
-                            "nullable": true
-                          }
-                        ],
-                        "nullable": true
-                      }
-                    }
-                  },
-                  "required": [
-                    "code",
-                    "message"
-                  ]
-                }
-              }
-            }
           }
         },
         "security": []
       }
     },
-    "/v1/learner/products/{productId}/download": {
+    "/v1/learner/memberships": {
       "post": {
         "tags": [
           "Learners"
         ],
-        "parameters": [
-          {
-            "name": "productId",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string"
-            }
-          }
-        ],
+        "parameters": [],
         "requestBody": {
           "description": "Body",
           "content": {
             "application/json": {
               "schema": {
-                "default": {},
                 "type": "object",
-                "properties": {}
+                "properties": {
+                  "productId": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "required": [
+                  "productId"
+                ]
               }
             }
           }
@@ -58493,19 +58448,359 @@
                 "schema": {
                   "type": "object",
                   "properties": {
-                    "token": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "schoolId": {
+                      "type": "string"
+                    },
+                    "entityType": {
                       "type": "string",
-                      "minLength": 128,
-                      "maxLength": 128
+                      "enum": [
+                        "product",
+                        "community"
+                      ]
                     },
-                    "expiresAt": {
+                    "entityId": {
+                      "type": "string"
+                    },
+                    "paymentPlanId": {
                       "type": "string",
-                      "format": "date-time"
+                      "nullable": true
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "active",
+                        "payment_failed",
+                        "expired",
+                        "pending",
+                        "rejected",
+                        "paused"
+                      ]
+                    },
+                    "role": {
+                      "type": "string",
+                      "enum": [
+                        "comment",
+                        "post",
+                        "moderate"
+                      ],
+                      "nullable": true
+                    },
+                    "subscriptionId": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "subscriptionMethod": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "joiningReason": {
+                      "type": "string"
+                    },
+                    "rejectionReason": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "isIncludedInPlan": {
+                      "type": "boolean"
                     }
                   },
                   "required": [
-                    "token",
-                    "expiresAt"
+                    "id",
+                    "schoolId",
+                    "entityType",
+                    "entityId",
+                    "paymentPlanId",
+                    "status",
+                    "role",
+                    "subscriptionId",
+                    "subscriptionMethod",
+                    "joiningReason",
+                    "rejectionReason",
+                    "isIncludedInPlan"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "400",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "404",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": []
+      }
+    },
+    "/v1/learner/products/{productId}/download": {
+      "post": {
+        "tags": [
+          "Learners"
+        ],
+        "parameters": [
+          {
+            "name": "productId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "description": "Body",
+          "content": {
+            "application/json": {
+              "schema": {
+                "default": {},
+                "type": "object",
+                "properties": {}
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "201",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "token": {
+                      "type": "string",
+                      "minLength": 128,
+                      "maxLength": 128
+                    },
+                    "expiresAt": {
+                      "type": "string",
+                      "format": "date-time"
+                    }
+                  },
+                  "required": [
+                    "token",
+                    "expiresAt"
                   ]
                 }
               }
@@ -77237,8 +77532,4894 @@
               }
             }
           },
-          "409": {
-            "description": "409",
+          "409": {
+            "description": "409",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "apiKey": []
+          },
+          {
+            "oauth": []
+          }
+        ]
+      }
+    },
+    "/v1/school/hosts/{hostname}/verify": {
+      "post": {
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [
+          {
+            "name": "hostname",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        ],
+        "requestBody": {
+          "description": "Body",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {},
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "200",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "hostname": {
+                      "type": "string"
+                    },
+                    "kind": {
+                      "type": "string",
+                      "enum": [
+                        "subdomain",
+                        "custom"
+                      ]
+                    },
+                    "verificationStatus": {
+                      "type": "string",
+                      "enum": [
+                        "verified",
+                        "unverified"
+                      ]
+                    },
+                    "verifiedAt": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "isPrimary": {
+                      "type": "boolean"
+                    },
+                    "verificationRecords": {
+                      "type": "object",
+                      "properties": {
+                        "cnameTarget": {
+                          "type": "string"
+                        },
+                        "txtName": {
+                          "type": "string"
+                        },
+                        "txtValue": {
+                          "type": "string"
+                        },
+                        "kind": {
+                          "type": "string",
+                          "enum": [
+                            "cname",
+                            "alias"
+                          ]
+                        },
+                        "txtSatisfied": {
+                          "type": "boolean",
+                          "nullable": true
+                        },
+                        "routingSatisfied": {
+                          "type": "boolean",
+                          "nullable": true
+                        }
+                      },
+                      "required": [
+                        "cnameTarget",
+                        "txtName",
+                        "txtValue",
+                        "kind",
+                        "txtSatisfied",
+                        "routingSatisfied"
+                      ],
+                      "nullable": true
+                    }
+                  },
+                  "required": [
+                    "hostname",
+                    "kind",
+                    "verificationStatus",
+                    "verifiedAt",
+                    "isPrimary"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "400",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "404",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "409",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "apiKey": []
+          },
+          {
+            "oauth": []
+          }
+        ]
+      }
+    },
+    "/v1/school/hosts/{hostname}": {
+      "delete": {
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [
+          {
+            "name": "hostname",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "204",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "404",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "409",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "apiKey": []
+          },
+          {
+            "oauth": []
+          }
+        ]
+      }
+    },
+    "/v1/sso/connections": {
+      "get": {
+        "summary": "List the school's single sign-on connections",
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "200",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "items": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "string"
+                          },
+                          "protocol": {
+                            "type": "string",
+                            "enum": [
+                              "saml",
+                              "oidc"
+                            ]
+                          },
+                          "status": {
+                            "type": "string",
+                            "enum": [
+                              "draft",
+                              "active",
+                              "suspended",
+                              "disabled"
+                            ]
+                          },
+                          "displayName": {
+                            "type": "string"
+                          },
+                          "enforcement": {
+                            "type": "string",
+                            "enum": [
+                              "optional",
+                              "required_for_domains"
+                            ]
+                          },
+                          "maxSessionMinutes": {
+                            "type": "integer",
+                            "nullable": true
+                          },
+                          "idpEntityId": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "idpSsoUrl": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "idpCertificates": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          },
+                          "subjectAttribute": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "serviceProvider": {
+                            "type": "object",
+                            "properties": {
+                              "entityId": {
+                                "type": "string"
+                              },
+                              "acsUrl": {
+                                "type": "string"
+                              },
+                              "metadataUrl": {
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "entityId",
+                              "acsUrl",
+                              "metadataUrl"
+                            ]
+                          },
+                          "domains": {
+                            "type": "array",
+                            "items": {
+                              "type": "object",
+                              "properties": {
+                                "domain": {
+                                  "type": "string"
+                                },
+                                "verified": {
+                                  "type": "boolean"
+                                },
+                                "verifiedAt": {
+                                  "type": "string",
+                                  "nullable": true
+                                },
+                                "verificationRecord": {
+                                  "type": "object",
+                                  "properties": {
+                                    "type": {
+                                      "type": "string",
+                                      "enum": [
+                                        "TXT"
+                                      ]
+                                    },
+                                    "name": {
+                                      "type": "string"
+                                    },
+                                    "value": {
+                                      "type": "string"
+                                    }
+                                  },
+                                  "required": [
+                                    "type",
+                                    "name",
+                                    "value"
+                                  ]
+                                },
+                                "consecutiveCheckFailures": {
+                                  "type": "integer"
+                                },
+                                "lastCheckedAt": {
+                                  "type": "string",
+                                  "nullable": true
+                                }
+                              },
+                              "required": [
+                                "domain",
+                                "verified",
+                                "verifiedAt",
+                                "verificationRecord",
+                                "consecutiveCheckFailures",
+                                "lastCheckedAt"
+                              ]
+                            }
+                          },
+                          "testedAt": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "testedCurrentConfiguration": {
+                            "type": "boolean"
+                          },
+                          "planAvailable": {
+                            "type": "boolean"
+                          },
+                          "createdAt": {
+                            "type": "string"
+                          },
+                          "updatedAt": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "id",
+                          "protocol",
+                          "status",
+                          "displayName",
+                          "enforcement",
+                          "maxSessionMinutes",
+                          "idpEntityId",
+                          "idpSsoUrl",
+                          "idpCertificates",
+                          "subjectAttribute",
+                          "serviceProvider",
+                          "domains",
+                          "testedAt",
+                          "testedCurrentConfiguration",
+                          "planAvailable",
+                          "createdAt",
+                          "updatedAt"
+                        ]
+                      }
+                    }
+                  },
+                  "required": [
+                    "items"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "apiKey": []
+          },
+          {
+            "oauth": []
+          }
+        ]
+      },
+      "post": {
+        "summary": "Create a draft single sign-on connection",
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [],
+        "requestBody": {
+          "description": "Body",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "displayName": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 100
+                  },
+                  "metadataXml": {
+                    "type": "string",
+                    "maxLength": 524288
+                  },
+                  "idpEntityId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 2048
+                  },
+                  "idpSsoUrl": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 2048
+                  },
+                  "idpCertificates": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 16384
+                    },
+                    "maxItems": 5
+                  },
+                  "subjectAttribute": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 512,
+                    "nullable": true
+                  },
+                  "enforcement": {
+                    "type": "string",
+                    "enum": [
+                      "optional",
+                      "required_for_domains"
+                    ]
+                  },
+                  "maxSessionMinutes": {
+                    "type": "integer",
+                    "minimum": 5,
+                    "maximum": 525600,
+                    "nullable": true
+                  },
+                  "protocol": {
+                    "type": "string",
+                    "enum": [
+                      "saml"
+                    ]
+                  }
+                },
+                "required": [
+                  "displayName"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "201",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "protocol": {
+                      "type": "string",
+                      "enum": [
+                        "saml",
+                        "oidc"
+                      ]
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "draft",
+                        "active",
+                        "suspended",
+                        "disabled"
+                      ]
+                    },
+                    "displayName": {
+                      "type": "string"
+                    },
+                    "enforcement": {
+                      "type": "string",
+                      "enum": [
+                        "optional",
+                        "required_for_domains"
+                      ]
+                    },
+                    "maxSessionMinutes": {
+                      "type": "integer",
+                      "nullable": true
+                    },
+                    "idpEntityId": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "idpSsoUrl": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "idpCertificates": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "subjectAttribute": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "serviceProvider": {
+                      "type": "object",
+                      "properties": {
+                        "entityId": {
+                          "type": "string"
+                        },
+                        "acsUrl": {
+                          "type": "string"
+                        },
+                        "metadataUrl": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "entityId",
+                        "acsUrl",
+                        "metadataUrl"
+                      ]
+                    },
+                    "domains": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "domain": {
+                            "type": "string"
+                          },
+                          "verified": {
+                            "type": "boolean"
+                          },
+                          "verifiedAt": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "verificationRecord": {
+                            "type": "object",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "TXT"
+                                ]
+                              },
+                              "name": {
+                                "type": "string"
+                              },
+                              "value": {
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "name",
+                              "value"
+                            ]
+                          },
+                          "consecutiveCheckFailures": {
+                            "type": "integer"
+                          },
+                          "lastCheckedAt": {
+                            "type": "string",
+                            "nullable": true
+                          }
+                        },
+                        "required": [
+                          "domain",
+                          "verified",
+                          "verifiedAt",
+                          "verificationRecord",
+                          "consecutiveCheckFailures",
+                          "lastCheckedAt"
+                        ]
+                      }
+                    },
+                    "testedAt": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "testedCurrentConfiguration": {
+                      "type": "boolean"
+                    },
+                    "planAvailable": {
+                      "type": "boolean"
+                    },
+                    "createdAt": {
+                      "type": "string"
+                    },
+                    "updatedAt": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "protocol",
+                    "status",
+                    "displayName",
+                    "enforcement",
+                    "maxSessionMinutes",
+                    "idpEntityId",
+                    "idpSsoUrl",
+                    "idpCertificates",
+                    "subjectAttribute",
+                    "serviceProvider",
+                    "domains",
+                    "testedAt",
+                    "testedCurrentConfiguration",
+                    "planAvailable",
+                    "createdAt",
+                    "updatedAt"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "400",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "409",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": []
+      }
+    },
+    "/v1/sso/connections/{connectionId}": {
+      "get": {
+        "summary": "Read a single sign-on connection",
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [
+          {
+            "name": "connectionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "200",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "protocol": {
+                      "type": "string",
+                      "enum": [
+                        "saml",
+                        "oidc"
+                      ]
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "draft",
+                        "active",
+                        "suspended",
+                        "disabled"
+                      ]
+                    },
+                    "displayName": {
+                      "type": "string"
+                    },
+                    "enforcement": {
+                      "type": "string",
+                      "enum": [
+                        "optional",
+                        "required_for_domains"
+                      ]
+                    },
+                    "maxSessionMinutes": {
+                      "type": "integer",
+                      "nullable": true
+                    },
+                    "idpEntityId": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "idpSsoUrl": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "idpCertificates": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "subjectAttribute": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "serviceProvider": {
+                      "type": "object",
+                      "properties": {
+                        "entityId": {
+                          "type": "string"
+                        },
+                        "acsUrl": {
+                          "type": "string"
+                        },
+                        "metadataUrl": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "entityId",
+                        "acsUrl",
+                        "metadataUrl"
+                      ]
+                    },
+                    "domains": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "domain": {
+                            "type": "string"
+                          },
+                          "verified": {
+                            "type": "boolean"
+                          },
+                          "verifiedAt": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "verificationRecord": {
+                            "type": "object",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "TXT"
+                                ]
+                              },
+                              "name": {
+                                "type": "string"
+                              },
+                              "value": {
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "name",
+                              "value"
+                            ]
+                          },
+                          "consecutiveCheckFailures": {
+                            "type": "integer"
+                          },
+                          "lastCheckedAt": {
+                            "type": "string",
+                            "nullable": true
+                          }
+                        },
+                        "required": [
+                          "domain",
+                          "verified",
+                          "verifiedAt",
+                          "verificationRecord",
+                          "consecutiveCheckFailures",
+                          "lastCheckedAt"
+                        ]
+                      }
+                    },
+                    "testedAt": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "testedCurrentConfiguration": {
+                      "type": "boolean"
+                    },
+                    "planAvailable": {
+                      "type": "boolean"
+                    },
+                    "createdAt": {
+                      "type": "string"
+                    },
+                    "updatedAt": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "protocol",
+                    "status",
+                    "displayName",
+                    "enforcement",
+                    "maxSessionMinutes",
+                    "idpEntityId",
+                    "idpSsoUrl",
+                    "idpCertificates",
+                    "subjectAttribute",
+                    "serviceProvider",
+                    "domains",
+                    "testedAt",
+                    "testedCurrentConfiguration",
+                    "planAvailable",
+                    "createdAt",
+                    "updatedAt"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "404",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": [
+          {
+            "apiKey": []
+          },
+          {
+            "oauth": []
+          }
+        ]
+      },
+      "patch": {
+        "summary": "Change a single sign-on connection",
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [
+          {
+            "name": "connectionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64
+            }
+          }
+        ],
+        "requestBody": {
+          "description": "Body",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "displayName": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 100
+                  },
+                  "metadataXml": {
+                    "type": "string",
+                    "maxLength": 524288
+                  },
+                  "idpEntityId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 2048
+                  },
+                  "idpSsoUrl": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 2048
+                  },
+                  "idpCertificates": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 16384
+                    },
+                    "maxItems": 5
+                  },
+                  "subjectAttribute": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 512,
+                    "nullable": true
+                  },
+                  "enforcement": {
+                    "type": "string",
+                    "enum": [
+                      "optional",
+                      "required_for_domains"
+                    ]
+                  },
+                  "maxSessionMinutes": {
+                    "type": "integer",
+                    "minimum": 5,
+                    "maximum": 525600,
+                    "nullable": true
+                  }
+                },
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "200",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "protocol": {
+                      "type": "string",
+                      "enum": [
+                        "saml",
+                        "oidc"
+                      ]
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "draft",
+                        "active",
+                        "suspended",
+                        "disabled"
+                      ]
+                    },
+                    "displayName": {
+                      "type": "string"
+                    },
+                    "enforcement": {
+                      "type": "string",
+                      "enum": [
+                        "optional",
+                        "required_for_domains"
+                      ]
+                    },
+                    "maxSessionMinutes": {
+                      "type": "integer",
+                      "nullable": true
+                    },
+                    "idpEntityId": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "idpSsoUrl": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "idpCertificates": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "subjectAttribute": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "serviceProvider": {
+                      "type": "object",
+                      "properties": {
+                        "entityId": {
+                          "type": "string"
+                        },
+                        "acsUrl": {
+                          "type": "string"
+                        },
+                        "metadataUrl": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "entityId",
+                        "acsUrl",
+                        "metadataUrl"
+                      ]
+                    },
+                    "domains": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "domain": {
+                            "type": "string"
+                          },
+                          "verified": {
+                            "type": "boolean"
+                          },
+                          "verifiedAt": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "verificationRecord": {
+                            "type": "object",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "TXT"
+                                ]
+                              },
+                              "name": {
+                                "type": "string"
+                              },
+                              "value": {
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "name",
+                              "value"
+                            ]
+                          },
+                          "consecutiveCheckFailures": {
+                            "type": "integer"
+                          },
+                          "lastCheckedAt": {
+                            "type": "string",
+                            "nullable": true
+                          }
+                        },
+                        "required": [
+                          "domain",
+                          "verified",
+                          "verifiedAt",
+                          "verificationRecord",
+                          "consecutiveCheckFailures",
+                          "lastCheckedAt"
+                        ]
+                      }
+                    },
+                    "testedAt": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "testedCurrentConfiguration": {
+                      "type": "boolean"
+                    },
+                    "planAvailable": {
+                      "type": "boolean"
+                    },
+                    "createdAt": {
+                      "type": "string"
+                    },
+                    "updatedAt": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "protocol",
+                    "status",
+                    "displayName",
+                    "enforcement",
+                    "maxSessionMinutes",
+                    "idpEntityId",
+                    "idpSsoUrl",
+                    "idpCertificates",
+                    "subjectAttribute",
+                    "serviceProvider",
+                    "domains",
+                    "testedAt",
+                    "testedCurrentConfiguration",
+                    "planAvailable",
+                    "createdAt",
+                    "updatedAt"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "400",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "404",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": []
+      },
+      "delete": {
+        "summary": "Delete a single sign-on connection",
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [
+          {
+            "name": "connectionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "204",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "404",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": []
+      }
+    },
+    "/v1/sso/connections/{connectionId}/domains": {
+      "post": {
+        "summary": "Add an email domain to a single sign-on connection",
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [
+          {
+            "name": "connectionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64
+            }
+          }
+        ],
+        "requestBody": {
+          "description": "Body",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "domain": {
+                    "type": "string",
+                    "minLength": 3,
+                    "maxLength": 253
+                  }
+                },
+                "required": [
+                  "domain"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "201",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "domain": {
+                      "type": "string"
+                    },
+                    "verified": {
+                      "type": "boolean"
+                    },
+                    "verifiedAt": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "verificationRecord": {
+                      "type": "object",
+                      "properties": {
+                        "type": {
+                          "type": "string",
+                          "enum": [
+                            "TXT"
+                          ]
+                        },
+                        "name": {
+                          "type": "string"
+                        },
+                        "value": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "type",
+                        "name",
+                        "value"
+                      ]
+                    },
+                    "consecutiveCheckFailures": {
+                      "type": "integer"
+                    },
+                    "lastCheckedAt": {
+                      "type": "string",
+                      "nullable": true
+                    }
+                  },
+                  "required": [
+                    "domain",
+                    "verified",
+                    "verifiedAt",
+                    "verificationRecord",
+                    "consecutiveCheckFailures",
+                    "lastCheckedAt"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "400",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "404",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "409",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": []
+      }
+    },
+    "/v1/sso/connections/{connectionId}/domains/{domain}/verify": {
+      "post": {
+        "summary": "Check the DNS record that proves the school owns an email domain",
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [
+          {
+            "name": "connectionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64
+            }
+          },
+          {
+            "name": "domain",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        ],
+        "requestBody": {
+          "description": "Body",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {},
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "200",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "domain": {
+                      "type": "string"
+                    },
+                    "verified": {
+                      "type": "boolean"
+                    },
+                    "verifiedAt": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "verificationRecord": {
+                      "type": "object",
+                      "properties": {
+                        "type": {
+                          "type": "string",
+                          "enum": [
+                            "TXT"
+                          ]
+                        },
+                        "name": {
+                          "type": "string"
+                        },
+                        "value": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "type",
+                        "name",
+                        "value"
+                      ]
+                    },
+                    "consecutiveCheckFailures": {
+                      "type": "integer"
+                    },
+                    "lastCheckedAt": {
+                      "type": "string",
+                      "nullable": true
+                    }
+                  },
+                  "required": [
+                    "domain",
+                    "verified",
+                    "verifiedAt",
+                    "verificationRecord",
+                    "consecutiveCheckFailures",
+                    "lastCheckedAt"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "400",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "404",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "429",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": []
+      }
+    },
+    "/v1/sso/connections/{connectionId}/domains/{domain}": {
+      "delete": {
+        "summary": "Remove an email domain from a single sign-on connection",
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [
+          {
+            "name": "connectionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64
+            }
+          },
+          {
+            "name": "domain",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "204",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "404",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": []
+      }
+    },
+    "/v1/sso/connections/{connectionId}/test": {
+      "post": {
+        "summary": "Start a test sign-in; returns the URL to open",
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [
+          {
+            "name": "connectionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64
+            }
+          }
+        ],
+        "requestBody": {
+          "description": "Body",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "returnUrl": {
+                    "type": "string",
+                    "format": "uri",
+                    "maxLength": 1000
+                  }
+                },
+                "required": [
+                  "returnUrl"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "200",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "url": {
+                      "type": "string",
+                      "format": "uri"
+                    }
+                  },
+                  "required": [
+                    "url"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "400",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "404",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": []
+      }
+    },
+    "/v1/sso/connections/{connectionId}/test-results/{requestId}": {
+      "get": {
+        "summary": "Read the result of a test sign-in this admin started",
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [
+          {
+            "name": "connectionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64
+            }
+          },
+          {
+            "name": "requestId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "200",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "reason": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "issuer": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "subject": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "email": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "name": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "emailDomainVerified": {
+                      "type": "boolean",
+                      "nullable": true
+                    },
+                    "attributes": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "expiresAt": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "ok",
+                    "reason",
+                    "issuer",
+                    "subject",
+                    "email",
+                    "name",
+                    "emailDomainVerified",
+                    "attributes",
+                    "expiresAt"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "404",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": []
+      }
+    },
+    "/v1/sso/connections/{connectionId}/activate": {
+      "post": {
+        "summary": "Turn a tested single sign-on connection on",
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [
+          {
+            "name": "connectionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64
+            }
+          }
+        ],
+        "requestBody": {
+          "description": "Body",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {},
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "200",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "protocol": {
+                      "type": "string",
+                      "enum": [
+                        "saml",
+                        "oidc"
+                      ]
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "draft",
+                        "active",
+                        "suspended",
+                        "disabled"
+                      ]
+                    },
+                    "displayName": {
+                      "type": "string"
+                    },
+                    "enforcement": {
+                      "type": "string",
+                      "enum": [
+                        "optional",
+                        "required_for_domains"
+                      ]
+                    },
+                    "maxSessionMinutes": {
+                      "type": "integer",
+                      "nullable": true
+                    },
+                    "idpEntityId": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "idpSsoUrl": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "idpCertificates": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "subjectAttribute": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "serviceProvider": {
+                      "type": "object",
+                      "properties": {
+                        "entityId": {
+                          "type": "string"
+                        },
+                        "acsUrl": {
+                          "type": "string"
+                        },
+                        "metadataUrl": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "entityId",
+                        "acsUrl",
+                        "metadataUrl"
+                      ]
+                    },
+                    "domains": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "domain": {
+                            "type": "string"
+                          },
+                          "verified": {
+                            "type": "boolean"
+                          },
+                          "verifiedAt": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "verificationRecord": {
+                            "type": "object",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "TXT"
+                                ]
+                              },
+                              "name": {
+                                "type": "string"
+                              },
+                              "value": {
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "name",
+                              "value"
+                            ]
+                          },
+                          "consecutiveCheckFailures": {
+                            "type": "integer"
+                          },
+                          "lastCheckedAt": {
+                            "type": "string",
+                            "nullable": true
+                          }
+                        },
+                        "required": [
+                          "domain",
+                          "verified",
+                          "verifiedAt",
+                          "verificationRecord",
+                          "consecutiveCheckFailures",
+                          "lastCheckedAt"
+                        ]
+                      }
+                    },
+                    "testedAt": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "testedCurrentConfiguration": {
+                      "type": "boolean"
+                    },
+                    "planAvailable": {
+                      "type": "boolean"
+                    },
+                    "createdAt": {
+                      "type": "string"
+                    },
+                    "updatedAt": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "protocol",
+                    "status",
+                    "displayName",
+                    "enforcement",
+                    "maxSessionMinutes",
+                    "idpEntityId",
+                    "idpSsoUrl",
+                    "idpCertificates",
+                    "subjectAttribute",
+                    "serviceProvider",
+                    "domains",
+                    "testedAt",
+                    "testedCurrentConfiguration",
+                    "planAvailable",
+                    "createdAt",
+                    "updatedAt"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "400",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "404",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "409",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "security": []
+      }
+    },
+    "/v1/sso/connections/{connectionId}/disable": {
+      "post": {
+        "summary": "Turn a single sign-on connection off and end its sessions",
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [
+          {
+            "name": "connectionId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64
+            }
+          }
+        ],
+        "requestBody": {
+          "description": "Body",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {},
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "200",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "protocol": {
+                      "type": "string",
+                      "enum": [
+                        "saml",
+                        "oidc"
+                      ]
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "draft",
+                        "active",
+                        "suspended",
+                        "disabled"
+                      ]
+                    },
+                    "displayName": {
+                      "type": "string"
+                    },
+                    "enforcement": {
+                      "type": "string",
+                      "enum": [
+                        "optional",
+                        "required_for_domains"
+                      ]
+                    },
+                    "maxSessionMinutes": {
+                      "type": "integer",
+                      "nullable": true
+                    },
+                    "idpEntityId": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "idpSsoUrl": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "idpCertificates": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "subjectAttribute": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "serviceProvider": {
+                      "type": "object",
+                      "properties": {
+                        "entityId": {
+                          "type": "string"
+                        },
+                        "acsUrl": {
+                          "type": "string"
+                        },
+                        "metadataUrl": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "entityId",
+                        "acsUrl",
+                        "metadataUrl"
+                      ]
+                    },
+                    "domains": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "domain": {
+                            "type": "string"
+                          },
+                          "verified": {
+                            "type": "boolean"
+                          },
+                          "verifiedAt": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "verificationRecord": {
+                            "type": "object",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "TXT"
+                                ]
+                              },
+                              "name": {
+                                "type": "string"
+                              },
+                              "value": {
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "name",
+                              "value"
+                            ]
+                          },
+                          "consecutiveCheckFailures": {
+                            "type": "integer"
+                          },
+                          "lastCheckedAt": {
+                            "type": "string",
+                            "nullable": true
+                          }
+                        },
+                        "required": [
+                          "domain",
+                          "verified",
+                          "verifiedAt",
+                          "verificationRecord",
+                          "consecutiveCheckFailures",
+                          "lastCheckedAt"
+                        ]
+                      }
+                    },
+                    "testedAt": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "testedCurrentConfiguration": {
+                      "type": "boolean"
+                    },
+                    "planAvailable": {
+                      "type": "boolean"
+                    },
+                    "createdAt": {
+                      "type": "string"
+                    },
+                    "updatedAt": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "protocol",
+                    "status",
+                    "displayName",
+                    "enforcement",
+                    "maxSessionMinutes",
+                    "idpEntityId",
+                    "idpSsoUrl",
+                    "idpCertificates",
+                    "subjectAttribute",
+                    "serviceProvider",
+                    "domains",
+                    "testedAt",
+                    "testedCurrentConfiguration",
+                    "planAvailable",
+                    "createdAt",
+                    "updatedAt"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "401",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "403",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string",
+                      "enum": [
+                        "unauthenticated",
+                        "credential_ambiguous",
+                        "tenant_required",
+                        "tenant_forbidden",
+                        "forbidden",
+                        "not_found",
+                        "conflict",
+                        "validation_failed",
+                        "rate_limited",
+                        "internal_error"
+                      ]
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "details": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "string",
+                            "format": "null",
+                            "nullable": true
+                          }
+                        ],
+                        "nullable": true
+                      }
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "404",
             "content": {
               "application/json": {
                 "schema": {
@@ -77294,24 +82475,18 @@
             }
           }
         },
-        "security": [
-          {
-            "apiKey": []
-          },
-          {
-            "oauth": []
-          }
-        ]
+        "security": []
       }
     },
-    "/v1/school/hosts/{hostname}/verify": {
-      "post": {
+    "/v1/sso/identities/{schoolAccountId}": {
+      "delete": {
+        "summary": "Remove a learner's single sign-on link and end their SSO sessions",
         "tags": [
           "School & Team"
         ],
         "parameters": [
           {
-            "name": "hostname",
+            "name": "schoolAccountId",
             "in": "path",
             "required": true,
             "schema": {
@@ -77320,102 +82495,17 @@
             }
           }
         ],
-        "requestBody": {
-          "description": "Body",
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {},
-                "additionalProperties": false
-              }
-            }
-          }
-        },
         "responses": {
-          "200": {
-            "description": "200",
+          "204": {
+            "description": "204",
             "content": {
               "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "hostname": {
-                      "type": "string"
-                    },
-                    "kind": {
-                      "type": "string",
-                      "enum": [
-                        "subdomain",
-                        "custom"
-                      ]
-                    },
-                    "verificationStatus": {
-                      "type": "string",
-                      "enum": [
-                        "verified",
-                        "unverified"
-                      ]
-                    },
-                    "verifiedAt": {
-                      "type": "string",
-                      "nullable": true
-                    },
-                    "isPrimary": {
-                      "type": "boolean"
-                    },
-                    "verificationRecords": {
-                      "type": "object",
-                      "properties": {
-                        "cnameTarget": {
-                          "type": "string"
-                        },
-                        "txtName": {
-                          "type": "string"
-                        },
-                        "txtValue": {
-                          "type": "string"
-                        },
-                        "kind": {
-                          "type": "string",
-                          "enum": [
-                            "cname",
-                            "alias"
-                          ]
-                        },
-                        "txtSatisfied": {
-                          "type": "boolean",
-                          "nullable": true
-                        },
-                        "routingSatisfied": {
-                          "type": "boolean",
-                          "nullable": true
-                        }
-                      },
-                      "required": [
-                        "cnameTarget",
-                        "txtName",
-                        "txtValue",
-                        "kind",
-                        "txtSatisfied",
-                        "routingSatisfied"
-                      ],
-                      "nullable": true
-                    }
-                  },
-                  "required": [
-                    "hostname",
-                    "kind",
-                    "verificationStatus",
-                    "verifiedAt",
-                    "isPrimary"
-                  ]
-                }
+                "schema": {}
               }
             }
           },
-          "400": {
-            "description": "400",
+          "401": {
+            "description": "401",
             "content": {
               "application/json": {
                 "schema": {
@@ -77470,8 +82560,8 @@
               }
             }
           },
-          "401": {
-            "description": "401",
+          "403": {
+            "description": "403",
             "content": {
               "application/json": {
                 "schema": {
@@ -77526,8 +82616,8 @@
               }
             }
           },
-          "403": {
-            "description": "403",
+          "404": {
+            "description": "404",
             "content": {
               "application/json": {
                 "schema": {
@@ -77581,9 +82671,83 @@
                 }
               }
             }
+          }
+        },
+        "security": []
+      }
+    },
+    "/v1/school/login-methods": {
+      "get": {
+        "summary": "Read which sign-in methods the school's learners can use",
+        "tags": [
+          "School & Team"
+        ],
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "200",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "loginMethods": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "enum": [
+                          "email",
+                          "google"
+                        ]
+                      }
+                    },
+                    "googleAvailable": {
+                      "type": "boolean"
+                    },
+                    "sso": {
+                      "type": "object",
+                      "properties": {
+                        "active": {
+                          "type": "boolean"
+                        },
+                        "displayName": {
+                          "type": "string",
+                          "nullable": true
+                        },
+                        "planAvailable": {
+                          "type": "boolean"
+                        }
+                      },
+                      "required": [
+                        "active",
+                        "displayName",
+                        "planAvailable"
+                      ]
+                    },
+                    "usable": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "enum": [
+                          "email",
+                          "google",
+                          "sso"
+                        ]
+                      }
+                    }
+                  },
+                  "required": [
+                    "loginMethods",
+                    "googleAvailable",
+                    "sso",
+                    "usable"
+                  ]
+                }
+              }
+            }
           },
-          "404": {
-            "description": "404",
+          "401": {
+            "description": "401",
             "content": {
               "application/json": {
                 "schema": {
@@ -77638,8 +82802,8 @@
               }
             }
           },
-          "409": {
-            "description": "409",
+          "403": {
+            "description": "403",
             "content": {
               "application/json": {
                 "schema": {
@@ -77703,91 +82867,105 @@
             "oauth": []
           }
         ]
-      }
-    },
-    "/v1/school/hosts/{hostname}": {
-      "delete": {
+      },
+      "patch": {
+        "summary": "Turn learner sign-in methods on or off",
         "tags": [
           "School & Team"
         ],
-        "parameters": [
-          {
-            "name": "hostname",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "minLength": 1
+        "parameters": [],
+        "requestBody": {
+          "description": "Body",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "loginMethods": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "enum": [
+                        "email",
+                        "google"
+                      ]
+                    },
+                    "maxItems": 2
+                  }
+                },
+                "required": [
+                  "loginMethods"
+                ],
+                "additionalProperties": false
+              }
             }
           }
-        ],
+        },
         "responses": {
-          "204": {
-            "description": "204",
-            "content": {
-              "application/json": {
-                "schema": {}
-              }
-            }
-          },
-          "401": {
-            "description": "401",
+          "200": {
+            "description": "200",
             "content": {
               "application/json": {
                 "schema": {
                   "type": "object",
                   "properties": {
-                    "code": {
-                      "type": "string",
-                      "enum": [
-                        "unauthenticated",
-                        "credential_ambiguous",
-                        "tenant_required",
-                        "tenant_forbidden",
-                        "forbidden",
-                        "not_found",
-                        "conflict",
-                        "validation_failed",
-                        "rate_limited",
-                        "internal_error"
-                      ]
+                    "loginMethods": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "enum": [
+                          "email",
+                          "google"
+                        ]
+                      }
                     },
-                    "message": {
-                      "type": "string"
+                    "googleAvailable": {
+                      "type": "boolean"
                     },
-                    "details": {
+                    "sso": {
                       "type": "object",
-                      "additionalProperties": {
-                        "oneOf": [
-                          {
-                            "type": "string"
-                          },
-                          {
-                            "type": "number"
-                          },
-                          {
-                            "type": "boolean"
-                          },
-                          {
-                            "type": "string",
-                            "format": "null",
-                            "nullable": true
-                          }
-                        ],
-                        "nullable": true
+                      "properties": {
+                        "active": {
+                          "type": "boolean"
+                        },
+                        "displayName": {
+                          "type": "string",
+                          "nullable": true
+                        },
+                        "planAvailable": {
+                          "type": "boolean"
+                        }
+                      },
+                      "required": [
+                        "active",
+                        "displayName",
+                        "planAvailable"
+                      ]
+                    },
+                    "usable": {
+                      "type": "array",
+                      "items": {
+                        "type": "string",
+                        "enum": [
+                          "email",
+                          "google",
+                          "sso"
+                        ]
                       }
                     }
                   },
                   "required": [
-                    "code",
-                    "message"
+                    "loginMethods",
+                    "googleAvailable",
+                    "sso",
+                    "usable"
                   ]
                 }
               }
             }
           },
-          "403": {
-            "description": "403",
+          "400": {
+            "description": "400",
             "content": {
               "application/json": {
                 "schema": {
@@ -77842,8 +83020,8 @@
               }
             }
           },
-          "404": {
-            "description": "404",
+          "401": {
+            "description": "401",
             "content": {
               "application/json": {
                 "schema": {
@@ -77898,8 +83076,8 @@
               }
             }
           },
-          "409": {
-            "description": "409",
+          "403": {
+            "description": "403",
             "content": {
               "application/json": {
                 "schema": {
diff --git a/apps/api/package.json b/apps/api/package.json
index c1e64a882..7efd73996 100644
--- a/apps/api/package.json
+++ b/apps/api/package.json
@@ -37,18 +37,20 @@
     "@better-auth/oauth-provider": "1.7.22",
     "@better-auth/utils": "0.5.1",
     "@better-fetch/fetch": "1.3.3",
-    "@codelitdev/billing": "0.9.0",
+    "@codelitdev/billing": "0.11.0",
     "@codelitdev/mcp-server-kit": "0.5.0",
     "@codelitdev/oauth-server-kit": "0.10.0",
     "@codelitdev/observability": "0.5.0",
-    "@codelitdev/platform": "0.9.0",
+    "@codelitdev/platform": "0.11.0",
     "@codelitdev/platform-conformance": "0.9.0",
     "@courselit/api-contract": "workspace:*",
     "@frontlit/text-editor": "0.1.0-alpha.3",
+    "@node-saml/node-saml": "5.2.0",
     "@ts-rest/express": "3.52.1",
     "@ts-rest/open-api": "3.52.1",
     "@types/nodemailer": "^8.0.1",
     "@types/pg": "8.23.1",
+    "@xmldom/xmldom": "0.8.15",
     "better-auth": "1.7.22",
     "better-call": "1.4.5",
     "dodopayments": "^2.61.1",
@@ -69,6 +71,7 @@
     "@types/swagger-ui-express": "4.1.8",
     "drizzle-kit": "0.31.10",
     "typescript": "5.9.3",
-    "@types/bun": "1.4.4"
+    "@types/bun": "1.4.4",
+    "xml-crypto": "6.4.0"
   }
 }
diff --git a/apps/api/src/activity-types.ts b/apps/api/src/activity-types.ts
index 87012b7f5..0d691ade4 100644
--- a/apps/api/src/activity-types.ts
+++ b/apps/api/src/activity-types.ts
@@ -19,6 +19,7 @@ export const ActivityType = {
   NEWSLETTER_SUBSCRIBED: "newsletter_subscribed",
   NEWSLETTER_UNSUBSCRIBED: "newsletter_unsubscribed",
   USER_CREATED: "user_created",
+  LEARNER_SIGNED_IN: "learner_signed_in",
   TAG_ADDED: "tag_added",
   TAG_REMOVED: "tag_removed",
   COMMUNITY_JOINED: "community_joined",
diff --git a/apps/api/src/auth/authenticate.ts b/apps/api/src/auth/authenticate.ts
index 5e02ce446..8de035280 100644
--- a/apps/api/src/auth/authenticate.ts
+++ b/apps/api/src/auth/authenticate.ts
@@ -22,6 +22,7 @@ import {
 import { apiKeyFailureLimiterFor, clientKeyFromHeaders } from "./api-key-throttle.js";
 import type { AdminAuth } from "./better-auth.js";
 import { adminSessionCookieName } from "./options.js";
+import { isShadowUser } from "../shadow-users.js";
 
 export type AuthRuntime = {
   db: AppDb;
@@ -70,6 +71,11 @@ export async function authenticateHttpRequest(
         error: createPlatformError("unauthenticated"),
       };
     }
+    // Second layer behind Better Auth's session hook: a shadow user (made
+    // only to own an SSO school account) never acts as a platform user.
+    if (await isShadowUser(deps.db, resolved.identity.subject)) {
+      return { kind: "rejected", error: createPlatformError("unauthenticated") };
+    }
     return {
       kind: "authenticated",
       principalId: resolved.identity.subject,
@@ -97,6 +103,9 @@ export async function authenticateHttpRequest(
         error: createPlatformError("unauthenticated"),
       };
     }
+    if (await isShadowUser(deps.db, resolved.identity.subject)) {
+      return { kind: "rejected", error: createPlatformError("unauthenticated") };
+    }
     return {
       kind: "authenticated",
       principalId: resolved.identity.subject,
@@ -145,6 +154,9 @@ export async function authenticateMcpRequest(
         error: createPlatformError("unauthenticated"),
       };
     }
+    if (await isShadowUser(deps.db, resolved.identity.subject)) {
+      return { kind: "rejected", error: createPlatformError("unauthenticated") };
+    }
     return {
       kind: "authenticated",
       principalId: resolved.identity.subject,
diff --git a/apps/api/src/auth/operation-policy.ts b/apps/api/src/auth/operation-policy.ts
index abdbd11d9..049e6583b 100644
--- a/apps/api/src/auth/operation-policy.ts
+++ b/apps/api/src/auth/operation-policy.ts
@@ -155,6 +155,32 @@ export const OPERATION_POLICIES = {
   deleteSchoolHost: schoolOp(["school:write"]),
   verifySchoolHost: schoolOp(["school:write"]),
 
+  // Learner sign-in methods. Turning a method off can't hand anyone's account
+  // to someone else, and the policy falls back to email codes, so API keys and
+  // MCP may change it.
+  getSchoolLoginMethods: schoolOp(["school:read"]),
+  updateSchoolLoginMethods: schoolOp(["school:write"]),
+
+  // Learner single sign-on. Whoever controls a connection's IdP settings can
+  // sign in as every learner linked to it, so writes are owner-only, a
+  // signed-in admin session only (no API key or OAuth client) and need a
+  // recent sign-in. Reads are open to every credential and never carry
+  // secrets or test attributes.
+  listSsoConnections: schoolOp(["school:read"]),
+  getSsoConnection: schoolOp(["school:read"]),
+  createSsoConnection: schoolOwnerOp(["session"], true),
+  updateSsoConnection: schoolOwnerOp(["session"], true),
+  deleteSsoConnection: schoolOwnerOp(["session"], true),
+  addSsoDomain: schoolOwnerOp(["session"], true),
+  verifySsoDomain: schoolOwnerOp(["session"], true),
+  deleteSsoDomain: schoolOwnerOp(["session"], true),
+  startSsoConnectionTest: schoolOwnerOp(["session"], true),
+  // Readable by the admin who started the test, within 15 minutes of it.
+  getSsoConnectionTestResult: schoolOwnerOp(["session"]),
+  activateSsoConnection: schoolOwnerOp(["session"], true),
+  disableSsoConnection: schoolOwnerOp(["session"], true),
+  unlinkSsoIdentity: schoolOwnerOp(["session"], true),
+
   // Mailing (broadcasts, sequences, templates). Sending is kept off API keys:
   // a leaked key must not be able to send email to the school's contacts.
   getMailingSettings: schoolOp(["contacts:read"]),
@@ -365,6 +391,7 @@ export const OPERATION_POLICIES = {
   learnerRequestEmailCode: learnerOp(),
   learnerVerifyEmailCode: learnerOp(),
   learnerStartGoogleSignIn: learnerOp(),
+  learnerStartSsoSignIn: learnerOp(),
   consumeSchoolAuthTicket: learnerOp(),
   learnerSignOut: learnerOp(),
   learnerMe: learnerOp(),
diff --git a/apps/api/src/auth/options.ts b/apps/api/src/auth/options.ts
index c97a598b2..ded5ac5e8 100644
--- a/apps/api/src/auth/options.ts
+++ b/apps/api/src/auth/options.ts
@@ -15,6 +15,7 @@ import { escapeHtml, sendSystemMail } from "../system-mail.js";
 import { CAPTCHA_AUTH_ENDPOINTS, captchaSettings } from "../captcha.js";
 import { fetchClientMetadataResource } from "./cimd-fetch.js";
 import { CLIENT_IP_HEADER } from "./api-key-throttle.js";
+import { isShadowUser } from "../shadow-users.js";
 
 export const AUTH_COOKIE_PREFIX = "courselit";
 
@@ -138,6 +139,19 @@ export function buildBetterAuthOptions(input: {
     account: {
       modelName: "account",
     },
+    // Shadow users own SSO-created school accounts and never get a
+    // CourseLit-wide session, whatever else goes wrong.
+    databaseHooks: {
+      session: {
+        create: {
+          before: async (session: { userId: string }) => {
+            if (input.db && (await isShadowUser(input.db, session.userId))) {
+              return false as const;
+            }
+          },
+        },
+      },
+    },
     verification: {
       modelName: "verification",
     },
diff --git a/apps/api/src/billing.ts b/apps/api/src/billing.ts
index 6fda884c2..e9bc7605c 100644
--- a/apps/api/src/billing.ts
+++ b/apps/api/src/billing.ts
@@ -16,6 +16,8 @@ import type { Clock } from "@codelitdev/platform";
 import { createBillingAuditHook } from "./billing-audit.js";
 import { verification } from "./db/schema/auth.generated.js";
 import * as billingSchema from "./db/schema/billing.generated.js";
+import { enqueuePlanFeatureSync } from "./plan-features.js";
+import { SSO_FEATURE } from "./sso-config.js";
 import type { AppDb } from "./types.js";
 
 export type BillingBundle = {
@@ -147,11 +149,17 @@ export function composeBilling(
     hooks: {
       audit: createBillingAuditHook({ db, clock, getTransaction: () => store.getTransaction() }),
       lifecycle: {
-        async afterProjection() {
-          /* product-owned effect hook */
+        // Only queues a background job, in the billing transaction, so it commits
+        // with the plan change. The SSO work itself never runs here: a failed
+        // statement would abort the billing write. Queued on every projection;
+        // the sync reads the current plan and is safe to repeat.
+        async afterProjection({ next }) {
+          const client = (store.getTransaction() ?? db) as Pick<AppDb, "execute">;
+          await enqueuePlanFeatureSync(client, next.billableEntityId, clock);
         },
       },
     },
+    planFeatures: { business: [SSO_FEATURE] },
     mode,
     checkoutProvider: mode !== "cloud" ? "" : dodo ? "dodo" : "fake",
     requestedRevision: mode === "cloud" ? (dodo ? revision : 1) : null,
diff --git a/apps/api/src/communities.ts b/apps/api/src/communities.ts
index bc090bc1c..c12ad1dcc 100644
--- a/apps/api/src/communities.ts
+++ b/apps/api/src/communities.ts
@@ -60,6 +60,7 @@ import type { CourseLitPermission } from "./permissions.js";
 import { resourceSlugTaken } from "./resource-slugs.js";
 import { accessibleSpaceIds, moderatesSpace } from "./space-access.js";
 import { amountMinorForPlan } from "./storefront.js";
+import type { SignInMethod } from "./sign-in-policy.js";
 import type { AppDb } from "./types.js";
 import { ensureSalesPage } from "./website.js";
 
@@ -73,6 +74,8 @@ export type CommunityLearnerViewer = {
   schoolPublicId: string;
   learnerId: string;
   learnerPublicId: string;
+  /** How the learner signed in; an `sso` session never has team powers. */
+  authenticationMethod: SignInMethod;
 };
 
 export type CommunityViewer =
@@ -1116,7 +1119,7 @@ async function canReadCommunity(
   });
   if (membership?.status === "active") return true;
 
-  const accessible = await accessibleSpaceIds(db, schoolId, viewer.learnerId);
+  const accessible = await accessibleSpaceIds(db, schoolId, viewer.learnerId, viewer.authenticationMethod);
   if (accessible.size === 0) return false;
   if (spaceId) return accessible.has(spaceId);
   const posts = await db
@@ -1148,7 +1151,7 @@ async function canWriteCommunity(
   });
   if (membership?.status === "active") return true;
 
-  const accessible = await accessibleSpaceIds(db, schoolId, viewer.learnerId);
+  const accessible = await accessibleSpaceIds(db, schoolId, viewer.learnerId, viewer.authenticationMethod);
   if (accessible.size === 0) return false;
   if (spaceId) return accessible.has(spaceId);
   const posts = await db
@@ -1173,7 +1176,7 @@ async function canModerateCommunity(
   if (viewer.kind === "admin") {
     return adminCan(viewer.context, "communities:moderate");
   }
-  if (spaceId) return moderatesSpace(db, schoolId, viewer.learnerId, spaceId);
+  if (spaceId) return moderatesSpace(db, schoolId, viewer.learnerId, spaceId, viewer.authenticationMethod);
   const membership = await loadMembership(db, schoolId, communityId, {
     kind: "learner",
     id: viewer.learnerId,
diff --git a/apps/api/src/contacts-create.test.ts b/apps/api/src/contacts-create.test.ts
index a3eca12db..c2881ce84 100644
--- a/apps/api/src/contacts-create.test.ts
+++ b/apps/api/src/contacts-create.test.ts
@@ -114,7 +114,12 @@ describe("createContact", () => {
     const [job] = await runtime.db
       .select()
       .from(schema.integrationOutboxJobs)
-      .where(eq(schema.integrationOutboxJobs.schoolId, world.schoolA.id));
+      .where(
+        and(
+          eq(schema.integrationOutboxJobs.schoolId, world.schoolA.id),
+          eq(schema.integrationOutboxJobs.type, "sync_sendlit_contact"),
+        ),
+      );
     expect((job!.payload as { ensureSubscribed?: boolean }).ensureSubscribed).toBe(
       false,
     );
diff --git a/apps/api/src/db/schema/index.ts b/apps/api/src/db/schema/index.ts
index 176bfadc9..02b2a347b 100644
--- a/apps/api/src/db/schema/index.ts
+++ b/apps/api/src/db/schema/index.ts
@@ -10,6 +10,7 @@ export * from "./migration.js";
 export * from "./notifications.js";
 export * from "./products.js";
 export * from "./rate-limit.js";
+export * from "./school-sso.js";
 export * from "./schools.js";
 export * from "./spaces.js";
 export * from "./storefront.js";
diff --git a/apps/api/src/db/schema/integrations.ts b/apps/api/src/db/schema/integrations.ts
index 898eff7d7..7b372b6aa 100644
--- a/apps/api/src/db/schema/integrations.ts
+++ b/apps/api/src/db/schema/integrations.ts
@@ -15,7 +15,7 @@ export const integrationProviders = ["sendlit", "medialit"] as const;
 export type IntegrationProvider = (typeof integrationProviders)[number];
 /** Outbox jobs also run for the platform's own sender ("system"), which
  * delivers school email when the school has no mailing team. */
-export type OutboxProvider = IntegrationProvider | "system";
+export type OutboxProvider = IntegrationProvider | "system" | "platform";
 
 export const integrationStatuses = [
   "pending",
@@ -40,6 +40,7 @@ export const integrationJobTypes = [
   "track_sendlit_event",
   "send_school_email",
   "send_system_email",
+  "sync_plan_features",
 ] as const;
 export type IntegrationJobType = (typeof integrationJobTypes)[number];
 
diff --git a/apps/api/src/db/schema/school-sso.ts b/apps/api/src/db/schema/school-sso.ts
new file mode 100644
index 000000000..d096529ed
--- /dev/null
+++ b/apps/api/src/db/schema/school-sso.ts
@@ -0,0 +1,244 @@
+import { sql } from "drizzle-orm";
+import {
+  check,
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  primaryKey,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { user } from "./auth.generated.js";
+import { schoolAccounts, schools } from "./schools.js";
+
+export type SsoConnectionStatus = "draft" | "active" | "suspended" | "disabled";
+export type SsoEnforcement = "optional" | "required_for_domains";
+
+/**
+ * One school's connection to its own identity provider. Whoever controls the
+ * IdP settings can sign in as every learner linked to the connection, so
+ * nothing here is shared between schools.
+ */
+export const schoolSsoConnections = pgTable(
+  "school_sso_connections",
+  {
+    id: uuid("id").primaryKey(),
+    publicId: text("public_id").notNull().unique(), // Prefix: 'sso'
+    schoolId: uuid("school_id")
+      .notNull()
+      .references(() => schools.id, { onDelete: "cascade" }),
+    protocol: text("protocol").$type<"saml" | "oidc">().notNull(),
+    /** `suspended` is set and cleared by the system when the plan changes. */
+    status: text("status").$type<SsoConnectionStatus>().notNull().default("draft"),
+    displayName: text("display_name").notNull(),
+    enforcement: text("enforcement")
+      .$type<SsoEnforcement>()
+      .notNull()
+      .default("optional"),
+    /** Null means the school session default. */
+    maxSessionMinutes: integer("max_session_minutes"),
+    idpEntityId: text("idp_entity_id"),
+    idpSsoUrl: text("idp_sso_url"),
+    idpCertificates: text("idp_certificates")
+      .array()
+      .notNull()
+      .default(sql`'{}'::text[]`),
+    /** The SAML attribute used as the subject when NameID isn't persistent. */
+    subjectAttribute: text("subject_attribute"),
+    oidcIssuer: text("oidc_issuer"),
+    oidcClientId: text("oidc_client_id"),
+    /** Encrypted; written but never read back by the API. */
+    oidcClientSecret: text("oidc_client_secret"),
+    testedAt: timestamp("tested_at", { withTimezone: true }),
+    /** Digest of the settings the successful test ran against. */
+    testedConfigDigest: text("tested_config_digest"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull(),
+  },
+  (table) => [
+    index("school_sso_connections_school_idx").on(table.schoolId),
+    uniqueIndex("school_sso_connections_one_active_uidx")
+      .on(table.schoolId)
+      .where(sql`${table.status} = 'active'`),
+    check(
+      "school_sso_connections_protocol_check",
+      sql`${table.protocol} IN ('saml', 'oidc')`,
+    ),
+    check(
+      "school_sso_connections_status_check",
+      sql`${table.status} IN ('draft', 'active', 'suspended', 'disabled')`,
+    ),
+    check(
+      "school_sso_connections_enforcement_check",
+      sql`${table.enforcement} IN ('optional', 'required_for_domains')`,
+    ),
+  ],
+);
+
+/** Email domains a connection may link identities for, once DNS-verified. */
+export const schoolSsoDomains = pgTable(
+  "school_sso_domains",
+  {
+    id: uuid("id").primaryKey(),
+    connectionId: uuid("connection_id")
+      .notNull()
+      .references(() => schoolSsoConnections.id, { onDelete: "cascade" }),
+    schoolId: uuid("school_id")
+      .notNull()
+      .references(() => schools.id, { onDelete: "cascade" }),
+    /** Lowercase ASCII (punycode), no leading `@`, no trailing dot. */
+    domain: text("domain").notNull(),
+    verificationToken: text("verification_token").notNull(),
+    verifiedAt: timestamp("verified_at", { withTimezone: true }),
+    /** Weekly re-checks in a row that found no TXT record; three clear `verified_at`. */
+    consecutiveCheckFailures: integer("consecutive_check_failures").notNull().default(0),
+    lastCheckedAt: timestamp("last_checked_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+  },
+  (table) => [
+    uniqueIndex("school_sso_domains_school_domain_uidx").on(
+      table.schoolId,
+      table.domain,
+    ),
+    index("school_sso_domains_connection_idx").on(table.connectionId),
+  ],
+);
+
+/** The link between a person at the IdP and one school account. */
+export const schoolSsoIdentities = pgTable(
+  "school_sso_identities",
+  {
+    id: uuid("id").primaryKey(),
+    schoolId: uuid("school_id")
+      .notNull()
+      .references(() => schools.id, { onDelete: "cascade" }),
+    connectionId: uuid("connection_id")
+      .notNull()
+      .references(() => schoolSsoConnections.id, { onDelete: "cascade" }),
+    /** The IdP entity ID or OIDC issuer when the identity was linked. */
+    issuer: text("issuer").notNull(),
+    subject: text("subject").notNull(),
+    schoolAccountId: uuid("school_account_id")
+      .notNull()
+      .references(() => schoolAccounts.id, { onDelete: "cascade" }),
+    lastEmail: text("last_email").notNull(),
+    lastSignedInAt: timestamp("last_signed_in_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+  },
+  (table) => [
+    uniqueIndex("school_sso_identities_connection_subject_uidx").on(
+      table.connectionId,
+      table.subject,
+    ),
+    uniqueIndex("school_sso_identities_connection_account_uidx").on(
+      table.connectionId,
+      table.schoolAccountId,
+    ),
+    index("school_sso_identities_account_idx").on(table.schoolAccountId),
+  ],
+);
+
+/** A sign-in (or test sign-in) started on a school website, open until it returns. */
+export const schoolSsoRequests = pgTable(
+  "school_sso_requests",
+  {
+    id: uuid("id").primaryKey(),
+    requestDigest: text("request_digest").notNull().unique(),
+    schoolId: uuid("school_id")
+      .notNull()
+      .references(() => schools.id, { onDelete: "cascade" }),
+    connectionId: uuid("connection_id")
+      .notNull()
+      .references(() => schoolSsoConnections.id, { onDelete: "cascade" }),
+    nonceDigest: text("nonce_digest").notNull(),
+    returnOrigin: text("return_origin").notNull(),
+    nextPath: text("next_path").notNull(),
+    /** The SAML AuthnRequest ID, or the OIDC state digest. */
+    protocolRequestId: text("protocol_request_id"),
+    oidcNonce: text("oidc_nonce"),
+    pkceVerifier: text("pkce_verifier"),
+    purpose: text("purpose").$type<"sign_in" | "test">().notNull().default("sign_in"),
+    /** Only for `test`: the admin who may read the result. */
+    startedBySchoolAccountId: uuid("started_by_school_account_id").references(
+      () => schoolAccounts.id,
+      { onDelete: "set null" },
+    ),
+    testResult: jsonb("test_result").$type<Record<string, unknown> | null>(),
+    testResultExpiresAt: timestamp("test_result_expires_at", { withTimezone: true }),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    consumedAt: timestamp("consumed_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+  },
+  (table) => [
+    index("school_sso_requests_connection_idx").on(table.connectionId),
+    check(
+      "school_sso_requests_purpose_check",
+      sql`${table.purpose} IN ('sign_in', 'test')`,
+    ),
+  ],
+);
+
+/** SAML assertion IDs already accepted, so a response can't be replayed. */
+export const schoolSsoAssertionIds = pgTable(
+  "school_sso_assertion_ids",
+  {
+    connectionId: uuid("connection_id")
+      .notNull()
+      .references(() => schoolSsoConnections.id, { onDelete: "cascade" }),
+    assertionId: text("assertion_id").notNull(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.connectionId, table.assertionId] }),
+    index("school_sso_assertion_ids_expires_idx").on(table.expiresAt),
+  ],
+);
+
+/** Audit log: config changes, activations, domain checks, failure reason codes. */
+export const schoolSsoEvents = pgTable(
+  "school_sso_events",
+  {
+    id: uuid("id").primaryKey(),
+    schoolId: uuid("school_id")
+      .notNull()
+      .references(() => schools.id, { onDelete: "cascade" }),
+    connectionId: uuid("connection_id").references(() => schoolSsoConnections.id, {
+      onDelete: "set null",
+    }),
+    actorSchoolAccountId: uuid("actor_school_account_id").references(
+      () => schoolAccounts.id,
+      { onDelete: "set null" },
+    ),
+    action: text("action").notNull(),
+    /** A reason code only; never assertion XML, attributes or emails. */
+    reason: text("reason"),
+    metadata: jsonb("metadata")
+      .$type<Record<string, unknown>>()
+      .notNull()
+      .default(sql`'{}'::jsonb`),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+  },
+  (table) => [
+    index("school_sso_events_school_created_idx").on(table.schoolId, table.createdAt),
+  ],
+);
+
+/**
+ * Users made only to own an SSO-created school account, because
+ * `school_accounts.user_id` must point at a `user`. They have no password,
+ * no `account` rows and an unreachable `.invalid` address, and Better Auth
+ * refuses to start a platform session for them. Kept in its own table so
+ * Better Auth's schema stays untouched.
+ */
+export const ssoShadowUsers = pgTable("sso_shadow_users", {
+  userId: text("user_id")
+    .primaryKey()
+    .references(() => user.id, { onDelete: "cascade" }),
+  schoolId: uuid("school_id")
+    .notNull()
+    .references(() => schools.id, { onDelete: "cascade" }),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+});
diff --git a/apps/api/src/db/schema/schools.ts b/apps/api/src/db/schema/schools.ts
index cc59f4e64..3eb1e91f6 100644
--- a/apps/api/src/db/schema/schools.ts
+++ b/apps/api/src/db/schema/schools.ts
@@ -1,6 +1,7 @@
 import type { MediaRef } from "@courselit/api-contract";
 import { sql } from "drizzle-orm";
 import {
+  type AnyPgColumn,
   boolean,
   check,
   index,
@@ -13,6 +14,7 @@ import {
   uuid,
 } from "drizzle-orm/pg-core";
 import { user } from "./auth.generated.js";
+import { schoolSsoConnections } from "./school-sso.js";
 
 export const schools = pgTable("schools", {
   id: uuid("id").primaryKey(),
@@ -24,6 +26,15 @@ export const schools = pgTable("schools", {
     .notNull()
     .default("active"),
   locale: text("locale").notNull().default("en"),
+  /**
+   * Sign-in methods the school has turned on. SSO isn't listed: it is on
+   * exactly when the school has an active connection.
+   */
+  loginMethods: text("login_methods")
+    .array()
+    .$type<("email" | "google")[]>()
+    .notNull()
+    .default(sql`'{email}'::text[]`),
   currency: text("currency").notNull().default("USD"),
   /** Encrypted provider credentials and the school's selected checkout gateway. */
   paymentSettingsEncrypted: text("payment_settings_encrypted"),
@@ -31,7 +42,12 @@ export const schools = pgTable("schools", {
   codeInjectionBody: text("code_injection_body").notNull().default(""),
   createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
   updatedAt: timestamp("updated_at", { withTimezone: true }).notNull(),
-});
+}, (table) => [
+  check(
+    "schools_login_methods_check",
+    sql`${table.loginMethods} <@ ARRAY['email', 'google']::text[]`,
+  ),
+]);
 
 /** Setup wizard progress and onboarding checklist state, one row per school. */
 export const schoolOnboarding = pgTable("school_onboarding", {
@@ -183,8 +199,13 @@ export const schoolSessions = pgTable(
       .references(() => user.id, { onDelete: "cascade" }),
     tokenDigest: text("token_digest").notNull().unique(),
     authenticationMethod: text("authentication_method")
-      .$type<"email" | "google">()
+      .$type<"email" | "google" | "sso">()
       .notNull(),
+    /** Set for `sso` sessions: ending the connection ends the session. */
+    ssoConnectionId: uuid("sso_connection_id").references(
+      (): AnyPgColumn => schoolSsoConnections.id,
+      { onDelete: "cascade" },
+    ),
     authenticatedAt: timestamp("authenticated_at", { withTimezone: true }).notNull(),
     expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
@@ -215,8 +236,15 @@ export const schoolAuthTickets = pgTable(
       .notNull()
       .references(() => user.id, { onDelete: "cascade" }),
     authenticationMethod: text("authentication_method")
-      .$type<"email" | "google">()
+      .$type<"email" | "google" | "sso">()
       .notNull(),
+    /** Set for `sso` tickets: the connection the session will belong to. */
+    ssoConnectionId: uuid("sso_connection_id").references(
+      (): AnyPgColumn => schoolSsoConnections.id,
+      { onDelete: "cascade" },
+    ),
+    /** Set for `sso` tickets: when the IdP session ends, if earlier than the default. */
+    sessionExpiresAt: timestamp("session_expires_at", { withTimezone: true }),
     expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
     consumedAt: timestamp("consumed_at", { withTimezone: true }),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
diff --git a/apps/api/src/dispatch.ts b/apps/api/src/dispatch.ts
index 495c2aadf..008156347 100644
--- a/apps/api/src/dispatch.ts
+++ b/apps/api/src/dispatch.ts
@@ -55,6 +55,7 @@ import {
   learnerAvatarMediaAuthorizationBodySchema,
   learnerEmailCodeBodySchema,
   learnerStartGoogleBodySchema,
+  learnerStartSsoBodySchema,
   learnerVerifyEmailCodeBodySchema,
   learnerAvatarMediaFinalizeBodySchema,
   learnerCommunityMediaAuthorizationBodySchema,
@@ -372,6 +373,10 @@ import {
   updateSchoolCurrency,
   updateSchoolPaymentSettings,
 } from "./schools.js";
+import { CLIENT_IP_HEADER } from "./auth/api-key-throttle.js";
+import { startLearnerSsoSignIn } from "./learner-sso-sign-in.js";
+import { usableLearnerMethods } from "./login-methods.js";
+import { handleSsoAdminRequest } from "./sso-admin-routes.js";
 import {
   getScormRuntimeState,
   processScormPackage,
@@ -881,6 +886,7 @@ export async function dispatch(
                 schoolPublicId: learner.school.publicId,
                 learnerId: learner.learner.id,
                 learnerPublicId: learner.learner.publicId,
+                authenticationMethod: learner.authenticationMethod,
               })
             : await getPublicCommunity(deps.db, publicSchool, segment(1));
           return respond(result);
@@ -892,13 +898,15 @@ export async function dispatch(
           );
         }
         if (route === "/login-methods") {
-          const hasGoogle = Boolean(
-            process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET,
-          );
+          // What the school's sign-in policy allows right now, including SSO
+          // when the school has an active connection and the plan for it.
+          const usable = await usableLearnerMethods(deps.db, deps.billing.billing, school);
           return ok({
             schoolId: school.publicId,
-            loginMethods: hasGoogle ? ["email", "google"] : ["email"],
-            hasGoogle,
+            loginMethods: usable.methods,
+            hasGoogle: usable.methods.includes("google"),
+            hasSso: usable.methods.includes("sso"),
+            ssoDisplayName: usable.ssoDisplayName,
           });
         }
         if ((routeMatch = /^\/checkout-sessions\/([^/]+)$/.exec(route))) {
@@ -1045,6 +1053,29 @@ export async function dispatch(
       );
       return result.ok ? { status: 200, body: result.value } : errorResponse(result.error);
     }
+    if (request.method === "POST" && path === "/v1/learner/auth/sso") {
+      const parsed = learnerStartSsoBodySchema.safeParse(request.body ?? {});
+      if (!parsed.success) {
+        return errorResponse(createPlatformError("validation_failed"));
+      }
+      const schoolPublicId = headerSchoolId(request.headers);
+      if (!schoolPublicId) return errorResponse(createPlatformError("tenant_required"));
+      const clientIp = request.headers[CLIENT_IP_HEADER];
+      const result = await startLearnerSsoSignIn(
+        deps.db,
+        {
+          schoolPublicId,
+          host: parsed.data.host,
+          nonce: parsed.data.nonce,
+          next: parsed.data.next,
+          publicApiUrl: deps.auth.publicApiUrl,
+          billing: deps.billing.billing,
+          clientIp: Array.isArray(clientIp) ? clientIp[0] : clientIp,
+        },
+        deps.clock,
+      );
+      return result.ok ? { status: 200, body: result.value } : errorResponse(result.error);
+    }
     if (request.method === "POST" && path === "/v1/learner/auth/sign-out") {
       if (learnerAuth.kind === "authenticated") {
         await signOutLearner(deps.db, learnerAuth.value);
@@ -1080,6 +1111,7 @@ export async function dispatch(
         schoolPublicId: learnerAuth.value.school.publicId,
         learnerId: learnerAuth.value.learner.id,
         learnerPublicId: learnerAuth.value.learner.publicId,
+        authenticationMethod: learnerAuth.value.authenticationMethod,
       };
       const learnerCommunitySchool = {
         schoolId: learnerAuth.value.school.id,
@@ -4617,6 +4649,9 @@ export async function dispatch(
       return result.ok ? { status: 204, body: undefined } : errorResponse(result.error);
     }
 
+    const ssoResponse = await handleSsoAdminRequest(deps, request, path, school.value);
+    if (ssoResponse) return ssoResponse;
+
     if (request.method === "GET" && path === "/v1/school/hosts") {
       if (!context.permissions.has("school:read")) {
         return errorResponse(createPlatformError("forbidden"));
diff --git a/apps/api/src/express-app.ts b/apps/api/src/express-app.ts
index 42a502a07..13524636d 100644
--- a/apps/api/src/express-app.ts
+++ b/apps/api/src/express-app.ts
@@ -26,6 +26,7 @@ import type { DispatchDeps } from "./deps.js";
 import { dispatch } from "./dispatch.js";
 import { serveLearnerDownload } from "./downloads.js";
 import { registerLearnerGoogleRoutes } from "./learner-google-routes.js";
+import { registerLearnerSsoRoutes } from "./learner-sso-routes.js";
 import { assertLearnerSchool, authenticateLearner, isSecureCookieUrl } from "./learners.js";
 import { createOpenApiDocument } from "./openapi.js";
 import { authenticateHttpRequest } from "./auth/authenticate.js";
@@ -118,6 +119,7 @@ export function createExpressApp(deps: DispatchDeps): Express {
   );
   app.all(`${AUTH_BASE_PATH}/*`, authNodeHandler);
   registerLearnerGoogleRoutes(app, deps);
+  registerLearnerSsoRoutes(app, deps);
   const captcha = captchaSettings();
   app.use(
     createOAuthPagesRouter({
@@ -514,6 +516,7 @@ export function createExpressApp(deps: DispatchDeps): Express {
     learnerRequestEmailCode: forward,
     learnerVerifyEmailCode: forward,
     learnerStartGoogleSignIn: forward,
+    learnerStartSsoSignIn: forward,
     consumeSchoolAuthTicket: forward,
     learnerSignOut: forward,
     learnerMe: forward,
@@ -579,6 +582,21 @@ export function createExpressApp(deps: DispatchDeps): Express {
     createSchoolHost: forward,
     verifySchoolHost: forward,
     deleteSchoolHost: forward,
+    getSchoolLoginMethods: forward,
+    updateSchoolLoginMethods: forward,
+    listSsoConnections: forward,
+    createSsoConnection: forward,
+    getSsoConnection: forward,
+    updateSsoConnection: forward,
+    deleteSsoConnection: forward,
+    addSsoDomain: forward,
+    verifySsoDomain: forward,
+    deleteSsoDomain: forward,
+    startSsoConnectionTest: forward,
+    getSsoConnectionTestResult: forward,
+    activateSsoConnection: forward,
+    disableSsoConnection: forward,
+    unlinkSsoIdentity: forward,
     createSchool: forward,
     selectSchool: forward,
     listApiKeys: forward,
diff --git a/apps/api/src/integration-provisioning.ts b/apps/api/src/integration-provisioning.ts
index b22813e79..9556697f7 100644
--- a/apps/api/src/integration-provisioning.ts
+++ b/apps/api/src/integration-provisioning.ts
@@ -32,6 +32,7 @@ import {
 import type { TrackSendLitEventPayload } from "./membership-events.js";
 import type { SendSchoolEmailPayload } from "./school-emails.js";
 import { sendSystemMail } from "./system-mail.js";
+import { deleteShadowUserIfOrphaned } from "./shadow-users.js";
 import type { AppDb } from "./types.js";
 import {
   decryptIntegrationSecret,
@@ -606,14 +607,20 @@ async function eraseSendLitContactJob(
       }
     }
 
-    await db
-      .delete(schema.schoolAccounts)
-      .where(
-        and(
-          eq(schema.schoolAccounts.id, payload.schoolAccountId),
-          eq(schema.schoolAccounts.schoolId, job.schoolId),
-        ),
-      );
+    await db.transaction(async (transaction) => {
+      const tx = transaction as unknown as AppDb;
+      const [removed] = await tx
+        .delete(schema.schoolAccounts)
+        .where(
+          and(
+            eq(schema.schoolAccounts.id, payload.schoolAccountId!),
+            eq(schema.schoolAccounts.schoolId, job.schoolId),
+          ),
+        )
+        .returning({ userId: schema.schoolAccounts.userId });
+      // An SSO-created account's shadow user goes with its last school account.
+      if (removed) await deleteShadowUserIfOrphaned(tx, removed.userId);
+    });
   } finally {
     await db.execute(sql`SELECT pg_advisory_unlock(hashtext(${lockKey}))`);
   }
@@ -705,7 +712,7 @@ async function failJob(
     message = "sendlit_quota_exceeded";
     actionRequired = true;
   }
-  if (job.type === "provision_sendlit" && job.provider !== "system") {
+  if (job.type === "provision_sendlit" && (job.provider === "sendlit" || job.provider === "medialit")) {
     await updateIntegration(db, job.schoolId, job.provider, {
       status: actionRequired ? "action_required" : "pending",
       lastError: message,
@@ -776,6 +783,56 @@ export async function processNextIntegrationJob(
   return false;
 }
 
+/** How many times a platform job (plan sync) is retried before it is parked. */
+const MAX_PLATFORM_JOB_ATTEMPTS = 8;
+
+/**
+ * Runs one ready platform job, such as `sync_plan_features`, which the
+ * billing hook queues. Returns whether a job was processed. A failing job is
+ * retried with backoff and never touches the billing write that queued it.
+ */
+export async function processNextPlatformJob(
+  db: AppDb,
+  clock: Clock,
+  logger: Logger,
+  run: (job: { type: string; schoolId: string; payload: Record<string, unknown> }) => Promise<void>,
+): Promise<boolean> {
+  const now = clock.now();
+  await db
+    .update(schema.integrationOutboxJobs)
+    .set({ status: "pending", nextAttemptAt: now, updatedAt: now })
+    .where(
+      and(
+        eq(schema.integrationOutboxJobs.provider, "platform"),
+        eq(schema.integrationOutboxJobs.status, "processing"),
+        lt(
+          schema.integrationOutboxJobs.updatedAt,
+          new Date(now.getTime() - 15 * 60 * 1000),
+        ),
+      ),
+    );
+  const job = await claimNextJob(db, now, ["platform"]);
+  if (!job) return false;
+  try {
+    await run({ type: job.type, schoolId: job.schoolId, payload: job.payload });
+    await finishJob(db, job, clock);
+  } catch (error) {
+    const actionRequired = job.attempts + 1 >= MAX_PLATFORM_JOB_ATTEMPTS;
+    await failJob(db, job, clock, error, actionRequired);
+    logger.warn(
+      {
+        jobId: job.id,
+        schoolId: job.schoolId,
+        type: job.type,
+        attempts: job.attempts + 1,
+        error: safeError(error),
+      },
+      "Platform job failed",
+    );
+  }
+  return true;
+}
+
 /** How many times the platform sender retries one email before giving up. */
 const MAX_SYSTEM_EMAIL_ATTEMPTS = 8;
 
diff --git a/apps/api/src/invitations.ts b/apps/api/src/invitations.ts
index f4053f687..d6bef0a2f 100644
--- a/apps/api/src/invitations.ts
+++ b/apps/api/src/invitations.ts
@@ -19,6 +19,7 @@ import { and, eq, gt, isNull, sql } from "drizzle-orm";
 import * as schema from "./db/schema/index.js";
 import { queueSendLitContactSync } from "./contacts.js";
 import { ensureSchoolAccount } from "./learners.js";
+import { findSsoBackedAccount } from "./shadow-users.js";
 import { parsePermissions } from "./permissions.js";
 import type { AppDb } from "./types.js";
 
@@ -124,6 +125,21 @@ export async function createInvitation(
       };
     }
 
+    // An account an identity provider can sign in as never joins the team.
+    if (
+      await findSsoBackedAccount(tx as unknown as AppDb, {
+        schoolId: ctx.tenantId!,
+        email: normalized,
+      })
+    ) {
+      return {
+        ok: false as const,
+        error: createPlatformError("conflict", {
+          safeDetails: { reason: "sso_linked_account" },
+        }),
+      };
+    }
+
     // 3. Check if there's already a pending invitation
     const existingInvitation = await tx
       .select({ id: schema.invitations.id })
@@ -239,6 +255,20 @@ export async function resendInvitation(
       }
     }
 
+    if (
+      await findSsoBackedAccount(tx as unknown as AppDb, {
+        schoolId: invitation.schoolId,
+        email: invitation.normalizedEmail,
+      })
+    ) {
+      return {
+        ok: false as const,
+        error: createPlatformError("conflict", {
+          safeDetails: { reason: "sso_linked_account" },
+        }),
+      };
+    }
+
     const token = randomBytes(32).toString("base64url");
     const now = clock.now();
     const expiresAt = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);
@@ -484,6 +514,23 @@ export async function acceptTeamInvitation(
       }
     }
 
+    // Checked before `ensureSchoolAccount`, which would move an SSO-backed
+    // account with this address onto the accepting user.
+    if (
+      await findSsoBackedAccount(tx as unknown as AppDb, {
+        schoolId: invitation.schoolId,
+        userId: ctx.principalId,
+        email: actor.email,
+      })
+    ) {
+      return {
+        ok: false as const,
+        error: createPlatformError("conflict", {
+          safeDetails: { reason: "sso_linked_account" },
+        }),
+      };
+    }
+
     // 3. Ensure actor's school account exists
     const schoolAccount = await ensureSchoolAccount(tx as unknown as AppDb, {
       schoolId: invitation.schoolId,
diff --git a/apps/api/src/learner-auth.test.ts b/apps/api/src/learner-auth.test.ts
index 37c351140..463f137f3 100644
--- a/apps/api/src/learner-auth.test.ts
+++ b/apps/api/src/learner-auth.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from "bun:test";
+import { afterAll, beforeEach, describe, expect, it } from "bun:test";
 import type { Server } from "node:http";
 import type { AddressInfo } from "node:net";
 import { and, eq } from "drizzle-orm";
@@ -15,6 +15,19 @@ import { learnerNameIsPlaceholder } from "./learners.js";
 import { createPgliteRuntime, freezeRuntimeClock } from "./runtime.js";
 import { seedWorld } from "./seed.js";
 
+
+// These tests decide for themselves whether Google keys exist. Bun loads the
+// developer's .env, so start each test without them and restore them after.
+const savedGoogleKeys = [process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET];
+beforeEach(() => {
+  delete process.env.GOOGLE_CLIENT_ID;
+  delete process.env.GOOGLE_CLIENT_SECRET;
+});
+afterAll(() => {
+  if (savedGoogleKeys[0] !== undefined) process.env.GOOGLE_CLIENT_ID = savedGoogleKeys[0];
+  if (savedGoogleKeys[1] !== undefined) process.env.GOOGLE_CLIENT_SECRET = savedGoogleKeys[1];
+});
+
 describe.serial("learner authentication", () => {
   it("does not expose legacy unauthenticated learner OTP endpoints", async () => {
     const clock = freezeRuntimeClock(new Date("2026-03-01T00:00:00.000Z"));
@@ -70,7 +83,7 @@ describe.serial("learner authentication", () => {
     });
     expect(unknownSchoolRes.status).toBe(404);
 
-    // Admin login-methods endpoint no longer exists, and routes outside the
+    // The admin endpoint reads the same settings, and routes outside the
     // contract are closed to every credential.
     const adminRes = await dispatch(runtime, {
       method: "GET",
@@ -80,7 +93,17 @@ describe.serial("learner authentication", () => {
         cookie: world.owner.sessionCookie,
       },
     });
-    expect(adminRes.status).toBe(403);
+    expect(adminRes.status).toBe(200);
+    expect(adminRes.body).toMatchObject({ loginMethods: ["email"], googleAvailable: false });
+    const unknownRoute = await dispatch(runtime, {
+      method: "GET",
+      path: "/v1/school/login-methods-legacy",
+      headers: {
+        "x-school-id": world.schoolA.publicId,
+        cookie: world.owner.sessionCookie,
+      },
+    });
+    expect(unknownRoute.status).toBe(403);
 
     await runtime.close();
   });
@@ -324,6 +347,9 @@ describe.serial("learner authentication", () => {
     });
     try {
       const world = await seedWorld(runtime, clock);
+      await runtime.db
+        .update(schema.schools)
+        .set({ loginMethods: ["email", "google"] });
       const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
       const email = "victim@example.com";
 
@@ -417,6 +443,9 @@ describe.serial("learner authentication", () => {
     };
     process.env.GOOGLE_CLIENT_ID = "test-google-client";
     process.env.GOOGLE_CLIENT_SECRET = "test-google-secret";
+    await runtime.db
+      .update(schema.schools)
+      .set({ loginMethods: ["email", "google"] });
     try {
       const host = "school-a.localhost:3001";
       const nonce = "n".repeat(43);
@@ -548,6 +577,9 @@ describe.serial("learner authentication", () => {
     });
     try {
       const world = await seedWorld(runtime, clock);
+      await runtime.db
+        .update(schema.schools)
+        .set({ loginMethods: ["email", "google"] });
       const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
       const started = await startLearnerGoogleSignIn(
         runtime.db,
diff --git a/apps/api/src/learner-session-user-id.test.ts b/apps/api/src/learner-session-user-id.test.ts
new file mode 100644
index 000000000..86a4b0da1
--- /dev/null
+++ b/apps/api/src/learner-session-user-id.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it } from "bun:test";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+// `LearnerSession.userId` can be a real platform user for an SSO learner, so
+// it must never leave the school. Nothing reads it today; this scan keeps it
+// that way. Reads of a school account's `userId` are scanned the same way.
+
+function sourceFiles(dir: string): string[] {
+  return readdirSync(dir).flatMap((name) => {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) return sourceFiles(path);
+    return path.endsWith(".ts") && !path.endsWith(".test.ts") ? [path] : [];
+  });
+}
+
+const PLATFORM_TABLES = /schema\.(user|session|account|selectedSchools|memberships)\b/;
+
+// Every place a learner session's or school account's user id is read.
+const ALLOWED_READS: Record<string, number> = {
+  // building the session from its own row
+  "learners.ts": 1,
+  // admin team screens comparing team accounts with the signed-in admin
+  "team.ts": 2,
+  // reading a school account's own user inside one school (shadow-user check)
+  "learner-sso.ts": 1,
+  // creating a Better Auth session, not reading a learner session
+  "auth/options.ts": 1,
+};
+
+describe("LearnerSession.userId", () => {
+  it("is never read outside the learner module", () => {
+    const base = join(import.meta.dir);
+    const reads: Record<string, number> = {};
+    const pattern =
+      /(?<!schema\.)\b(?:learnerAuth\.value|learnerSession|learner|session|schoolAccount|account)\.userId\b/g;
+    for (const file of sourceFiles(base)) {
+      const rel = file.slice(base.length + 1);
+      if (rel.startsWith("migrations/") || rel.startsWith("db/")) continue;
+      const matches = readFileSync(file, "utf8").match(pattern);
+      if (matches) reads[rel] = matches.length;
+    }
+    expect(reads).toEqual(ALLOWED_READS);
+  });
+
+  it("no file that handles learner sessions queries platform-wide tables with a session user id", () => {
+    const base = join(import.meta.dir);
+    for (const file of ["dispatch.ts", "express-app.ts", "learner-sign-in.ts"]) {
+      const source = readFileSync(join(base, file), "utf8");
+      for (const line of source.split("\n")) {
+        if (/(?<!schema\.)\b(?:learnerAuth\.value|learnerSession|session)\.userId\b/.test(line)) {
+          expect(PLATFORM_TABLES.test(line)).toBe(false);
+        }
+      }
+    }
+  });
+});
diff --git a/apps/api/src/learner-sign-in.ts b/apps/api/src/learner-sign-in.ts
index 2dee34d77..c44e7b15c 100644
--- a/apps/api/src/learner-sign-in.ts
+++ b/apps/api/src/learner-sign-in.ts
@@ -20,6 +20,8 @@ import {
   signInLearnerWithIdentity,
 } from "./learners.js";
 import { queueSchoolEmail, renderSchoolEmail } from "./school-emails.js";
+import { isShadowUserEmail } from "./shadow-users.js";
+import { type SignInMethod, sessionMethodAllowed } from "./sign-in-policy.js";
 import { loadSchoolByPublicId, resolveSchoolByHost } from "./schools.js";
 import type { AppDb } from "./types.js";
 
@@ -40,6 +42,22 @@ type Result<T> = { ok: true; value: T } | { ok: false; error: PlatformError };
 const signInFailed = (reason: string) =>
   createPlatformError("unauthenticated", { safeDetails: { reason } });
 
+/**
+ * Refuse a sign-in method the school has switched off, or that its SSO
+ * enforcement forbids for this address, before anything is sent or admitted.
+ */
+async function methodRefusal(
+  db: AppDb,
+  school: typeof schema.schools.$inferSelect,
+  method: SignInMethod,
+  email: string | null,
+): Promise<PlatformError | null> {
+  const policy = await sessionMethodAllowed(db, { school, email, method });
+  return policy.allowed
+    ? null
+    : createPlatformError("forbidden", { safeDetails: { reason: policy.reason } });
+}
+
 function codeDigest(codeId: string, code: string): string {
   return digestToken(`${codeId}:${code}`);
 }
@@ -83,6 +101,11 @@ export async function requestLearnerEmailCode(
   const school = await loadSchoolByPublicId(db, input.schoolPublicId);
   if (!school) return { ok: false, error: createPlatformError("tenant_required") };
   const email = normalizeEmail(input.email);
+  if (isShadowUserEmail(email)) {
+    return { ok: false, error: createPlatformError("validation_failed") };
+  }
+  const refusal = await methodRefusal(db, school, "email", email);
+  if (refusal) return { ok: false, error: refusal };
   const now = clock.now();
   const recent = await db
     .select({
@@ -227,7 +250,7 @@ export async function verifyLearnerEmailCode(
   };
 }
 
-function originForHost(host: string): string | null {
+export function originForHost(host: string): string | null {
   const value = host.trim().toLowerCase();
   if (!/^[a-z0-9.-]+(:\d{1,5})?$/.test(value)) return null;
   const hostname = value.replace(/:\d+$/, "");
@@ -264,6 +287,9 @@ export async function startLearnerGoogleSignIn(
   if (!origin || !school || school.publicId !== input.schoolPublicId) {
     return { ok: false, error: createPlatformError("tenant_forbidden") };
   }
+  // The address isn't known until Google returns; the finish step checks it.
+  const refusal = await methodRefusal(db, school, "google", null);
+  if (refusal) return { ok: false, error: refusal };
   const token = randomBytes(32).toString("base64url");
   const now = clock.now();
   await db.insert(schema.schoolLoginRequests).values({
@@ -331,6 +357,8 @@ export async function finishLearnerGoogleSignIn(
     .where(eq(schema.schools.id, request.schoolId))
     .limit(1);
   if (!school) return { ok: false, error: createPlatformError("tenant_required") };
+  const refusal = await methodRefusal(db, school, "google", input.user.email);
+  if (refusal) return { ok: false, error: refusal };
   const admitted = await admitLearner(
     db,
     {
@@ -382,7 +410,11 @@ export async function createSchoolAuthTicket(
     schoolId: string;
     schoolAccountId: string;
     userId: string;
-    authenticationMethod: "email" | "google";
+    authenticationMethod: "email" | "google" | "sso";
+    /** For `sso`: the connection the session will belong to. */
+    ssoConnectionId?: string | null;
+    /** For `sso`: the IdP's session end, when earlier than the default. */
+    sessionExpiresAt?: Date | null;
     nonceDigest: string;
     clock: Clock;
   },
@@ -397,6 +429,8 @@ export async function createSchoolAuthTicket(
     ticketDigest: digestToken(ticket),
     nonceDigest: input.nonceDigest,
     authenticationMethod: input.authenticationMethod,
+    ssoConnectionId: input.ssoConnectionId ?? null,
+    sessionExpiresAt: input.sessionExpiresAt ?? null,
     expiresAt: new Date(now.getTime() + TICKET_TTL_MS),
     createdAt: now,
   });
@@ -447,10 +481,17 @@ export async function consumeSchoolAuthTicket(
     schoolAccount: account,
     userId: ticket.userId,
     authenticationMethod: ticket.authenticationMethod,
+    ssoConnectionId: ticket.ssoConnectionId,
+    expiresAt: ticket.sessionExpiresAt,
     clock,
   });
+  if (!issued.ok) return issued;
   return {
     ok: true,
-    value: { sessionToken: issued.token, dto: issued.dto, session: issued.session },
+    value: {
+      sessionToken: issued.value.token,
+      dto: issued.value.dto,
+      session: issued.value.session,
+    },
   };
 }
diff --git a/apps/api/src/learner-sso-flow.test.ts b/apps/api/src/learner-sso-flow.test.ts
new file mode 100644
index 000000000..a212557b9
--- /dev/null
+++ b/apps/api/src/learner-sso-flow.test.ts
@@ -0,0 +1,345 @@
+import { describe, expect, it } from "bun:test";
+import { eq } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { dispatch } from "./dispatch.js";
+import { attackerKeys, iso } from "./sso-protocol/test-idp.js";
+import { NONCE, ownerHeaders, ssoSetup, ticketFrom } from "./test-sso-flow.js";
+
+const count = async (runtime: Awaited<ReturnType<typeof ssoSetup>>["runtime"], table: any) =>
+  (await runtime.db.select().from(table)).length;
+
+describe.serial("learner SSO sign-in flow", () => {
+  it("signs a learner in from the storefront start to an sso school session", async () => {
+    const t = await ssoSetup({ maxSessionMinutes: 5 });
+    try {
+      const { started, token, requestId, redirect } = await t.startSignIn("/dashboard/courses");
+      expect(started.status).toBe(200);
+      expect(redirect!.status).toBe(302);
+      const idp = new URL(redirect!.headers.get("location")!);
+      expect(idp.origin + idp.pathname).toBe("https://idp.example/sso");
+      expect(idp.searchParams.get("RelayState")).toBe(token!);
+      expect(requestId).toBeTruthy();
+
+      const acs = await t.acs(t.response(requestId!, { sessionNotOnOrAfter: iso(3_600_000) }), token!);
+      expect(acs.status).toBe(302);
+      const location = new URL(acs.headers.get("location")!);
+      expect(location.origin).toBe("http://school-a.localhost:3001");
+      expect(location.pathname).toBe("/auth/complete");
+      expect(location.searchParams.get("next")).toBe("/dashboard/courses");
+      const ticket = ticketFrom(location.toString())!;
+      expect(ticket).toBeTruthy();
+
+      // Only the browser that started it (the nonce cookie) can redeem it.
+      expect((await t.redeem(ticket, "x".repeat(43))).status).toBe(401);
+      const redeemed = await t.redeem(ticket);
+      expect(redeemed.status).toBe(200);
+      expect(redeemed.body).toMatchObject({ email: "alice@acme.com" });
+      const [session] = await t.runtime.db.select().from(schema.schoolSessions)
+        .where(eq(schema.schoolSessions.authenticationMethod, "sso"));
+      expect(session!.ssoConnectionId).toBe(t.connection.id);
+      // max_session_minutes (5) is earlier than SessionNotOnOrAfter (1 hour).
+      const minutes = (session!.expiresAt.getTime() - t.clock.now().getTime()) / 60_000;
+      expect(minutes).toBeGreaterThan(4);
+      expect(minutes).toBeLessThanOrEqual(5);
+      // A ticket works once.
+      expect((await t.redeem(ticket)).status).toBe(401);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("honours the IdP's SessionNotOnOrAfter when it is the earliest", async () => {
+    const t = await ssoSetup({ maxSessionMinutes: 600 });
+    try {
+      const { token, requestId } = await t.startSignIn();
+      const acs = await t.acs(t.response(requestId!, { sessionNotOnOrAfter: iso(10 * 60_000) }), token!);
+      const ticket = ticketFrom(acs.headers.get("location"))!;
+      expect((await t.redeem(ticket)).status).toBe(200);
+      const [session] = await t.runtime.db.select().from(schema.schoolSessions)
+        .where(eq(schema.schoolSessions.authenticationMethod, "sso"));
+      const minutes = (session!.expiresAt.getTime() - t.clock.now().getTime()) / 60_000;
+      expect(minutes).toBeGreaterThan(9);
+      expect(minutes).toBeLessThanOrEqual(10.1);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("does not use up the request on a forged POST that carries a valid RelayState", async () => {
+    const t = await ssoSetup();
+    try {
+      const { token, requestId } = await t.startSignIn();
+      const forged = await t.acs(
+        t.response(requestId!, {}, {}, { keys: attackerKeys }),
+        token!,
+      );
+      expect(forged.status).toBe(302);
+      expect(forged.headers.get("location")).toContain("/login?error=sso");
+      expect(ticketFrom(forged.headers.get("location"))).toBeNull();
+      const [row] = await t.runtime.db.select().from(schema.schoolSsoRequests);
+      expect(row!.consumedAt).toBeNull();
+      const events = await t.runtime.db.select().from(schema.schoolSsoEvents);
+      expect(events.some((event) => event.action === "sign_in.failed" && event.reason === "signature_invalid")).toBe(true);
+      // The real response for the same request still works.
+      const real = await t.acs(t.response(requestId!), token!);
+      expect(ticketFrom(real.headers.get("location"))).toBeTruthy();
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("rejects a replayed response and an unknown RelayState", async () => {
+    const t = await ssoSetup();
+    try {
+      const { token, requestId } = await t.startSignIn();
+      const xml = t.response(requestId!);
+      expect(ticketFrom((await t.acs(xml, token!)).headers.get("location"))).toBeTruthy();
+      const replay = await t.acs(xml, token!);
+      expect(ticketFrom(replay.headers.get("location"))).toBeNull();
+      const unknown = await t.acs(xml, "nope");
+      expect(unknown.status).toBe(404);
+      expect(await t.runtime.db.select().from(schema.schoolSessions).then((r) => r.length)).toBe(0);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("opening the start link twice can't replace the AuthnRequest ID", async () => {
+    const t = await ssoSetup();
+    try {
+      const { started } = await t.startSignIn();
+      const url = new URL((started.body as { url: string }).url);
+      const again = await fetch(`${t.appBase}${url.pathname}${url.search}`, { redirect: "manual" });
+      expect(again.status).toBe(404);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("never logs or returns assertion contents on failure", async () => {
+    const t = await ssoSetup();
+    try {
+      const { token, requestId } = await t.startSignIn();
+      const body = await (await t.acs(t.response(requestId!, { audience: "https://other/entity" }), token!)).text();
+      expect(body).not.toContain("alice@acme.com");
+      const events = await t.runtime.db.select().from(schema.schoolSsoEvents);
+      expect(JSON.stringify(events)).not.toContain("alice@acme.com");
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("answers identically for unknown, disabled and suspended connections", async () => {
+    const answers: string[] = [];
+    for (const status of ["disabled", "suspended"] as const) {
+      const t = await ssoSetup({ status });
+      try {
+        const path = t.connectionPath;
+        for (const [method, suffix] of [["GET", "/start?request=abc"], ["GET", "/metadata"], ["POST", "/acs"]] as const) {
+          const r = await fetch(`${t.appBase}${path}${suffix}`, { method, redirect: "manual", ...(method === "POST" ? { headers: { "content-type": "application/x-www-form-urlencoded" }, body: "SAMLResponse=x&RelayState=y" } : {}) });
+          answers.push(`${r.status}:${await r.text()}`);
+        }
+        const missing = await fetch(`${t.appBase}/learner-login/sso/sso_missing/metadata`, { redirect: "manual" });
+        answers.push(`${missing.status}:${await missing.text()}`);
+        // And a start from the storefront is refused.
+        const started = await t.startSignIn();
+        expect(started.started.status).toBe(403);
+      } finally {
+        await t.close();
+      }
+    }
+    expect(new Set(answers).size).toBe(1);
+    expect(answers[0]!.startsWith("404:")).toBe(true);
+  });
+
+  it("serves SP metadata whose entity ID and ACS URL are the per-connection ones", async () => {
+    const t = await ssoSetup();
+    try {
+      const response = await fetch(`${t.appBase}${t.connectionPath}/metadata`);
+      expect(response.status).toBe(200);
+      const xml = await response.text();
+      expect(xml).toContain(t.urls.entityId);
+      expect(xml).toContain(t.urls.acsUrl);
+      expect(t.urls.acsUrl).toBe(`${t.runtime.auth.publicApiUrl}/learner-login/sso/${t.connection.publicId}/acs`);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("refuses a body over 256 KB at the ACS", async () => {
+    const t = await ssoSetup();
+    try {
+      const big = await fetch(`${t.appBase}${t.connectionPath}/acs`, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: `SAMLResponse=${"A".repeat(300 * 1024)}&RelayState=x`,
+      });
+      expect(big.status).toBe(413);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("refuses at the ACS when the connection is disabled mid-flight, and ends its sessions", async () => {
+    const t = await ssoSetup();
+    try {
+      const { token, requestId } = await t.startSignIn();
+      const ticket = ticketFrom((await t.acs(t.response(requestId!), token!)).headers.get("location"))!;
+      expect((await t.redeem(ticket)).status).toBe(200);
+      const second = await t.startSignIn();
+      const disable = await dispatch(t.runtime, {
+        method: "POST",
+        path: `/v1/sso/connections/${t.connection.publicId}/disable`,
+        headers: ownerHeaders(t.world),
+        body: {},
+      });
+      expect(disable.status).toBe(200);
+      expect(await t.runtime.db.select().from(schema.schoolSessions).then((r) => r.filter((s) => s.authenticationMethod === "sso").length)).toBe(0);
+      const late = await t.acs(t.response(second.requestId!), second.token!);
+      expect(late.status).toBe(404);
+      expect(await count(t.runtime, schema.schoolAuthTickets)).toBe(1);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("changing the certificate mid-flight refuses the response", async () => {
+    const t = await ssoSetup();
+    try {
+      const { token, requestId } = await t.startSignIn();
+      await t.runtime.db.update(schema.schoolSsoConnections).set({ subjectAttribute: "objectidentifier" }).where(eq(schema.schoolSsoConnections.id, t.connection.id));
+      const response = await t.acs(t.response(requestId!), token!);
+      expect(ticketFrom(response.headers.get("location"))).toBeNull();
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("a test sign-in issues no ticket, account or identity and stores its result for its starter only", async () => {
+    const t = await ssoSetup({ status: "draft", tested: false });
+    try {
+      const accounts = await count(t.runtime, schema.schoolAccounts);
+      const start = await dispatch(t.runtime, {
+        method: "POST",
+        path: `/v1/sso/connections/${t.connection.publicId}/test`,
+        headers: ownerHeaders(t.world),
+        body: { returnUrl: `${t.runtime.auth.webOrigin}/settings/sso/${t.connection.publicId}` },
+      });
+      expect(start.status).toBe(200);
+      const url = new URL((start.body as { url: string }).url);
+      const redirect = await fetch(`${t.appBase}${url.pathname}${url.search}`, { redirect: "manual" });
+      expect(redirect.status).toBe(302);
+      const [request] = await t.runtime.db.select().from(schema.schoolSsoRequests);
+      const acs = await t.acs(t.response(request!.protocolRequestId!, { attributes: { email: ["alice@acme.com"], displayName: ["Alice"], secretish: ["x"] } }), url.searchParams.get("request")!);
+      expect(acs.status).toBe(302);
+      const back = new URL(acs.headers.get("location")!);
+      expect(back.origin).toBe(new URL(t.runtime.auth.webOrigin).origin);
+      expect(back.searchParams.get("ssoTest")).toBe(request!.id);
+      // Only the request id is in the URL: no attributes, subject or email.
+      expect(acs.headers.get("location")).not.toContain("alice");
+      expect(acs.headers.get("location")).not.toContain("secretish");
+      expect(await count(t.runtime, schema.schoolAuthTickets)).toBe(0);
+      expect(await count(t.runtime, schema.schoolSessions)).toBe(0);
+      expect(await count(t.runtime, schema.schoolSsoIdentities)).toBe(0);
+      expect(await count(t.runtime, schema.schoolAccounts)).toBe(accounts);
+      const [connection] = await t.runtime.db.select().from(schema.schoolSsoConnections);
+      expect(connection!.testedAt).not.toBeNull();
+      expect(connection!.testedConfigDigest).toBeTruthy();
+
+      const result = await dispatch(t.runtime, {
+        method: "GET",
+        path: `/v1/sso/connections/${t.connection.publicId}/test-results/${request!.id}`,
+        headers: ownerHeaders(t.world),
+      });
+      expect(result.status).toBe(200);
+      expect(result.body).toMatchObject({
+        ok: true,
+        email: "alice@acme.com",
+        subject: "subject-1",
+        emailDomainVerified: true,
+        attributes: { secretish: ["x"] },
+      });
+      // Another admin, a member, an API key and a wrong id all get nothing.
+      for (const headers of [
+        { cookie: t.world.member.sessionCookie, "x-school-id": t.world.schoolA.publicId },
+        { "x-api-key": t.world.apiKeyA.raw, "x-school-id": t.world.schoolA.publicId },
+      ]) {
+        const denied = await dispatch(t.runtime, {
+          method: "GET",
+          path: `/v1/sso/connections/${t.connection.publicId}/test-results/${request!.id}`,
+          headers,
+        });
+        expect([401, 403]).toContain(denied.status);
+      }
+      // The same request can't be used for a sign-in.
+      expect(
+        (await t.acs(t.response(request!.protocolRequestId!), url.searchParams.get("request")!)).headers.get("location"),
+      ).not.toContain("ticket");
+      // The result expires after 15 minutes.
+      await t.runtime.db.update(schema.schoolSsoRequests).set({ testResultExpiresAt: new Date(t.clock.now().getTime() - 1000) });
+      expect(
+        (await dispatch(t.runtime, {
+          method: "GET",
+          path: `/v1/sso/connections/${t.connection.publicId}/test-results/${request!.id}`,
+          headers: ownerHeaders(t.world),
+        })).status,
+      ).toBe(404);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("a failed test shows its reason to the starter", async () => {
+    const t = await ssoSetup({ status: "draft", tested: false });
+    try {
+      const start = await dispatch(t.runtime, {
+        method: "POST",
+        path: `/v1/sso/connections/${t.connection.publicId}/test`,
+        headers: ownerHeaders(t.world),
+        body: { returnUrl: `${t.runtime.auth.webOrigin}/settings/sso` },
+      });
+      const url = new URL((start.body as { url: string }).url);
+      await fetch(`${t.appBase}${url.pathname}${url.search}`, { redirect: "manual" });
+      const [request] = await t.runtime.db.select().from(schema.schoolSsoRequests);
+      const acs = await t.acs(t.response(request!.protocolRequestId!, { audience: "https://other/entity" }), url.searchParams.get("request")!);
+      expect(new URL(acs.headers.get("location")!).searchParams.get("ssoTest")).toBe(request!.id);
+      const result = await dispatch(t.runtime, {
+        method: "GET",
+        path: `/v1/sso/connections/${t.connection.publicId}/test-results/${request!.id}`,
+        headers: ownerHeaders(t.world),
+      });
+      expect(result.body).toMatchObject({ ok: false, reason: "wrong_audience" });
+      const [connection] = await t.runtime.db.select().from(schema.schoolSsoConnections);
+      expect(connection!.testedAt).toBeNull();
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("limits SSO starts per IP and school, and ACS posts per IP", async () => {
+    const t = await ssoSetup();
+    try {
+      let last = 200;
+      for (let i = 0; i < 31 && last === 200; i += 1) {
+        last = (await t.startSignIn()).started.status;
+      }
+      expect(last).toBe(429);
+      // A different client address has its own allowance.
+      const other = await dispatch(t.runtime, {
+        method: "POST",
+        path: "/v1/learner/auth/sso",
+        headers: { "x-school-id": t.world.schoolA.publicId, "x-courselit-client-ip": "203.0.113.9" },
+        body: { host: "school-a.localhost:3001", nonce: NONCE },
+      });
+      expect(other.status).toBe(200);
+
+      await t.runtime.db.delete(schema.rateLimitEvents);
+      const statuses: number[] = [];
+      for (let i = 0; i < 62; i += 1) statuses.push((await t.acs("x", "y")).status);
+      expect(statuses.slice(0, 60).every((status) => status === 404)).toBe(true);
+      expect(statuses[61]).toBe(429);
+    } finally {
+      await t.close();
+    }
+  });
+});
diff --git a/apps/api/src/learner-sso-routes.ts b/apps/api/src/learner-sso-routes.ts
new file mode 100644
index 000000000..13ba9196f
--- /dev/null
+++ b/apps/api/src/learner-sso-routes.ts
@@ -0,0 +1,123 @@
+import express, { type Express, type RequestHandler, type Response } from "express";
+import { CLIENT_IP_HEADER } from "./auth/api-key-throttle.js";
+import type { DispatchDeps } from "./deps.js";
+import {
+  beginSsoRedirect,
+  completeSsoResponse,
+  findSsoConnectionByPublicId,
+  ssoServiceProviderMetadata,
+} from "./learner-sso-sign-in.js";
+import { assertRateLimit } from "./rate-limit.js";
+import { escapeHtml } from "./system-mail.js";
+
+const ACS_BODY_LIMIT = "256kb";
+const ACS_WINDOW_MS = 10 * 60 * 1000;
+const ACS_LIMIT = 60;
+
+function sendExpired(res: Response) {
+  res
+    .status(404)
+    .setHeader("Cache-Control", "no-store")
+    .type("html")
+    .send(
+      `<!doctype html><html><body style="font-family: sans-serif; padding: 24px;"><p>${escapeHtml(
+        "This sign-in link has expired. Go back to the school's website and try again.",
+      )}</p></body></html>`,
+    );
+}
+
+/**
+ * Single sign-on for school websites runs on the API host. The IdP posts the
+ * response to `/learner-login/sso/:conn/acs` cross-site, so no cookie is
+ * involved: the request token in RelayState finds the sign-in, and the nonce
+ * cookie on the school's host (checked when the ticket is redeemed) ties it
+ * to the browser that started it.
+ */
+export function registerLearnerSsoRoutes(app: Express, deps: DispatchDeps) {
+  const publicApiUrl = deps.auth.publicApiUrl;
+  const billing = deps.billing.billing;
+
+  app.get("/learner-login/sso/:conn/start", async (req, res, next) => {
+    try {
+      const token = typeof req.query.request === "string" ? req.query.request : "";
+      const outcome = await beginSsoRedirect(
+        deps.db,
+        { connectionPublicId: req.params.conn, requestToken: token, publicApiUrl },
+        deps.clock,
+      );
+      if (outcome.kind === "unavailable") return sendExpired(res);
+      res.setHeader("Cache-Control", "no-store");
+      res.redirect(302, outcome.url);
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  app.get("/learner-login/sso/:conn/metadata", async (req, res, next) => {
+    try {
+      const xml = await ssoServiceProviderMetadata(deps.db, req.params.conn, publicApiUrl);
+      if (!xml) return sendExpired(res);
+      res.setHeader("Cache-Control", "no-store");
+      res.type("application/samlmetadata+xml").send(xml);
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  // Mounted for this route only, and registered before any global body
+  // parser, so a larger global limit can never apply to it first.
+  const parseAcsBody: RequestHandler = (req, res, next) => {
+    express.urlencoded({ extended: false, limit: ACS_BODY_LIMIT, parameterLimit: 10 })(
+      req,
+      res,
+      (error?: unknown) => {
+        if (error) {
+          res.status(413).type("text").send("The request is too large.");
+          return;
+        }
+        next();
+      },
+    );
+  };
+  app.post("/learner-login/sso/:conn/acs", parseAcsBody, async (req, res, next) => {
+    try {
+      const connection = await findSsoConnectionByPublicId(deps.db, req.params.conn);
+      if (!connection) return sendExpired(res);
+      const limited = await assertRateLimit(
+        deps.db,
+        {
+          schoolId: connection.schoolId,
+          userId: String(req.headers[CLIENT_IP_HEADER] ?? "unknown"),
+          scope: "learner_sso",
+          action: "acs",
+          subjectId: "acs",
+          windowMs: ACS_WINDOW_MS,
+          limit: ACS_LIMIT,
+        },
+        deps.clock,
+      );
+      if (!limited.ok) {
+        res.setHeader("Retry-After", "60");
+        res.status(429).type("text").send("Too many sign-in attempts. Try again shortly.");
+        return;
+      }
+      const body = (req.body ?? {}) as Record<string, unknown>;
+      const outcome = await completeSsoResponse(
+        deps.db,
+        {
+          connectionPublicId: req.params.conn,
+          samlResponse: body.SAMLResponse,
+          relayState: body.RelayState,
+          publicApiUrl,
+          billing,
+        },
+        deps.clock,
+      );
+      if (outcome.kind === "unavailable") return sendExpired(res);
+      res.setHeader("Cache-Control", "no-store");
+      res.redirect(302, outcome.url);
+    } catch (error) {
+      next(error);
+    }
+  });
+}
diff --git a/apps/api/src/learner-sso-sign-in.ts b/apps/api/src/learner-sso-sign-in.ts
new file mode 100644
index 000000000..42e2bed75
--- /dev/null
+++ b/apps/api/src/learner-sso-sign-in.ts
@@ -0,0 +1,466 @@
+import { randomBytes } from "node:crypto";
+import type { BillingEngine } from "@codelitdev/billing/workflows";
+import { type Clock, createPlatformError, type PlatformError, uuidv7 } from "@codelitdev/platform";
+import { and, eq, gt, isNull, lt, sql } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { digestToken } from "./learners.js";
+import { createSchoolAuthTicket, originForHost, safeNextPath } from "./learner-sign-in.js";
+import { linkSsoIdentity } from "./learner-sso.js";
+import { schoolHasFeature } from "./plan-features.js";
+import { assertRateLimit } from "./rate-limit.js";
+import { resolveSchoolByHost } from "./schools.js";
+import { activeSsoConnection, isVerifiedSsoDomainEmail } from "./sign-in-policy.js";
+import {
+  connectionConfigDigest,
+  samlConfigFor,
+  SSO_FEATURE,
+  type SsoConnectionRow,
+} from "./sso-config.js";
+import { recordSsoEvent } from "./sso-events.js";
+import {
+  type AssertionReplayStore,
+  createSamlServiceProvider,
+  type SamlFailureReason,
+  type SsoRequestStore,
+} from "./sso-protocol/index.js";
+import type { AppDb } from "./types.js";
+
+const SSO_REQUEST_TTL_MS = 10 * 60 * 1000;
+const TEST_RESULT_TTL_MS = 15 * 60 * 1000;
+const MIN_NONCE_LENGTH = 32;
+const START_WINDOW_MS = 10 * 60 * 1000;
+const START_LIMIT = 30;
+
+type Billing = Pick<BillingEngine, "hasFeature">;
+type Result<T> = { ok: true; value: T } | { ok: false; error: PlatformError };
+
+export async function findSsoConnectionByPublicId(db: AppDb, publicId: string) {
+  const [connection] = await db
+    .select()
+    .from(schema.schoolSsoConnections)
+    .where(eq(schema.schoolSsoConnections.publicId, publicId))
+    .limit(1);
+  return connection ?? null;
+}
+
+/**
+ * Begin single sign-on for a school website. The storefront calls this
+ * server-to-server like Google: the host the learner is on, a random nonce it
+ * has also put in a cookie there, and where to go afterwards. Nothing here
+ * proves anything about the learner; the request row only holds digests.
+ */
+export async function startLearnerSsoSignIn(
+  db: AppDb,
+  input: {
+    schoolPublicId: string;
+    host: string;
+    nonce: string;
+    next?: string | null;
+    publicApiUrl: string;
+    billing: Billing;
+    /** The client address the API resolved, for rate limiting. */
+    clientIp?: string | null;
+  },
+  clock: Clock,
+): Promise<Result<{ url: string }>> {
+  if (input.nonce.length < MIN_NONCE_LENGTH) {
+    return { ok: false, error: createPlatformError("validation_failed") };
+  }
+  const origin = originForHost(input.host);
+  const school = origin ? await resolveSchoolByHost(db, input.host) : null;
+  if (!origin || !school || school.publicId !== input.schoolPublicId) {
+    return { ok: false, error: createPlatformError("tenant_forbidden") };
+  }
+  const limited = await assertRateLimit(
+    db,
+    {
+      schoolId: school.id,
+      userId: input.clientIp || "unknown",
+      scope: "learner_sso",
+      action: "start",
+      subjectId: school.id,
+      windowMs: START_WINDOW_MS,
+      limit: START_LIMIT,
+    },
+    clock,
+  );
+  if (!limited.ok) return limited;
+  const connection = await activeSsoConnection(db, school.id);
+  if (
+    connection?.protocol !== "saml" ||
+    !(await schoolHasFeature(input.billing, school.id, SSO_FEATURE))
+  ) {
+    return {
+      ok: false,
+      error: createPlatformError("forbidden", {
+        safeDetails: { reason: "sso_not_available" },
+      }),
+    };
+  }
+  const token = randomBytes(32).toString("base64url");
+  const now = clock.now();
+  await db.insert(schema.schoolSsoRequests).values({
+    id: uuidv7(clock),
+    requestDigest: digestToken(token),
+    schoolId: school.id,
+    connectionId: connection.id,
+    nonceDigest: digestToken(input.nonce),
+    returnOrigin: origin,
+    nextPath: safeNextPath(input.next),
+    purpose: "sign_in",
+    expiresAt: new Date(now.getTime() + SSO_REQUEST_TTL_MS),
+    createdAt: now,
+  });
+  const url = new URL(
+    `/learner-login/sso/${encodeURIComponent(connection.publicId)}/start`,
+    input.publicApiUrl,
+  );
+  url.searchParams.set("request", token);
+  return { ok: true, value: { url: url.toString() } };
+}
+
+/** A connection the public routes will serve: draft or active. Anything else looks unknown. */
+function routableConnection(connection: SsoConnectionRow | null): SsoConnectionRow | null {
+  return connection &&
+    connection.protocol === "saml" &&
+    (connection.status === "draft" || connection.status === "active")
+    ? connection
+    : null;
+}
+
+/** SP metadata for the IdP admin, or null for a missing, disabled or suspended connection. */
+export async function ssoServiceProviderMetadata(
+  db: AppDb,
+  connectionPublicId: string,
+  publicApiUrl: string,
+): Promise<string | null> {
+  const connection = routableConnection(
+    await findSsoConnectionByPublicId(db, connectionPublicId),
+  );
+  if (!connection) return null;
+  return createSamlServiceProvider(samlConfigFor(connection, publicApiUrl)).serviceProviderMetadata();
+}
+
+export type SsoRouteOutcome = { kind: "unavailable" } | { kind: "redirect"; url: string };
+
+/**
+ * `GET /learner-login/sso/:conn/start?request=…`: find the open request, build
+ * the AuthnRequest with RelayState = the request token, keep its ID on the
+ * row, and return the IdP URL to send the browser to.
+ */
+export async function beginSsoRedirect(
+  db: AppDb,
+  input: { connectionPublicId: string; requestToken: string; publicApiUrl: string },
+  clock: Clock,
+): Promise<SsoRouteOutcome> {
+  const connection = routableConnection(
+    await findSsoConnectionByPublicId(db, input.connectionPublicId),
+  );
+  if (!connection || !input.requestToken) return { kind: "unavailable" };
+  const [request] = await db
+    .select()
+    .from(schema.schoolSsoRequests)
+    .where(
+      and(
+        eq(schema.schoolSsoRequests.requestDigest, digestToken(input.requestToken)),
+        eq(schema.schoolSsoRequests.connectionId, connection.id),
+        isNull(schema.schoolSsoRequests.consumedAt),
+        gt(schema.schoolSsoRequests.expiresAt, clock.now()),
+      ),
+    )
+    .limit(1);
+  if (!request) return { kind: "unavailable" };
+  // A sign-in needs an active connection; only a test may use a draft one.
+  if (request.purpose === "sign_in" && connection.status !== "active") {
+    return { kind: "unavailable" };
+  }
+  let built: { url: string; requestId: string };
+  try {
+    built = await createSamlServiceProvider(
+      samlConfigFor(connection, input.publicApiUrl),
+    ).buildAuthnRequestUrl({ relayState: input.requestToken });
+  } catch {
+    return { kind: "unavailable" };
+  }
+  const saved = await db
+    .update(schema.schoolSsoRequests)
+    .set({ protocolRequestId: built.requestId })
+    .where(
+      and(
+        eq(schema.schoolSsoRequests.id, request.id),
+        isNull(schema.schoolSsoRequests.consumedAt),
+        isNull(schema.schoolSsoRequests.protocolRequestId),
+      ),
+    )
+    .returning({ id: schema.schoolSsoRequests.id });
+  // One AuthnRequest per request: opening the link a second time can't
+  // replace the ID the first one is waiting on.
+  if (!saved[0]) return { kind: "unavailable" };
+  return { kind: "redirect", url: built.url };
+}
+
+function requestStore(
+  db: AppDb,
+  connectionId: string,
+  clock: Clock,
+  captured: { request: typeof schema.schoolSsoRequests.$inferSelect | null },
+): SsoRequestStore {
+  return {
+    async findOpen(relayState) {
+      const [row] = await db
+        .select({ protocolRequestId: schema.schoolSsoRequests.protocolRequestId })
+        .from(schema.schoolSsoRequests)
+        .where(
+          and(
+            eq(schema.schoolSsoRequests.requestDigest, digestToken(relayState)),
+            eq(schema.schoolSsoRequests.connectionId, connectionId),
+            isNull(schema.schoolSsoRequests.consumedAt),
+            gt(schema.schoolSsoRequests.expiresAt, clock.now()),
+          ),
+        )
+        .limit(1);
+      return row?.protocolRequestId ? { requestId: row.protocolRequestId } : null;
+    },
+    async consume(relayState, inResponseTo) {
+      const [row] = await db
+        .update(schema.schoolSsoRequests)
+        .set({ consumedAt: clock.now() })
+        .where(
+          and(
+            eq(schema.schoolSsoRequests.requestDigest, digestToken(relayState)),
+            eq(schema.schoolSsoRequests.connectionId, connectionId),
+            eq(schema.schoolSsoRequests.protocolRequestId, inResponseTo),
+            isNull(schema.schoolSsoRequests.consumedAt),
+            gt(schema.schoolSsoRequests.expiresAt, clock.now()),
+          ),
+        )
+        .returning();
+      if (row) captured.request = row;
+      return Boolean(row);
+    },
+  };
+}
+
+function replayStore(db: AppDb, connectionId: string): AssertionReplayStore {
+  return {
+    async remember(assertionId, expiresAt) {
+      const inserted = await db
+        .insert(schema.schoolSsoAssertionIds)
+        .values({ connectionId, assertionId, expiresAt })
+        .onConflictDoNothing()
+        .returning({ id: schema.schoolSsoAssertionIds.assertionId });
+      return inserted.length > 0;
+    },
+  };
+}
+
+function failureUrl(
+  request: Pick<typeof schema.schoolSsoRequests.$inferSelect, "id" | "purpose" | "returnOrigin" | "nextPath">,
+): string {
+  if (request.purpose === "test") {
+    const url = new URL(request.nextPath, request.returnOrigin);
+    url.searchParams.set("ssoTest", request.id);
+    return url.toString();
+  }
+  const url = new URL("/login", request.returnOrigin);
+  url.searchParams.set("error", "sso");
+  if (request.nextPath !== "/dashboard") url.searchParams.set("next", request.nextPath);
+  return url.toString();
+}
+
+/** The earliest of the IdP's session end and the connection's own limit. */
+export function ssoSessionExpiry(
+  connection: Pick<SsoConnectionRow, "maxSessionMinutes">,
+  sessionNotOnOrAfter: Date | null,
+  now: Date,
+): Date | null {
+  const limits: number[] = [];
+  if (connection.maxSessionMinutes) {
+    limits.push(now.getTime() + connection.maxSessionMinutes * 60_000);
+  }
+  if (sessionNotOnOrAfter) limits.push(sessionNotOnOrAfter.getTime());
+  return limits.length > 0 ? new Date(Math.min(...limits)) : null;
+}
+
+/**
+ * `POST /learner-login/sso/:conn/acs`. The module checks everything about the
+ * response, in order, through the stores below: open request found (not used
+ * up), connection still usable, signature, status, then the request is used
+ * up with one conditional update and the assertion ID remembered. Only then
+ * does anything happen here: a sign-in links the identity and hands out a
+ * ticket; a test only stores what the IdP sent.
+ */
+export async function completeSsoResponse(
+  db: AppDb,
+  input: {
+    connectionPublicId: string;
+    samlResponse: unknown;
+    relayState: unknown;
+    publicApiUrl: string;
+    billing: Billing;
+  },
+  clock: Clock,
+): Promise<SsoRouteOutcome> {
+  const loaded = await findSsoConnectionByPublicId(db, input.connectionPublicId);
+  // Unknown, disabled and suspended connections all answer the same way.
+  const connection = routableConnection(loaded);
+  if (!connection || typeof input.relayState !== "string" || !input.relayState) {
+    return { kind: "unavailable" };
+  }
+  const [known] = await db
+    .select()
+    .from(schema.schoolSsoRequests)
+    .where(
+      and(
+        eq(schema.schoolSsoRequests.requestDigest, digestToken(input.relayState)),
+        eq(schema.schoolSsoRequests.connectionId, connection.id),
+      ),
+    )
+    .limit(1);
+  if (!known) return { kind: "unavailable" };
+
+  const loadedDigest = connectionConfigDigest(connection);
+  const captured: { request: typeof schema.schoolSsoRequests.$inferSelect | null } = {
+    request: null,
+  };
+  const failed = async (reason: string): Promise<SsoRouteOutcome> => {
+    await recordSsoEvent(
+      db,
+      {
+        schoolId: connection.schoolId,
+        connectionId: connection.id,
+        action: known.purpose === "test" ? "test.failed" : "sign_in.failed",
+        reason,
+      },
+      clock,
+    );
+    if (known.purpose === "test") {
+      await storeTestResult(db, known, { ok: false, reason }, clock);
+    }
+    return { kind: "redirect", url: failureUrl(known) };
+  };
+
+  const validation = await createSamlServiceProvider(
+    samlConfigFor(connection, input.publicApiUrl),
+  ).validatePostResponse({
+    samlResponse: typeof input.samlResponse === "string" ? input.samlResponse : "",
+    relayState: input.relayState,
+    requests: requestStore(db, connection.id, clock, captured),
+    replay: replayStore(db, connection.id),
+    checkConnection: async () => {
+      // The connection may have changed since the request started.
+      const current = await findSsoConnectionByPublicId(db, input.connectionPublicId);
+      if (!current || connectionConfigDigest(current) !== loadedDigest) return false;
+      if (known.purpose === "sign_in") {
+        return (
+          current.status === "active" &&
+          (await schoolHasFeature(input.billing, current.schoolId, SSO_FEATURE))
+        );
+      }
+      return current.status === "draft" || current.status === "active";
+    },
+  });
+  if (!validation.ok) return failed(validation.reason satisfies SamlFailureReason);
+  const request = captured.request;
+  if (!request) return failed("request_not_found");
+  const assertion = validation.assertion;
+
+  if (request.purpose === "test") {
+    const parsedDomain = assertion.email
+      ? await isVerifiedSsoDomainEmail(db, connection.id, assertion.email)
+      : false;
+    await storeTestResult(
+      db,
+      request,
+      {
+        ok: true,
+        issuer: assertion.issuer,
+        subject: assertion.subject,
+        email: assertion.email,
+        name: assertion.name,
+        emailDomainVerified: parsedDomain,
+        attributes: assertion.attributes,
+      },
+      clock,
+    );
+    // The digest of the settings this test ran against: activation needs it
+    // to still match.
+    await db
+      .update(schema.schoolSsoConnections)
+      .set({ testedAt: clock.now(), testedConfigDigest: loadedDigest })
+      .where(eq(schema.schoolSsoConnections.id, connection.id));
+    await recordSsoEvent(
+      db,
+      { schoolId: connection.schoolId, connectionId: connection.id, action: "test.succeeded" },
+      clock,
+    );
+    // The browser carries only the request id, never the attributes.
+    return { kind: "redirect", url: failureUrl(request) };
+  }
+
+  if (!assertion.email) return failed("sso_invalid_email");
+  const linked = await linkSsoIdentity(
+    db,
+    {
+      connection,
+      issuer: assertion.issuer,
+      subject: assertion.subject,
+      email: assertion.email,
+      name: assertion.name,
+    },
+    clock,
+  );
+  if (!linked.ok) return failed(linked.reason);
+  const ticket = await createSchoolAuthTicket(db, {
+    schoolId: connection.schoolId,
+    schoolAccountId: linked.value.id,
+    userId: linked.value.userId,
+    authenticationMethod: "sso",
+    ssoConnectionId: connection.id,
+    sessionExpiresAt: ssoSessionExpiry(connection, assertion.sessionNotOnOrAfter, clock.now()),
+    nonceDigest: request.nonceDigest,
+    clock,
+  });
+  const url = new URL("/auth/complete", request.returnOrigin);
+  url.searchParams.set("next", request.nextPath);
+  url.hash = new URLSearchParams({ ticket }).toString();
+  return { kind: "redirect", url: url.toString() };
+}
+
+async function storeTestResult(
+  db: AppDb,
+  request: Pick<typeof schema.schoolSsoRequests.$inferSelect, "id">,
+  result: Record<string, unknown>,
+  clock: Clock,
+): Promise<void> {
+  const now = clock.now();
+  await db
+    .update(schema.schoolSsoRequests)
+    .set({
+      testResult: result,
+      testResultExpiresAt: new Date(now.getTime() + TEST_RESULT_TTL_MS),
+    })
+    .where(eq(schema.schoolSsoRequests.id, request.id));
+}
+
+/** Delete expired requests, test results and replay-cache rows. */
+export async function cleanupSsoRequests(
+  db: AppDb,
+  clock: Clock,
+): Promise<{ requests: number; assertionIds: number }> {
+  const now = clock.now();
+  const requests = await db
+    .delete(schema.schoolSsoRequests)
+    .where(
+      and(
+        lt(schema.schoolSsoRequests.expiresAt, now),
+        sql`(${schema.schoolSsoRequests.testResultExpiresAt} is null or ${schema.schoolSsoRequests.testResultExpiresAt} < ${now.toISOString()}::timestamptz)`,
+      ),
+    )
+    .returning({ id: schema.schoolSsoRequests.id });
+  const ids = await db
+    .delete(schema.schoolSsoAssertionIds)
+    .where(lt(schema.schoolSsoAssertionIds.expiresAt, now))
+    .returning({ id: schema.schoolSsoAssertionIds.assertionId });
+  return { requests: requests.length, assertionIds: ids.length };
+}
diff --git a/apps/api/src/learner-sso.test.ts b/apps/api/src/learner-sso.test.ts
new file mode 100644
index 000000000..fc2891061
--- /dev/null
+++ b/apps/api/src/learner-sso.test.ts
@@ -0,0 +1,695 @@
+import { describe, expect, it } from "bun:test";
+import { createPublicId, uuidv7 } from "@codelitdev/platform";
+import { and, eq, like, sql } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { dispatch } from "./dispatch.js";
+import { learnerCookie, seedRealLearner, seedSsoConnection } from "./test-sso.js";
+import { linkSsoIdentity } from "./learner-sso.js";
+import {
+  authenticateLearner,
+  findOrCreateVerifiedUser,
+  issueSchoolSession,
+  signInLearnerWithIdentity,
+} from "./learners.js";
+import { createPgliteRuntime, freezeRuntimeClock } from "./runtime.js";
+import { seedWorld } from "./seed.js";
+import { staffSpaceIds } from "./space-access.js";
+import { createShadowUser, isShadowUser } from "./shadow-users.js";
+import { parseSsoEmail } from "./sso-email.js";
+
+const clockAt = () => freezeRuntimeClock(new Date("2026-03-01T00:00:00.000Z"));
+
+async function setup() {
+  const clock = clockAt();
+  const runtime = await createPgliteRuntime({ clock });
+  const world = await seedWorld(runtime, clock);
+  const connection = await seedSsoConnection(runtime.db, clock, {
+    schoolId: world.schoolA.id,
+    domains: ["acme.com", "xn--bcher-kva.example"],
+    unverifiedDomains: ["pending.com"],
+  });
+  const link = (
+    over: Partial<{ subject: string; email: string; name: string | null; issuer: string }>,
+  ) =>
+    linkSsoIdentity(
+      runtime.db,
+      {
+        connection,
+        issuer: over.issuer ?? connection.idpEntityId!,
+        subject: over.subject ?? "subject-1",
+        email: over.email ?? "alice@acme.com",
+        name: over.name === undefined ? "Alice" : over.name,
+      },
+      clock,
+    );
+  const count = async (table: Parameters<typeof runtime.db.select>[0] extends never ? never : any) =>
+    (await runtime.db.select({ n: sql<number>`count(*)::int` }).from(table))[0]!.n;
+  return { clock, runtime, world, connection, link, count };
+}
+
+describe.serial("linkSsoIdentity", () => {
+  it("creates a shadow user, account and identity in a verified domain, once", async () => {
+    const { runtime, world, link, count } = await setup();
+    const users = await count(schema.user);
+    const first = await link({});
+    expect(first.ok).toBe(true);
+    if (!first.ok) throw new Error();
+    expect(first.created).toBe(true);
+    expect(first.value.email).toBe("alice@acme.com");
+    expect(await count(schema.user)).toBe(users + 1);
+    const [user] = await runtime.db
+      .select()
+      .from(schema.user)
+      .where(eq(schema.user.id, first.value.userId));
+    expect(user!.email).toMatch(/^sso-.+@users\.invalid$/);
+    expect(user!.emailVerified).toBe(false);
+    expect(await isShadowUser(runtime.db, user!.id)).toBe(true);
+    const credentials = await runtime.db
+      .select()
+      .from(schema.account)
+      .where(eq(schema.account.userId, user!.id));
+    expect(credentials).toHaveLength(0);
+
+    const second = await link({});
+    expect(second.ok && !second.created && second.value.id === first.value.id).toBe(true);
+    expect(await count(schema.user)).toBe(users + 1);
+    expect(await count(schema.schoolSsoIdentities)).toBe(1);
+    // Marketing email stays off for an SSO-created account.
+    const jobs = await runtime.db.select().from(schema.integrationOutboxJobs);
+    const sync = jobs.find(
+      (job) =>
+        job.type === "sync_sendlit_contact" &&
+        (job.payload as Record<string, unknown>).schoolAccountId === first.value.id,
+    );
+    expect(sync).toBeDefined();
+    expect((sync!.payload as Record<string, unknown>).subscribed).toBe(false);
+    expect(world.schoolA.id).toBe(first.value.schoolId);
+    await runtime.close();
+  });
+
+  it("records a learner_signed_in activity with method sso", async () => {
+    const { runtime, link } = await setup();
+    const linked = await link({});
+    if (!linked.ok) throw new Error();
+    const rows = await runtime.db
+      .select()
+      .from(schema.activities)
+      .where(eq(schema.activities.type, "learner_signed_in"));
+    expect(rows).toHaveLength(1);
+    expect((rows[0]!.metadata as { method: string }).method).toBe("sso");
+    await runtime.close();
+  });
+
+  it("rejects an unverified domain and creates nothing", async () => {
+    const { runtime, link, count } = await setup();
+    const users = await count(schema.user);
+    const accounts = await count(schema.schoolAccounts);
+    for (const email of ["bob@pending.com", "bob@other.org", "bob@sub.acme.com", "bob@acme.com.evil.org"]) {
+      const result = await link({ email });
+      expect(result).toEqual({ ok: false, reason: "sso_domain_not_verified" });
+    }
+    expect(await count(schema.user)).toBe(users);
+    expect(await count(schema.schoolAccounts)).toBe(accounts);
+    expect(await count(schema.schoolSsoIdentities)).toBe(0);
+    await runtime.close();
+  });
+
+  it("links to an existing learner and never changes the platform user", async () => {
+    const { runtime, clock, world, link, count } = await setup();
+    const real = await seedRealLearner(
+      runtime.db,
+      clock,
+      world.schoolA.publicId,
+      "carol@acme.com",
+      "Carol Real",
+    );
+    const before = (
+      await runtime.db.select().from(schema.user).where(eq(schema.user.id, real.user.id))
+    )[0]!;
+    const users = await count(schema.user);
+    const result = await link({ subject: "carol", email: "carol@acme.com", name: "Carol From IdP" });
+    expect(result.ok && !result.created && result.value.userId === real.user.id).toBe(true);
+    expect(await count(schema.user)).toBe(users);
+    const after = (
+      await runtime.db.select().from(schema.user).where(eq(schema.user.id, real.user.id))
+    )[0]!;
+    expect(after).toEqual(before);
+    if (result.ok) expect(result.value.displayName).toBe("Carol Real");
+
+    // A later email change at the IdP doesn't touch a real user's account.
+    const changed = await link({ subject: "carol", email: "carol.new@acme.com", name: "Other" });
+    expect(changed.ok && changed.value.email === "carol@acme.com").toBe(true);
+    await runtime.close();
+  });
+
+  it("never touches an unverified platform user with the same address", async () => {
+    const { runtime, clock, link } = await setup();
+    const now = clock.now();
+    await runtime.db.insert(schema.user).values({
+      id: uuidv7(clock),
+      name: "Squatter",
+      email: "dave@acme.com",
+      emailVerified: false,
+      createdAt: now,
+      updatedAt: now,
+    });
+    const result = await link({ subject: "dave", email: "dave@acme.com" });
+    expect(result.ok).toBe(true);
+    const [squatter] = await runtime.db
+      .select()
+      .from(schema.user)
+      .where(eq(schema.user.email, "dave@acme.com"));
+    expect(squatter!.emailVerified).toBe(false);
+    expect(squatter!.name).toBe("Squatter");
+    await runtime.close();
+  });
+
+  it("a found identity wins over email, and follows email changes only for shadow-backed accounts in verified domains", async () => {
+    const { runtime, clock, world, link } = await setup();
+    const first = await link({ subject: "erin", email: "erin@acme.com", name: "Erin" });
+    if (!first.ok) throw new Error();
+    // Another account already has the new address: identity still wins, email stays.
+    await seedRealLearner(runtime.db, clock, world.schoolA.publicId, "taken@acme.com");
+    const blocked = await link({ subject: "erin", email: "taken@acme.com" });
+    expect(blocked.ok && blocked.value.id === first.value.id && blocked.value.email === "erin@acme.com").toBe(true);
+    // Outside a verified domain: no change.
+    const outside = await link({ subject: "erin", email: "erin@other.org" });
+    expect(outside.ok && outside.value.email === "erin@acme.com").toBe(true);
+    // Verified domain, free address: followed.
+    const moved = await link({ subject: "erin", email: "erin.renamed@acme.com", name: "Erin R" });
+    expect(moved.ok && moved.value.id === first.value.id).toBe(true);
+    if (moved.ok) {
+      expect(moved.value.email).toBe("erin.renamed@acme.com");
+      expect(moved.value.displayName).toBe("Erin R");
+    }
+    const [identity] = await runtime.db.select().from(schema.schoolSsoIdentities);
+    expect(identity!.lastEmail).toBe("erin.renamed@acme.com");
+    await runtime.close();
+  });
+
+  it("never matches an identity from another issuer", async () => {
+    const { runtime, connection, link, count } = await setup();
+    const first = await link({ subject: "frank", email: "frank@acme.com" });
+    expect(first.ok).toBe(true);
+    // The assertion names a different issuer than the connection's.
+    expect(await link({ subject: "frank", issuer: "https://evil.example/entity" })).toEqual({
+      ok: false,
+      reason: "sso_issuer_mismatch",
+    });
+    // A stored identity from an older issuer is not matched or re-linked either.
+    await runtime.db
+      .update(schema.schoolSsoIdentities)
+      .set({ issuer: "https://old.example/entity" })
+      .where(eq(schema.schoolSsoIdentities.connectionId, connection.id));
+    const users = await count(schema.user);
+    expect(await link({ subject: "frank", email: "frank@acme.com" })).toEqual({
+      ok: false,
+      reason: "sso_issuer_mismatch",
+    });
+    expect(await count(schema.user)).toBe(users);
+    await runtime.close();
+  });
+
+  it("refuses a team member on every sign-in, including after the first", async () => {
+    const { runtime, clock, world, link } = await setup();
+    // A team member's account with an address in a verified domain.
+    const staff = await seedRealLearner(runtime.db, clock, world.schoolA.publicId, "staff@acme.com");
+    await runtime.db.insert(schema.memberships).values({
+      id: uuidv7(clock),
+      publicId: createPublicId("mbr", clock),
+      schoolId: world.schoolA.id,
+      schoolAccountId: staff.session.schoolAccount.id,
+      isOwner: false,
+      permissions: ["products:write"],
+      createdAt: clock.now(),
+      updatedAt: clock.now(),
+    });
+    expect(await link({ subject: "staff", email: "staff@acme.com" })).toEqual({
+      ok: false,
+      reason: "sso_account_is_team_member",
+    });
+    // Linked first, joined the team afterwards: the next sign-in is refused.
+    const learner = await link({ subject: "grace", email: "grace@acme.com" });
+    if (!learner.ok) throw new Error();
+    await runtime.db.insert(schema.memberships).values({
+      id: uuidv7(clock),
+      publicId: createPublicId("mbr", clock),
+      schoolId: world.schoolA.id,
+      schoolAccountId: learner.value.id,
+      isOwner: false,
+      permissions: [],
+      createdAt: clock.now(),
+      updatedAt: clock.now(),
+    });
+    expect(await link({ subject: "grace", email: "grace@acme.com" })).toEqual({
+      ok: false,
+      reason: "sso_account_is_team_member",
+    });
+    await runtime.close();
+  });
+
+  it("refuses inactive accounts and inactive connections", async () => {
+    const { runtime, connection, link } = await setup();
+    const learner = await link({ subject: "hank", email: "hank@acme.com" });
+    if (!learner.ok) throw new Error();
+    await runtime.db
+      .update(schema.schoolAccounts)
+      .set({ status: "deactivated" })
+      .where(eq(schema.schoolAccounts.id, learner.value.id));
+    expect(await link({ subject: "hank", email: "hank@acme.com" })).toEqual({
+      ok: false,
+      reason: "sso_account_inactive",
+    });
+    await runtime.db
+      .update(schema.schoolSsoConnections)
+      .set({ status: "suspended" })
+      .where(eq(schema.schoolSsoConnections.id, connection.id));
+    expect(await link({ subject: "ivy", email: "ivy@acme.com" })).toEqual({
+      ok: false,
+      reason: "sso_connection_inactive",
+    });
+    await runtime.close();
+  });
+
+  it("parses emails strictly and matches IDN domains by punycode", async () => {
+    const { runtime, link, count } = await setup();
+    const users = await count(schema.user);
+    for (const email of [
+      '"alice"@acme.com',
+      'a"b@acme.com',
+      "alice@acme.com@evil.org",
+      "alice@@acme.com",
+      " alice@acme.com",
+      "alice@acme.com ",
+      "ali ce@acme.com",
+      "alice@acme.com\n",
+      "(c)alice@acme.com",
+      "alice@",
+      "@acme.com",
+      "alice..x@acme.com",
+      ".alice@acme.com",
+      "alice@[127.0.0.1]",
+      "alice@acme",
+      "alice\u0000@acme.com",
+      "alice@https://acme.com",
+      "alice@acme.com/",
+      "alice@acme.com:443",
+      "",
+    ]) {
+      expect(await link({ subject: `s-${email}`, email })).toEqual({
+        ok: false,
+        reason: "sso_invalid_email",
+      });
+    }
+    expect(await count(schema.user)).toBe(users);
+    // The domain is stored as punycode and matched exactly.
+    const idn = await link({ subject: "idn", email: "Jörg@Bücher.example" });
+    expect(parseSsoEmail("Jörg@Bücher.example")).toBeNull(); // non-ASCII local part
+    expect(idn.ok).toBe(false);
+    const ok = await link({ subject: "idn", email: "Joerg@Bücher.example" });
+    expect(ok.ok && ok.value.email).toBe("joerg@xn--bcher-kva.example");
+    // A look-alike domain isn't a verified one.
+    expect(await link({ subject: "cyr", email: "x@аcme.com" })).toEqual({
+      ok: false,
+      reason: "sso_domain_not_verified",
+    });
+    await runtime.close();
+  });
+});
+
+describe.serial("account races", () => {
+  it("never moves a real user's account onto a shadow user when it wins the race", async () => {
+    const { runtime, clock, world, connection } = await setup();
+    const racing = new Proxy(runtime.db, {
+      get(target, prop) {
+        const value = (target as any)[prop];
+        if (prop === "transaction") {
+          return async (...args: unknown[]) => {
+            // The email-code sign-in lands between SSO's lookup and its insert.
+            racing_hook.fire && (await racing_hook.fire());
+            racing_hook.fire = null;
+            return (value as (...a: unknown[]) => unknown).apply(target, args);
+          };
+        }
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+    });
+    const racing_hook: { fire: null | (() => Promise<void>) } = {
+      fire: async () => {
+        await seedRealLearner(runtime.db, clock, world.schoolA.publicId, "race@acme.com", "Racer");
+      },
+    };
+    const result = await linkSsoIdentity(
+      racing,
+      {
+        connection,
+        issuer: connection.idpEntityId!,
+        subject: "race",
+        email: "race@acme.com",
+        name: "Racer",
+      },
+      clock,
+    );
+    expect(result.ok && !result.created).toBe(true);
+    const [real] = await runtime.db
+      .select()
+      .from(schema.user)
+      .where(eq(schema.user.email, "race@acme.com"));
+    expect(real!.emailVerified).toBe(true);
+    const accounts = await runtime.db
+      .select()
+      .from(schema.schoolAccounts)
+      .where(eq(schema.schoolAccounts.email, "race@acme.com"));
+    expect(accounts).toHaveLength(1);
+    expect(accounts[0]!.userId).toBe(real!.id);
+    const shadows = await runtime.db.select().from(schema.ssoShadowUsers);
+    expect(shadows).toHaveLength(0);
+    const users = await runtime.db
+      .select()
+      .from(schema.user)
+      .where(like(schema.user.email, "%@users.invalid"));
+    expect(users).toHaveLength(0);
+    await runtime.close();
+  });
+
+  it("moves a shadow-backed account to the real user on an email sign-in and deletes the shadow user", async () => {
+    const { runtime, clock, world, link } = await setup();
+    const created = await link({ subject: "judy", email: "judy@acme.com", name: "Judy" });
+    if (!created.ok) throw new Error();
+    const shadowId = created.value.userId;
+    // The SSO learner signs in, then proves the address by email code.
+    const real = await seedRealLearner(runtime.db, clock, world.schoolA.publicId, "judy@acme.com");
+    expect(real.session.schoolAccount.id).toBe(created.value.id);
+    expect(real.session.schoolAccount.userId).toBe(real.user.id);
+    expect(await isShadowUser(runtime.db, shadowId)).toBe(false);
+    const gone = await runtime.db.select().from(schema.user).where(eq(schema.user.id, shadowId));
+    expect(gone).toHaveLength(0);
+    const identities = await runtime.db.select().from(schema.schoolSsoIdentities);
+    expect(identities).toHaveLength(1);
+    expect(identities[0]!.schoolAccountId).toBe(created.value.id);
+    await runtime.close();
+  });
+
+  it("deletes a shadow user together with its last school account", async () => {
+    const { runtime, link } = await setup();
+    const created = await link({ subject: "ken", email: "ken@acme.com" });
+    if (!created.ok) throw new Error();
+    const { deleteShadowUserIfOrphaned } = await import("./shadow-users.js");
+    // Still owns an account: kept.
+    expect(await deleteShadowUserIfOrphaned(runtime.db, created.value.userId)).toBe(false);
+    await runtime.db
+      .delete(schema.schoolAccounts)
+      .where(eq(schema.schoolAccounts.id, created.value.id));
+    expect(await deleteShadowUserIfOrphaned(runtime.db, created.value.userId)).toBe(true);
+    expect(await isShadowUser(runtime.db, created.value.userId)).toBe(false);
+    await runtime.close();
+  });
+});
+
+describe.serial("shadow users", () => {
+  it("findOrCreateVerifiedUser never returns or modifies a shadow user", async () => {
+    const { runtime, clock, world } = await setup();
+    const shadow = await createShadowUser(
+      runtime.db,
+      { schoolId: world.schoolA.id, name: "Shadow" },
+      clock,
+    );
+    await expect(findOrCreateVerifiedUser(runtime.db, shadow.email, clock)).rejects.toThrow(
+      "shadow_user_email",
+    );
+    await expect(
+      findOrCreateVerifiedUser(runtime.db, "SSO-anything@Users.Invalid", clock),
+    ).rejects.toThrow("shadow_user_email");
+    const [after] = await runtime.db.select().from(schema.user).where(eq(schema.user.id, shadow.id));
+    expect(after!.emailVerified).toBe(false);
+    const real = await findOrCreateVerifiedUser(runtime.db, "someone@example.com", clock);
+    expect(real.id).not.toBe(shadow.id);
+    await runtime.close();
+  });
+
+  it("Better Auth refuses to create a session for a shadow user", async () => {
+    const { runtime, clock, world } = await setup();
+    const shadow = await createShadowUser(
+      runtime.db,
+      { schoolId: world.schoolA.id, name: "Shadow" },
+      clock,
+    );
+    const ctx = await runtime.auth.auth.$context;
+    // Control: a normal user still gets a session.
+    const normal = await ctx.internalAdapter.createSession(world.member.id);
+    expect(normal).toBeTruthy();
+    const refused = await ctx.internalAdapter.createSession(shadow.id).catch(() => null);
+    expect(refused).toBeFalsy();
+    const sessions = await runtime.db
+      .select()
+      .from(schema.session)
+      .where(eq(schema.session.userId, shadow.id));
+    expect(sessions).toHaveLength(0);
+    await runtime.close();
+  });
+
+  it("the API rejects a Better Auth session that resolves to a shadow user", async () => {
+    const { runtime, clock, world } = await setup();
+    const shadow = await createShadowUser(
+      runtime.db,
+      { schoolId: world.schoolA.id, name: "Shadow" },
+      clock,
+    );
+    const headers = { cookie: world.owner.sessionCookie, "x-school-id": world.schoolA.publicId };
+    const ok = await dispatch(runtime, { method: "GET", path: "/v1/school/team", headers });
+    expect(ok.status).toBe(200);
+    // Point the (valid, signed) session at the shadow user behind the hook's back.
+    await runtime.db
+      .update(schema.session)
+      .set({ userId: shadow.id })
+      .where(eq(schema.session.userId, world.owner.id));
+    const refused = await dispatch(runtime, { method: "GET", path: "/v1/school/team", headers });
+    expect(refused.status).toBe(401);
+    await runtime.close();
+  });
+});
+
+describe.serial("team guards", () => {
+  it("refuses invitations and acceptance for SSO-linked and shadow-backed accounts", async () => {
+    const { runtime, clock, world, link } = await setup();
+    const headers = { cookie: world.owner.sessionCookie, "x-school-id": world.schoolA.publicId };
+    // A shadow-backed SSO account: not invitable.
+    const sso = await link({ subject: "liam", email: "liam@acme.com" });
+    expect(sso.ok).toBe(true);
+    const refused = await dispatch(runtime, {
+      method: "POST",
+      path: "/v1/school/team/invitations",
+      headers,
+      body: { email: "liam@acme.com", permissions: ["products:read"] },
+    });
+    expect(refused.status).toBe(409);
+    expect((refused.body as { error?: { details?: { reason?: string } } }).error?.details?.reason ?? JSON.stringify(refused.body)).toContain("sso_linked_account");
+
+    // Invite first, then the address becomes SSO-linked: accepting is refused,
+    // and the existing account isn't moved onto the accepting user.
+    const invite = await dispatch(runtime, {
+      method: "POST",
+      path: "/v1/school/team/invitations",
+      headers,
+      body: { email: world.outsider.email, permissions: ["products:read"] },
+    });
+    expect(invite.status).toBe(201);
+    const body = invite.body as { id: string; token: string };
+    const linked = await seedRealLearner(runtime.db, clock, world.schoolA.publicId, world.outsider.email);
+    // Link SSO on that account: verify the outsider's domain for the connection.
+    await runtime.db.insert(schema.schoolSsoDomains).values({
+      id: uuidv7(clock),
+      connectionId: (await runtime.db.select().from(schema.schoolSsoConnections))[0]!.id,
+      schoolId: world.schoolA.id,
+      domain: "example.com",
+      verificationToken: "v".repeat(32),
+      verifiedAt: clock.now(),
+      createdAt: clock.now(),
+    });
+    const l2 = await link({ subject: "outsider", email: world.outsider.email });
+    expect(l2.ok && l2.value.id === linked.session.schoolAccount.id).toBe(true);
+    const accept = await dispatch(runtime, {
+      method: "POST",
+      path: "/v1/team-invitations/accept",
+      headers: { cookie: world.outsider.sessionCookie },
+      body: { invitationId: body.id, token: body.token },
+    });
+    expect(accept.status).toBe(409);
+    const memberships = await runtime.db
+      .select()
+      .from(schema.memberships)
+      .where(eq(schema.memberships.schoolAccountId, linked.session.schoolAccount.id));
+    expect(memberships).toHaveLength(0);
+    await runtime.close();
+  });
+});
+
+describe.serial("sso sessions", () => {
+  async function ssoSession() {
+    const ctx = await setup();
+    const created = await ctx.link({ subject: "mia", email: "mia@acme.com" });
+    if (!created.ok) throw new Error();
+    const [school] = await ctx.runtime.db
+      .select()
+      .from(schema.schools)
+      .where(eq(schema.schools.id, ctx.world.schoolA.id));
+    const issued = await issueSchoolSession(ctx.runtime.db, {
+      school: school!,
+      schoolAccount: created.value,
+      userId: created.value.userId,
+      authenticationMethod: "sso",
+      ssoConnectionId: ctx.connection.id,
+      clock: ctx.clock,
+    });
+    if (!issued.ok) throw new Error("issue_failed");
+    return { ...ctx, school: school!, account: created.value, token: issued.value.token, issued: issued.value };
+  }
+  const authenticate = (c: Awaited<ReturnType<typeof ssoSession>>) =>
+    authenticateLearner(c.runtime.db, learnerCookie(c.token), c.clock);
+
+  it("works while the connection is active and stops the moment it is not", async () => {
+    const c = await ssoSession();
+    expect((await authenticate(c)).kind).toBe("authenticated");
+    for (const status of ["suspended", "disabled", "draft"] as const) {
+      await c.runtime.db
+        .update(schema.schoolSsoConnections)
+        .set({ status })
+        .where(eq(schema.schoolSsoConnections.id, c.connection.id));
+      expect((await authenticate(c)).kind).toBe("rejected");
+    }
+    await c.runtime.db
+      .update(schema.schoolSsoConnections)
+      .set({ status: "active" })
+      .where(eq(schema.schoolSsoConnections.id, c.connection.id));
+    expect((await authenticate(c)).kind).toBe("authenticated");
+    await c.runtime.close();
+  });
+
+  it("is rejected when its account joins the team, and never reads team powers", async () => {
+    const c = await ssoSession();
+    await c.runtime.db.insert(schema.memberships).values({
+      id: uuidv7(c.clock),
+      publicId: createPublicId("mbr", c.clock),
+      schoolId: c.world.schoolA.id,
+      schoolAccountId: c.account.id,
+      isOwner: false,
+      permissions: ["products:write", "communities:moderate"],
+      createdAt: c.clock.now(),
+      updatedAt: c.clock.now(),
+    });
+    expect((await authenticate(c)).kind).toBe("rejected");
+    await c.runtime.close();
+  });
+
+  it("gets no staff spaces even for a team account, while other methods do", async () => {
+    const { runtime, clock, world } = await setup();
+    const owner = await seedRealLearner(runtime.db, clock, world.schoolA.publicId, "owner-staff@example.com");
+    await runtime.db.insert(schema.memberships).values({
+      id: uuidv7(clock),
+      publicId: createPublicId("mbr", clock),
+      schoolId: world.schoolA.id,
+      schoolAccountId: owner.session.schoolAccount.id,
+      isOwner: false,
+      permissions: ["communities:moderate"],
+      createdAt: clock.now(),
+      updatedAt: clock.now(),
+    });
+    // A live community space the owner reaches as staff.
+    const now = clock.now();
+    await runtime.db
+      .update(schema.communities)
+      .set({ enabled: true })
+      .where(eq(schema.communities.schoolId, world.schoolA.id));
+    const spaceId = uuidv7(clock);
+    await runtime.db.insert(schema.spaces).values({
+      id: spaceId,
+      publicId: createPublicId("spc", clock),
+      schoolId: world.schoolA.id,
+      name: "Space",
+      slug: "space",
+      position: 1,
+      createdAt: now,
+      updatedAt: now,
+    });
+    const viaEmail = await staffSpaceIds(
+      runtime.db,
+      world.schoolA.id,
+      owner.session.schoolAccount.id,
+      "email",
+    );
+    const viaSso = await staffSpaceIds(
+      runtime.db,
+      world.schoolA.id,
+      owner.session.schoolAccount.id,
+      "sso",
+    );
+    expect(viaSso.size).toBe(0);
+    expect(viaEmail.has(spaceId)).toBe(true);
+    await runtime.close();
+  });
+
+  it("honours an earlier expiry and never a later one", async () => {
+    const c = await ssoSession();
+    const sooner = new Date(c.clock.now().getTime() + 60_000);
+    const later = new Date(c.clock.now().getTime() + 90 * 24 * 3600_000);
+    const a = await issueSchoolSession(c.runtime.db, {
+      school: c.school,
+      schoolAccount: c.account,
+      userId: c.account.userId,
+      authenticationMethod: "sso",
+      ssoConnectionId: c.connection.id,
+      expiresAt: sooner,
+      clock: c.clock,
+    });
+    const b = await issueSchoolSession(c.runtime.db, {
+      school: c.school,
+      schoolAccount: c.account,
+      userId: c.account.userId,
+      authenticationMethod: "sso",
+      ssoConnectionId: c.connection.id,
+      expiresAt: later,
+      clock: c.clock,
+    });
+    const expiry = async (token: string) =>
+      (
+        await authenticateLearner(c.runtime.db, learnerCookie(token), c.clock)
+      );
+    if (!a.ok || !b.ok) throw new Error();
+    const rows = await c.runtime.db.select().from(schema.schoolSessions);
+    const byDigest = (t: string) => rows.find((r) => r.id === (t === "a" ? a.value.session.sessionId : b.value.session.sessionId))!;
+    expect(byDigest("a").expiresAt.getTime()).toBe(sooner.getTime());
+    expect(byDigest("b").expiresAt.getTime()).toBeLessThan(later.getTime());
+    expect((await expiry(a.value.token)).kind).toBe("authenticated");
+    // An sso session needs a connection; other methods can't carry one.
+    const missing = await issueSchoolSession(c.runtime.db, {
+      school: c.school,
+      schoolAccount: c.account,
+      userId: c.account.userId,
+      authenticationMethod: "sso",
+      clock: c.clock,
+    });
+    expect(missing.ok).toBe(false);
+    const stray = await issueSchoolSession(c.runtime.db, {
+      school: c.school,
+      schoolAccount: c.account,
+      userId: c.account.userId,
+      authenticationMethod: "email",
+      ssoConnectionId: c.connection.id,
+      clock: c.clock,
+    });
+    expect(stray.ok).toBe(false);
+    await c.runtime.close();
+  });
+
+  it("an sso session is deleted with its connection", async () => {
+    const c = await ssoSession();
+    await c.runtime.db
+      .delete(schema.schoolSsoConnections)
+      .where(and(eq(schema.schoolSsoConnections.id, c.connection.id)));
+    const rows = await c.runtime.db.select().from(schema.schoolSessions);
+    expect(rows.filter((r) => r.authenticationMethod === "sso")).toHaveLength(0);
+    await c.runtime.close();
+  });
+});
+
+void signInLearnerWithIdentity;
diff --git a/apps/api/src/learner-sso.ts b/apps/api/src/learner-sso.ts
new file mode 100644
index 000000000..6f0581a5e
--- /dev/null
+++ b/apps/api/src/learner-sso.ts
@@ -0,0 +1,387 @@
+import { type Clock, createPublicId, uuidv7 } from "@codelitdev/platform";
+import { and, eq } from "drizzle-orm";
+import { ActivityType, recordActivity } from "./activities.js";
+import { setContactMarketingSubscription } from "./contacts.js";
+import * as schema from "./db/schema/index.js";
+import { enqueueLearnerContactSync } from "./learners.js";
+import { CONTACT_PUBLIC_ID_PREFIX } from "./public-id-prefixes.js";
+import { createShadowUser } from "./shadow-users.js";
+import { isVerifiedSsoDomainEmail } from "./sign-in-policy.js";
+import { parseSsoEmail } from "./sso-email.js";
+import type { AppDb } from "./types.js";
+
+// Linking an identity an IdP vouched for to a school account. An IdP proves
+// nothing about an email address, so everything here stays inside the one
+// school that owns the connection: it never creates, verifies or changes a
+// platform user by email, and never calls `ensureSchoolAccount` (which would
+// move an existing account onto whichever user it is called with).
+
+export type SsoLinkFailureReason =
+  | "sso_invalid_email"
+  | "sso_invalid_subject"
+  | "sso_connection_inactive"
+  | "sso_issuer_mismatch"
+  | "sso_domain_not_verified"
+  | "sso_account_is_team_member"
+  | "sso_account_inactive"
+  | "sso_identity_conflict";
+
+type SchoolAccount = typeof schema.schoolAccounts.$inferSelect;
+type SsoConnection = typeof schema.schoolSsoConnections.$inferSelect;
+
+export type LinkSsoIdentityResult =
+  | { ok: true; value: SchoolAccount; created: boolean }
+  | { ok: false; reason: SsoLinkFailureReason };
+
+const fail = (reason: SsoLinkFailureReason): { ok: false; reason: SsoLinkFailureReason } => ({
+  ok: false,
+  reason,
+});
+
+class RetryLink extends Error {}
+
+function isUniqueViolation(error: unknown): boolean {
+  let current: unknown = error;
+  for (let depth = 0; current && depth < 4; depth += 1) {
+    if ((current as { code?: string }).code === "23505") return true;
+    current = (current as { cause?: unknown }).cause;
+  }
+  return false;
+}
+
+async function accountIsTeamMember(
+  db: AppDb,
+  schoolId: string,
+  schoolAccountId: string,
+): Promise<boolean> {
+  const [row] = await db
+    .select({ id: schema.memberships.id })
+    .from(schema.memberships)
+    .where(
+      and(
+        eq(schema.memberships.schoolId, schoolId),
+        eq(schema.memberships.schoolAccountId, schoolAccountId),
+      ),
+    )
+    .limit(1);
+  return Boolean(row);
+}
+
+function displayNameFor(name: string | null | undefined, local: string): string {
+  return (name?.trim() || local).slice(0, 200);
+}
+
+/**
+ * Sign an already-validated IdP assertion into a school account:
+ * `{ connection, issuer, subject, email, name }`. See the plan's Phase 2.
+ */
+export async function linkSsoIdentity(
+  db: AppDb,
+  input: {
+    connection: Pick<SsoConnection, "id" | "schoolId">;
+    issuer: string;
+    subject: string;
+    email: string;
+    name?: string | null;
+  },
+  clock: Clock,
+): Promise<LinkSsoIdentityResult> {
+  // 0. Strict email.
+  const parsed = parseSsoEmail(input.email);
+  if (!parsed) return fail("sso_invalid_email");
+  if (
+    typeof input.subject !== "string" ||
+    input.subject.length === 0 ||
+    input.subject.length > 512 ||
+    typeof input.issuer !== "string" ||
+    input.issuer.length === 0
+  ) {
+    return fail("sso_invalid_subject");
+  }
+  const [connection] = await db
+    .select()
+    .from(schema.schoolSsoConnections)
+    .where(eq(schema.schoolSsoConnections.id, input.connection.id))
+    .limit(1);
+  if (
+    !connection ||
+    connection.schoolId !== input.connection.schoolId ||
+    connection.status !== "active"
+  ) {
+    return fail("sso_connection_inactive");
+  }
+  const connectionIssuer = connection.idpEntityId ?? connection.oidcIssuer;
+  if (!connectionIssuer || connectionIssuer !== input.issuer) {
+    return fail("sso_issuer_mismatch");
+  }
+
+  let result: LinkSsoIdentityResult | null = null;
+  for (let attempt = 0; attempt < 3 && !result; attempt += 1) {
+    try {
+      result = await linkOnce(db, connection, input, parsed, clock);
+    } catch (error) {
+      // A concurrent sign-in created the same identity or account first;
+      // look everything up again rather than trusting stale reads.
+      if (error instanceof RetryLink || isUniqueViolation(error)) continue;
+      throw error;
+    }
+  }
+  if (!result) return fail("sso_identity_conflict");
+  if (!result.ok) return result;
+
+  await afterSignIn(db, connection, result.value, result.created, clock);
+  return result;
+}
+
+async function linkOnce(
+  db: AppDb,
+  connection: SsoConnection,
+  input: { issuer: string; subject: string; name?: string | null },
+  parsed: { email: string; local: string },
+  clock: Clock,
+): Promise<LinkSsoIdentityResult> {
+  const schoolId = connection.schoolId;
+  const now = clock.now();
+
+  // 1. An identity already linked for this subject wins over anything by email.
+  const [identity] = await db
+    .select()
+    .from(schema.schoolSsoIdentities)
+    .where(
+      and(
+        eq(schema.schoolSsoIdentities.connectionId, connection.id),
+        eq(schema.schoolSsoIdentities.subject, input.subject),
+      ),
+    )
+    .limit(1);
+  if (identity) {
+    if (identity.issuer !== input.issuer) return fail("sso_issuer_mismatch");
+    const [account] = await db
+      .select()
+      .from(schema.schoolAccounts)
+      .where(
+        and(
+          eq(schema.schoolAccounts.id, identity.schoolAccountId),
+          eq(schema.schoolAccounts.schoolId, schoolId),
+        ),
+      )
+      .limit(1);
+    if (!account) return fail("sso_account_inactive");
+    if (account.status !== "active") return fail("sso_account_inactive");
+    if (await accountIsTeamMember(db, schoolId, account.id)) {
+      return fail("sso_account_is_team_member");
+    }
+    return db.transaction(async (transaction) => {
+      const tx = transaction as unknown as AppDb;
+      let current = account;
+      if (account.email !== parsed.email) {
+        const [shadow] = await tx
+          .select({ userId: schema.ssoShadowUsers.userId })
+          .from(schema.ssoShadowUsers)
+          .where(eq(schema.ssoShadowUsers.userId, account.userId))
+          .limit(1);
+        const [taken] = await tx
+          .select({ id: schema.schoolAccounts.id })
+          .from(schema.schoolAccounts)
+          .where(
+            and(
+              eq(schema.schoolAccounts.schoolId, schoolId),
+              eq(schema.schoolAccounts.email, parsed.email),
+            ),
+          )
+          .limit(1);
+        // Emails change at the IdP, so a change is followed only for accounts
+        // that exist because of SSO, in a verified domain, and never onto
+        // an address another account in the school already has.
+        if (
+          shadow &&
+          !taken &&
+          (await isVerifiedSsoDomainEmail(tx, connection.id, parsed.email))
+        ) {
+          const [updated] = await tx
+            .update(schema.schoolAccounts)
+            .set({
+              email: parsed.email,
+              displayName: displayNameFor(input.name, parsed.local),
+              updatedAt: now,
+            })
+            .where(eq(schema.schoolAccounts.id, account.id))
+            .returning();
+          current = updated!;
+        }
+      }
+      await tx
+        .update(schema.schoolSsoIdentities)
+        .set({ lastEmail: parsed.email, lastSignedInAt: now })
+        .where(eq(schema.schoolSsoIdentities.id, identity.id));
+      return { ok: true as const, value: current, created: false };
+    });
+  }
+
+  // 2. A new identity needs an email in a domain the school proved it owns.
+  if (!(await isVerifiedSsoDomainEmail(db, connection.id, parsed.email))) {
+    return fail("sso_domain_not_verified");
+  }
+
+  // 3. Link to the school's account for that email, or create one.
+  const [existing] = await db
+    .select()
+    .from(schema.schoolAccounts)
+    .where(
+      and(
+        eq(schema.schoolAccounts.schoolId, schoolId),
+        eq(schema.schoolAccounts.email, parsed.email),
+      ),
+    )
+    .limit(1);
+  if (existing) return linkExisting(db, connection, existing, input, parsed.email, clock);
+
+  const attempt = await db.transaction(async (transaction) => {
+    const tx = transaction as unknown as AppDb;
+    const shadow = await createShadowUser(
+      tx,
+      { schoolId, name: displayNameFor(input.name, parsed.local) },
+      clock,
+    );
+    const [account] = await tx
+      .insert(schema.schoolAccounts)
+      .values({
+        id: uuidv7(clock),
+        publicId: createPublicId(CONTACT_PUBLIC_ID_PREFIX, clock),
+        schoolId,
+        userId: shadow.id,
+        email: parsed.email,
+        displayName: displayNameFor(input.name, parsed.local),
+        status: "active",
+        createdAt: now,
+        updatedAt: now,
+      })
+      .onConflictDoNothing({
+        target: [schema.schoolAccounts.schoolId, schema.schoolAccounts.email],
+      })
+      .returning();
+    if (!account) {
+      // Someone else created the account between our lookup and insert.
+      // Roll the shadow user back and link to theirs, untouched.
+      throw new RetryLink();
+    }
+    await tx.insert(schema.schoolSsoIdentities).values({
+      id: uuidv7(clock),
+      schoolId,
+      connectionId: connection.id,
+      issuer: input.issuer,
+      subject: input.subject,
+      schoolAccountId: account.id,
+      lastEmail: parsed.email,
+      lastSignedInAt: now,
+      createdAt: now,
+    });
+    return account;
+  });
+  return { ok: true, value: attempt, created: true };
+}
+
+async function linkExisting(
+  db: AppDb,
+  connection: SsoConnection,
+  account: SchoolAccount,
+  input: { issuer: string; subject: string },
+  email: string,
+  clock: Clock,
+): Promise<LinkSsoIdentityResult> {
+  if (account.status !== "active") return fail("sso_account_inactive");
+  // 4. Team members sign in to the website with email or Google, never SSO.
+  if (await accountIsTeamMember(db, connection.schoolId, account.id)) {
+    return fail("sso_account_is_team_member");
+  }
+  const now = clock.now();
+  const [already] = await db
+    .select({ id: schema.schoolSsoIdentities.id })
+    .from(schema.schoolSsoIdentities)
+    .where(
+      and(
+        eq(schema.schoolSsoIdentities.connectionId, connection.id),
+        eq(schema.schoolSsoIdentities.schoolAccountId, account.id),
+      ),
+    )
+    .limit(1);
+  // The account is already linked to a different person at the IdP.
+  if (already) return fail("sso_identity_conflict");
+  // The account's user row is never touched.
+  await db.insert(schema.schoolSsoIdentities).values({
+    id: uuidv7(clock),
+    schoolId: connection.schoolId,
+    connectionId: connection.id,
+    issuer: input.issuer,
+    subject: input.subject,
+    schoolAccountId: account.id,
+    lastEmail: email,
+    lastSignedInAt: now,
+    createdAt: now,
+  });
+  return { ok: true, value: account, created: false };
+}
+
+async function afterSignIn(
+  db: AppDb,
+  connection: SsoConnection,
+  account: SchoolAccount,
+  created: boolean,
+  clock: Clock,
+): Promise<void> {
+  const now = clock.now();
+  try {
+    if (created) {
+      await recordActivity(
+        db,
+        {
+          schoolId: connection.schoolId,
+          actorId: account.publicId,
+          type: ActivityType.USER_CREATED,
+          entityId: account.publicId,
+          metadata: { email: account.email },
+        },
+        clock,
+      );
+    }
+    await recordActivity(
+      db,
+      {
+        schoolId: connection.schoolId,
+        actorId: account.publicId,
+        type: ActivityType.LEARNER_SIGNED_IN,
+        entityId: account.publicId,
+        metadata: { method: "sso", at: now.toISOString() },
+      },
+      clock,
+    );
+  } catch (error) {
+    console.error("[recordActivity failed on sso sign-in]", error);
+  }
+  await db
+    .update(schema.schoolAccounts)
+    .set({
+      lastActiveAt: now,
+      updatedAt: now,
+      ...(account.learnerRegisteredAt ? {} : { learnerRegisteredAt: now }),
+    })
+    .where(eq(schema.schoolAccounts.id, account.id));
+  if (created) {
+    // A fake IdP must not add mailing-list contacts the school has no consent for.
+    await setContactMarketingSubscription(db, {
+      schoolId: connection.schoolId,
+      account,
+      subscribed: false,
+      reason: "sso_created",
+      clock,
+    });
+  } else {
+    await enqueueLearnerContactSync(
+      db,
+      connection.schoolId,
+      { email: account.email, name: account.displayName, id: account.id },
+      clock,
+      { reason: "learner_login" },
+    );
+  }
+}
diff --git a/apps/api/src/learners.ts b/apps/api/src/learners.ts
index 3c254a7c3..280c292cf 100644
--- a/apps/api/src/learners.ts
+++ b/apps/api/src/learners.ts
@@ -28,8 +28,17 @@ import {
   subscribeNewsletter,
 } from "./contacts.js";
 import { CONTACT_PUBLIC_ID_PREFIX } from "./public-id-prefixes.js";
+import {
+  deleteShadowUserIfOrphaned,
+  isShadowUser,
+  isShadowUserEmail,
+} from "./shadow-users.js";
+import { sessionMethodAllowed } from "./sign-in-policy.js";
 import type { AppDb } from "./types.js";
 
+/** How a learner proved who they are to a school. */
+export type LearnerAuthenticationMethod = "email" | "google" | "sso";
+
 export const LEARNER_SESSION_COOKIE = "courselit.learner.session";
 // When cookies are secure the learner session is a `__Host-` cookie (Secure,
 // Path=/, no Domain), so a sibling subdomain cannot plant one for the parent.
@@ -116,8 +125,14 @@ export type LearnerSession = {
   learner: typeof schema.schoolAccounts.$inferSelect & { name: string };
   school: typeof schema.schools.$inferSelect;
   sessionId: string;
+  /**
+   * The platform user behind the school account. For an `sso` learner it can
+   * be a real platform user, so it must only ever be used inside school-scoped
+   * queries; never on `user`, `session`, `account`, `selected_schools` or
+   * `memberships` (a test scans the source for this).
+   */
   userId: string;
-  authenticationMethod: "email" | "google";
+  authenticationMethod: LearnerAuthenticationMethod;
 };
 
 export function digestToken(token: string): string {
@@ -542,6 +557,7 @@ export async function authenticateLearner(
         session: schema.schoolSessions,
         account: schema.schoolAccounts,
         school: schema.schools,
+        ssoStatus: schema.schoolSsoConnections.status,
       })
       .from(schema.schoolSessions)
       .innerJoin(
@@ -549,6 +565,10 @@ export async function authenticateLearner(
         eq(schema.schoolAccounts.id, schema.schoolSessions.schoolAccountId),
       )
       .innerJoin(schema.schools, eq(schema.schools.id, schema.schoolSessions.schoolId))
+      .leftJoin(
+        schema.schoolSsoConnections,
+        eq(schema.schoolSsoConnections.id, schema.schoolSessions.ssoConnectionId),
+      )
       .where(eq(schema.schoolSessions.tokenDigest, digest))
       .limit(1);
     const row = rows[0];
@@ -558,12 +578,32 @@ export async function authenticateLearner(
     if (row.account.status !== "active") {
       return { kind: "rejected", error: createPlatformError("unauthenticated") };
     }
-    const hasGoogle = Boolean(
-      process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET,
-    );
-    const allowedMethods = hasGoogle ? ["email", "google"] : ["email"];
-    if (!allowedMethods.includes(row.session.authenticationMethod)) {
-      return { kind: "rejected", error: createPlatformError("unauthenticated") };
+    if (row.session.authenticationMethod === "sso") {
+      // An sso session lives only while its connection is active; this is
+      // read in the same query, so disabling a connection (or losing the plan,
+      // which suspends it) takes effect at once.
+      if (!row.session.ssoConnectionId || row.ssoStatus !== "active") {
+        return { kind: "rejected", error: createPlatformError("unauthenticated") };
+      }
+      // Team members sign in to the website with email or Google. An account
+      // that joined the team after signing in with sso loses the session.
+      const [team] = await db
+        .select({ id: schema.memberships.id })
+        .from(schema.memberships)
+        .where(eq(schema.memberships.schoolAccountId, row.account.id))
+        .limit(1);
+      if (team) {
+        return { kind: "rejected", error: createPlatformError("unauthenticated") };
+      }
+    } else {
+      const policy = await sessionMethodAllowed(db, {
+        school: row.school,
+        email: row.account.email,
+        method: row.session.authenticationMethod,
+      });
+      if (!policy.allowed) {
+        return { kind: "rejected", error: createPlatformError("unauthenticated") };
+      }
     }
     return {
       kind: "authenticated",
@@ -636,17 +676,36 @@ export async function ensureSchoolAccount(
         : input.image
           ? { url: input.image }
           : byEmail[0].avatar;
-    const updated = await db
-      .update(schema.schoolAccounts)
-      .set({
-        userId: input.userId,
-        displayName: input.displayName?.trim() || byEmail[0].displayName,
-        avatar,
-        updatedAt: now,
-      })
-      .where(eq(schema.schoolAccounts.id, byEmail[0].id))
-      .returning();
-    return updated[0];
+    const previousUserId = byEmail[0].userId;
+    return db.transaction(async (transaction) => {
+      const tx = transaction as unknown as AppDb;
+      const updated = await tx
+        .update(schema.schoolAccounts)
+        .set({
+          userId: input.userId,
+          displayName: input.displayName?.trim() || byEmail[0]!.displayName,
+          avatar,
+          updatedAt: now,
+        })
+        .where(eq(schema.schoolAccounts.id, byEmail[0]!.id))
+        .returning();
+      if (previousUserId !== input.userId) {
+        // The account moves to the person who proved the address. Keep any
+        // session it holds pointing at the account's current user, then drop
+        // the shadow user the account no longer needs. The SSO identity row
+        // stays linked to the account.
+        await tx
+          .update(schema.schoolSessions)
+          .set({ userId: input.userId })
+          .where(eq(schema.schoolSessions.schoolAccountId, byEmail[0]!.id));
+        await tx
+          .update(schema.schoolAuthTickets)
+          .set({ userId: input.userId })
+          .where(eq(schema.schoolAuthTickets.schoolAccountId, byEmail[0]!.id));
+        await deleteShadowUserIfOrphaned(tx, previousUserId);
+      }
+      return updated[0]!;
+    });
   }
   const publicId = createPublicId(CONTACT_PUBLIC_ID_PREFIX, input.clock);
   const name = input.displayName?.trim() || learnerNameFromEmail(email);
@@ -680,13 +739,49 @@ export async function issueSchoolSession(
     school: typeof schema.schools.$inferSelect;
     schoolAccount: typeof schema.schoolAccounts.$inferSelect;
     userId: string;
-    authenticationMethod: "email" | "google";
+    authenticationMethod: LearnerAuthenticationMethod;
+    /** For `sso`: the connection the session belongs to. */
+    ssoConnectionId?: string | null;
+    /** An earlier end than the default, e.g. the IdP's session end. Never later. */
+    expiresAt?: Date | null;
     clock: Clock;
   },
-): Promise<{ token: string; dto: LearnerDto; session: LearnerSession }> {
+): Promise<
+  | { ok: true; value: { token: string; dto: LearnerDto; session: LearnerSession } }
+  | { ok: false; error: PlatformError }
+> {
+  // The only place a school session is created, so the sign-in policy
+  // (methods turned on, SSO enforcement) holds on every path.
+  if (input.authenticationMethod === "sso" && !input.ssoConnectionId) {
+    return { ok: false, error: createPlatformError("forbidden") };
+  }
+  if (input.authenticationMethod !== "sso" && input.ssoConnectionId) {
+    return { ok: false, error: createPlatformError("forbidden") };
+  }
+  const policy = await sessionMethodAllowed(db, {
+    school: input.school,
+    email: input.schoolAccount.email,
+    method: input.authenticationMethod,
+    ssoConnectionId: input.ssoConnectionId,
+  });
+  if (!policy.allowed) {
+    return {
+      ok: false,
+      error: createPlatformError("forbidden", {
+        safeDetails: { reason: policy.reason },
+      }),
+    };
+  }
   const token = randomBytes(32).toString("base64url");
   const sessionId = uuidv7(input.clock);
   const now = input.clock.now();
+  const defaultExpiry = now.getTime() + SESSION_TTL_MS;
+  const expiresAt = new Date(
+    input.expiresAt ? Math.min(defaultExpiry, input.expiresAt.getTime()) : defaultExpiry,
+  );
+  if (expiresAt.getTime() <= now.getTime()) {
+    return { ok: false, error: createPlatformError("unauthenticated") };
+  }
   await db.insert(schema.schoolSessions).values({
     id: sessionId,
     schoolId: input.school.id,
@@ -694,8 +789,9 @@ export async function issueSchoolSession(
     userId: input.userId,
     tokenDigest: digestToken(token),
     authenticationMethod: input.authenticationMethod,
+    ssoConnectionId: input.ssoConnectionId ?? null,
     authenticatedAt: now,
-    expiresAt: new Date(now.getTime() + SESSION_TTL_MS),
+    expiresAt,
     createdAt: now,
   });
   const session: LearnerSession = {
@@ -707,9 +803,12 @@ export async function issueSchoolSession(
     authenticationMethod: input.authenticationMethod,
   };
   return {
-    token,
-    dto: toLearnerDto(input.schoolAccount, input.school.publicId),
-    session,
+    ok: true,
+    value: {
+      token,
+      dto: toLearnerDto(input.schoolAccount, input.school.publicId),
+      session,
+    },
   };
 }
 
@@ -784,12 +883,18 @@ export async function admitLearner(
   | { ok: false; error: PlatformError }
 > {
   const { school } = input;
-  const hasGoogle = Boolean(
-    process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET,
-  );
-  const allowedMethods = hasGoogle ? ["email", "google"] : ["email"];
-  if (!allowedMethods.includes(input.authenticationMethod)) {
-    return { ok: false, error: createPlatformError("forbidden") };
+  const policy = await sessionMethodAllowed(db, {
+    school,
+    email: normalizeEmail(input.email),
+    method: input.authenticationMethod,
+  });
+  if (!policy.allowed) {
+    return {
+      ok: false,
+      error: createPlatformError("forbidden", {
+        safeDetails: { reason: policy.reason },
+      }),
+    };
   }
 
   const schoolAccount = await ensureSchoolAccount(db, {
@@ -887,11 +992,12 @@ export async function signInLearnerWithIdentity(
     authenticationMethod,
     clock,
   });
+  if (!issued.ok) return issued;
   return {
     ok: true,
-    value: issued.dto,
-    token: issued.token,
-    session: issued.session,
+    value: issued.value.dto,
+    token: issued.value.token,
+    session: issued.value.session,
   };
 }
 
@@ -906,9 +1012,16 @@ export async function findOrCreateVerifiedUser(
   name?: string,
 ): Promise<typeof schema.user.$inferSelect> {
   const normalized = normalizeEmail(email);
+  // Shadow users own SSO-created school accounts and must never be handed to
+  // a sign-in, verified, or taken over. Their address can't be anyone's real
+  // address; refuse it anyway.
+  if (isShadowUserEmail(normalized)) throw new Error("shadow_user_email");
   const existing = (
     await db.select().from(schema.user).where(eq(schema.user.email, normalized)).limit(1)
   )[0];
+  if (existing && (await isShadowUser(db, existing.id))) {
+    throw new Error("shadow_user_email");
+  }
   if (existing?.emailVerified) return existing;
   if (existing) {
     // Whoever created this user never proved they own the address; the
diff --git a/apps/api/src/login-methods.test.ts b/apps/api/src/login-methods.test.ts
new file mode 100644
index 000000000..e899a5e18
--- /dev/null
+++ b/apps/api/src/login-methods.test.ts
@@ -0,0 +1,166 @@
+import { afterAll, beforeEach, describe, expect, it } from "bun:test";
+import { eq } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { dispatch } from "./dispatch.js";
+import { ownerHeaders, ssoSetup, type SsoSetup } from "./test-sso-flow.js";
+import { seedRealLearner } from "./test-sso.js";
+
+const patch = (t: SsoSetup, loginMethods: string[], headers: Record<string, string> = ownerHeaders(t.world)) =>
+  dispatch(t.runtime, { method: "PATCH", path: "/v1/school/login-methods", headers, body: { loginMethods } });
+
+async function withGoogleKeys<T>(run: () => Promise<T>): Promise<T> {
+  const saved = [process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET];
+  process.env.GOOGLE_CLIENT_ID = "id";
+  process.env.GOOGLE_CLIENT_SECRET = "secret";
+  try {
+    return await run();
+  } finally {
+    if (saved[0] === undefined) delete process.env.GOOGLE_CLIENT_ID;
+    else process.env.GOOGLE_CLIENT_ID = saved[0];
+    if (saved[1] === undefined) delete process.env.GOOGLE_CLIENT_SECRET;
+    else process.env.GOOGLE_CLIENT_SECRET = saved[1];
+  }
+}
+
+
+// These tests decide for themselves whether Google keys exist. Bun loads the
+// developer's .env, so start each test without them and restore them after.
+const savedGoogleKeys = [process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET];
+beforeEach(() => {
+  delete process.env.GOOGLE_CLIENT_ID;
+  delete process.env.GOOGLE_CLIENT_SECRET;
+});
+afterAll(() => {
+  if (savedGoogleKeys[0] !== undefined) process.env.GOOGLE_CLIENT_ID = savedGoogleKeys[0];
+  if (savedGoogleKeys[1] !== undefined) process.env.GOOGLE_CLIENT_SECRET = savedGoogleKeys[1];
+});
+
+describe.serial("school login methods", () => {
+  it("won't turn off the last method, but allows it while SSO is active", async () => {
+    const t = await ssoSetup({ noConnection: true });
+    try {
+      const refused = await patch(t, []);
+      expect(refused.status).toBe(400);
+      expect(refused.body).toMatchObject({ details: { reason: "last_sign_in_method" } });
+      expect((await dispatch(t.runtime, { method: "GET", path: "/v1/school/login-methods", headers: ownerHeaders(t.world) })).body).toMatchObject({ loginMethods: ["email"] });
+    } finally {
+      await t.close();
+    }
+    const withSso = await ssoSetup();
+    try {
+      const response = await patch(withSso, []);
+      expect(response.status).toBe(200);
+      expect(response.body).toMatchObject({ loginMethods: [], sso: { active: true, displayName: "Acme employees" }, usable: ["sso"] });
+    } finally {
+      await withSso.close();
+    }
+  });
+
+  it("falls back to email codes when every method that is on is unusable", async () => {
+    const t = await ssoSetup({ noConnection: true });
+    try {
+      await t.runtime.db.update(schema.schools).set({ loginMethods: ["google"] });
+      const methods = await dispatch(t.runtime, { method: "GET", path: `/v1/public/${t.world.schoolA.publicId}/login-methods`, headers: {} });
+      expect(methods.body).toMatchObject({ loginMethods: ["email"], hasGoogle: false });
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("turns Google on only when the platform has Google keys", async () => {
+    const t = await ssoSetup({ noConnection: true });
+    try {
+      const refused = await patch(t, ["email", "google"]);
+      expect(refused.status).toBe(400);
+      expect(refused.body).toMatchObject({ details: { reason: "google_unavailable" } });
+      await withGoogleKeys(async () => {
+        const accepted = await patch(t, ["email", "google"]);
+        expect(accepted.status).toBe(200);
+        expect(accepted.body).toMatchObject({ loginMethods: ["email", "google"], googleAvailable: true, usable: ["email", "google"] });
+      });
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("turning a method off ends the sessions made with it and refuses it at its start", async () => {
+    const t = await ssoSetup({ noConnection: true });
+    try {
+      await withGoogleKeys(async () => {
+        await patch(t, ["email", "google"]);
+        const learner = await seedRealLearner(t.runtime.db, t.clock, t.world.schoolA.publicId, "someone@example.org");
+        expect(learner.token).toBeTruthy();
+        await t.runtime.db.update(schema.schoolSessions).set({ authenticationMethod: "google" });
+        const other = await seedRealLearner(t.runtime.db, t.clock, t.world.schoolA.publicId, "other@example.org");
+        expect(other.token).toBeTruthy();
+        expect((await t.runtime.db.select().from(schema.schoolSessions)).length).toBe(2);
+        // Email stays on, Google goes off: the Google session ends, the email one stays.
+        expect((await patch(t, ["email"])).status).toBe(200);
+        const remaining = await t.runtime.db.select().from(schema.schoolSessions);
+        expect(remaining.map((row) => row.authenticationMethod)).toEqual(["email"]);
+        const start = await dispatch(t.runtime, {
+          method: "POST",
+          path: "/v1/learner/auth/google",
+          headers: { "x-school-id": t.world.schoolA.publicId },
+          body: { host: "school-a.localhost:3001", nonce: "n".repeat(43) },
+        });
+        expect(start.status).toBe(403);
+      });
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("requires the settings permission and is reachable by OAuth and API credentials", async () => {
+    const t = await ssoSetup({ noConnection: true });
+    try {
+      expect((await patch(t, ["email"], { cookie: t.world.member.sessionCookie, "x-school-id": t.world.schoolA.publicId })).status).toBe(403);
+      expect((await patch(t, ["email"], { authorization: `Bearer ${t.world.owner.oauthToken}`, "x-school-id": t.world.schoolA.publicId })).status).toBe(200);
+      const read = await dispatch(t.runtime, { method: "GET", path: "/v1/school/login-methods", headers: { "x-api-key": t.world.apiKeyA.raw } });
+      expect([200, 403]).toContain(read.status);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("is an MCP tool that needs confirmation", async () => {
+    const t = await ssoSetup({ noConnection: true });
+    try {
+      const headers = { authorization: `Bearer ${t.world.owner.oauthToken}`, "x-school-id": t.world.schoolA.publicId };
+      const call = (args: Record<string, unknown>) =>
+        dispatch(t.runtime, {
+          method: "POST",
+          path: "/mcp",
+          headers,
+          body: { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "update_school_login_methods", arguments: args } },
+        });
+      const unconfirmed = await call({ loginMethods: ["email"] });
+      expect((unconfirmed.body as any).result.isError).toBe(true);
+      const confirmed = await call({ loginMethods: ["email"], confirm: true });
+      expect((confirmed.body as any).result.isError).toBeFalsy();
+      const read = await dispatch(t.runtime, {
+        method: "POST", path: "/mcp", headers,
+        body: { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "list_sso_connections", arguments: {} } },
+      });
+      expect((read.body as any).result.isError).toBeFalsy();
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("lists SSO in the public methods with its display name only when usable", async () => {
+    const t = await ssoSetup();
+    try {
+      const url = `/v1/public/${t.world.schoolA.publicId}/login-methods`;
+      expect((await dispatch(t.runtime, { method: "GET", path: url, headers: {} })).body).toMatchObject({
+        loginMethods: ["email", "sso"], hasSso: true, ssoDisplayName: "Acme employees",
+      });
+      await t.runtime.db.update(schema.schoolSsoConnections).set({ status: "disabled" }).where(eq(schema.schoolSsoConnections.id, t.connection.id));
+      expect((await dispatch(t.runtime, { method: "GET", path: url, headers: {} })).body).toMatchObject({
+        loginMethods: ["email"], hasSso: false, ssoDisplayName: null,
+      });
+    } finally {
+      await t.close();
+    }
+  });
+});
diff --git a/apps/api/src/login-methods.ts b/apps/api/src/login-methods.ts
new file mode 100644
index 000000000..fe4ee219b
--- /dev/null
+++ b/apps/api/src/login-methods.ts
@@ -0,0 +1,117 @@
+import type { BillingEngine } from "@codelitdev/billing/workflows";
+import { type Clock, createPlatformError, type PlatformError } from "@codelitdev/platform";
+import { eq } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { schoolHasFeature } from "./plan-features.js";
+import {
+  activeSsoConnection,
+  endSessionsForMethod,
+  platformGoogleAvailable,
+  usableSignInMethods,
+} from "./sign-in-policy.js";
+import { SSO_FEATURE } from "./sso-config.js";
+import type { AppDb } from "./types.js";
+
+type Billing = Pick<BillingEngine, "hasFeature">;
+type Result<T> = { ok: true; value: T } | { ok: false; error: PlatformError };
+type School = typeof schema.schools.$inferSelect;
+type Method = "email" | "google";
+
+export type SchoolLoginMethodsDto = {
+  loginMethods: Method[];
+  googleAvailable: boolean;
+  sso: { active: boolean; displayName: string | null; planAvailable: boolean };
+  usable: ("email" | "google" | "sso")[];
+};
+
+/**
+ * The sign-in methods learners can use right now: what the school turned on,
+ * adjusted by what is actually usable. SSO also needs the plan, which the
+ * policy check alone doesn't read.
+ */
+export async function usableLearnerMethods(
+  db: AppDb,
+  billing: Billing,
+  school: School,
+): Promise<{ methods: ("email" | "google" | "sso")[]; ssoDisplayName: string | null }> {
+  const methods = await usableSignInMethods(db, school);
+  const connection = methods.includes("sso") ? await activeSsoConnection(db, school.id) : null;
+  const ssoUsable =
+    connection !== null && (await schoolHasFeature(billing, school.id, SSO_FEATURE));
+  return {
+    methods: methods.filter((method) => method !== "sso" || ssoUsable),
+    ssoDisplayName: ssoUsable ? connection!.displayName : null,
+  };
+}
+
+export async function readSchoolLoginMethods(
+  db: AppDb,
+  billing: Billing,
+  schoolId: string,
+): Promise<Result<SchoolLoginMethodsDto>> {
+  const [school] = await db
+    .select()
+    .from(schema.schools)
+    .where(eq(schema.schools.id, schoolId))
+    .limit(1);
+  if (!school) return { ok: false, error: createPlatformError("not_found") };
+  const connection = await activeSsoConnection(db, school.id);
+  const usable = await usableLearnerMethods(db, billing, school);
+  return {
+    ok: true,
+    value: {
+      loginMethods: school.loginMethods,
+      googleAvailable: platformGoogleAvailable(),
+      sso: {
+        active: connection !== null,
+        displayName: connection?.displayName ?? null,
+        planAvailable: await schoolHasFeature(billing, school.id, SSO_FEATURE),
+      },
+      usable: usable.methods,
+    },
+  };
+}
+
+/**
+ * Turn email codes and Google on or off. At least one of email, Google and an
+ * active SSO connection stays on, and Google can be turned on only when the
+ * platform has Google keys. Turning a method off ends the sessions made with
+ * it, so it takes effect now rather than when they expire.
+ */
+export async function updateSchoolLoginMethods(
+  db: AppDb,
+  billing: Billing,
+  schoolId: string,
+  input: { loginMethods: Method[] },
+  clock: Clock,
+): Promise<Result<SchoolLoginMethodsDto>> {
+  const [school] = await db
+    .select()
+    .from(schema.schools)
+    .where(eq(schema.schools.id, schoolId))
+    .limit(1);
+  if (!school) return { ok: false, error: createPlatformError("not_found") };
+  const next = [...new Set(input.loginMethods)];
+  const invalid = (reason: string) => ({
+    ok: false as const,
+    error: createPlatformError("validation_failed", { safeDetails: { reason } }),
+  });
+  if (
+    next.includes("google") &&
+    !school.loginMethods.includes("google") &&
+    !platformGoogleAvailable()
+  ) {
+    return invalid("google_unavailable");
+  }
+  if (next.length === 0 && !(await activeSsoConnection(db, school.id))) {
+    return invalid("last_sign_in_method");
+  }
+  await db
+    .update(schema.schools)
+    .set({ loginMethods: next, updatedAt: clock.now() })
+    .where(eq(schema.schools.id, school.id));
+  for (const method of school.loginMethods) {
+    if (!next.includes(method)) await endSessionsForMethod(db, school.id, method);
+  }
+  return readSchoolLoginMethods(db, billing, schoolId);
+}
diff --git a/apps/api/src/mcp-tools/operation-descriptions.ts b/apps/api/src/mcp-tools/operation-descriptions.ts
index 1d1003ac8..be6f2f93c 100644
--- a/apps/api/src/mcp-tools/operation-descriptions.ts
+++ b/apps/api/src/mcp-tools/operation-descriptions.ts
@@ -165,6 +165,14 @@ export const OPERATION_DESCRIPTIONS: Readonly<Record<string, string>> = {
     "Checks the DNS records for a custom domain and marks it verified when they are right.",
   deleteSchoolHost:
     "Detaches a custom domain from the school. Confirm with the user first.",
+  getSchoolLoginMethods:
+    "Reads which sign-in methods the school's learners can use (email codes, Google, single sign-on) and which are on right now.",
+  updateSchoolLoginMethods:
+    "Turns learner sign-in with email codes or Google on or off. Turning a method off signs out learners who used it. At least one method always stays on. This changes how learners sign in. Confirm with the user first.",
+  listSsoConnections:
+    "Lists the school's single sign-on connections with their status, verified email domains and the values to enter at the identity provider. Secrets are never returned.",
+  getSsoConnection:
+    "Reads one single sign-on connection: status, identity provider settings, domains and the DNS record to publish for each, and whether it was tested and the plan allows it. Secrets are never returned.",
 
   // Website
   listSchoolWebsitePages: "Lists the school website's pages with their publish status.",
diff --git a/apps/api/src/openapi.ts b/apps/api/src/openapi.ts
index 7a8bb09d9..e6c6c51f0 100644
--- a/apps/api/src/openapi.ts
+++ b/apps/api/src/openapi.ts
@@ -159,6 +159,7 @@ function tagForPath(path: string | undefined): OpenApiTag {
   if (
     isPathOrChild(path, "/api/school") ||
     isPathOrChild(path, "/v1/api-keys") ||
+    isPathOrChild(path, "/v1/sso") ||
     isPathOrChild(path, "/v1/ai-connections") ||
     isPathOrChild(path, "/v1/invitations") ||
     isPathOrChild(path, "/v1/team-invitations") ||
diff --git a/apps/api/src/plan-features.test.ts b/apps/api/src/plan-features.test.ts
new file mode 100644
index 000000000..9b53d4bad
--- /dev/null
+++ b/apps/api/src/plan-features.test.ts
@@ -0,0 +1,219 @@
+import { describe, expect, it } from "bun:test";
+import { eq } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { enqueuePlanFeatureSync, schoolHasFeature, syncPlanFeatures } from "./plan-features.js";
+import { processPlatformJobs } from "./sso-jobs.js";
+import { buyPlan, changePlan, changeSubscription } from "./test-billing-plan.js";
+import { ssoSetup, type SsoSetup } from "./test-sso-flow.js";
+import { dispatch } from "./dispatch.js";
+import { ownerHeaders, ticketFrom } from "./test-sso-flow.js";
+import { seedRealLearner } from "./test-sso.js";
+
+const platformJobs = (t: SsoSetup) =>
+  t.runtime.db.select().from(schema.integrationOutboxJobs).where(eq(schema.integrationOutboxJobs.provider, "platform"));
+const statusOf = async (t: SsoSetup) =>
+  (await t.runtime.db.select().from(schema.schoolSsoConnections))[0]!.status;
+const quietLogger = { warn() {}, error() {}, info() {} } as never;
+
+describe.serial("plan gating for learner SSO", () => {
+  it("is available on Business, not on Pro or unpaid schools in cloud mode, and always in oss mode", async () => {
+    const t = await ssoSetup({ billingMode: "cloud", noConnection: true });
+    try {
+      const billing = t.runtime.billing.billing;
+      expect(await schoolHasFeature(billing, t.world.schoolA.id, "learner_sso")).toBe(false); // Pro
+      expect(await schoolHasFeature(billing, t.world.schoolB.id, "learner_sso")).toBe(false); // no plan
+      await buyPlan(t.runtime, t.world, t.world.schoolB.id, "business_month");
+      expect(await schoolHasFeature(billing, t.world.schoolB.id, "learner_sso")).toBe(true);
+      expect(await schoolHasFeature(billing, t.world.schoolB.id, "something_else")).toBe(false);
+    } finally {
+      await t.close();
+    }
+    const oss = await ssoSetup({ billingMode: "oss", noConnection: true });
+    try {
+      expect(await schoolHasFeature(oss.runtime.billing.billing, oss.world.schoolA.id, "learner_sso")).toBe(true);
+    } finally {
+      await oss.close();
+    }
+  });
+
+  it("fails closed when billing can't answer", async () => {
+    const throwing = { hasFeature: async () => { throw new Error("down"); } };
+    expect(await schoolHasFeature(throwing, "x", "learner_sso")).toBe(false);
+  });
+
+  it("only falls back to oss mode when BILLING_MODE=oss is set explicitly", async () => {
+    const source = await Bun.file(new URL("./runtime.ts", import.meta.url)).text();
+    expect(source).toContain('process.env.BILLING_MODE === "oss" ? "oss" : ("cloud" as const)');
+  });
+
+  it("queues a sync_plan_features job in the billing transaction on every projection", async () => {
+    const t = await ssoSetup({ billingMode: "cloud", noConnection: true });
+    try {
+      const before = (await platformJobs(t)).length;
+      const subscription = await buyPlan(t.runtime, t.world, t.world.schoolB.id, "business_month");
+      const afterBuy = await platformJobs(t);
+      expect(afterBuy.length).toBeGreaterThan(before);
+      expect(afterBuy.every((job) => job.type === "sync_plan_features" && job.status === "pending")).toBe(true);
+      expect(afterBuy.some((job) => job.schoolId === t.world.schoolB.id)).toBe(true);
+      // Even a projection that changes nothing material queues one.
+      const count = afterBuy.length;
+      await changeSubscription(t.runtime, subscription, {});
+      expect((await platformJobs(t)).length).toBeGreaterThan(count);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("a failing sync never rolls back a billing write, and is retried", async () => {
+    const t = await ssoSetup({ billingMode: "cloud", noConnection: true });
+    try {
+      const subscription = await buyPlan(t.runtime, t.world, t.world.schoolB.id, "business_month");
+      // The billing write committed and the plan is Business.
+      expect(await schoolHasFeature(t.runtime.billing.billing, t.world.schoolB.id, "learner_sso")).toBe(true);
+      // The real engine answers false when it can't read state; only a direct
+      // state read throws.
+      const failing = {
+        hasFeature: async () => false,
+        commercialState: async () => {
+          throw new Error("billing read failed");
+        },
+      };
+      const jobs = await platformJobs(t);
+      expect(jobs.length).toBeGreaterThan(0);
+      // Run the job with a broken sync: it fails and goes back to pending.
+      const { processNextPlatformJob } = await import("./integration-provisioning.js");
+      await processNextPlatformJob(t.runtime.db, t.clock, quietLogger, async (job) => {
+        await syncPlanFeatures(t.runtime.db, failing, job.schoolId, t.clock);
+      });
+      const retried = (await platformJobs(t)).filter((job) => job.attempts > 0);
+      expect(retried).toHaveLength(1);
+      expect(retried[0]!.status).toBe("pending");
+      expect(retried[0]!.lastError).toContain("billing read failed");
+      expect(await schoolHasFeature(t.runtime.billing.billing, t.world.schoolB.id, "learner_sso")).toBe(true);
+      expect(subscription).toBeTruthy();
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("a hook insert for a billable entity that isn't a school does nothing and doesn't fail", async () => {
+    const t = await ssoSetup({ billingMode: "cloud", noConnection: true });
+    try {
+      const before = (await platformJobs(t)).length;
+      await enqueuePlanFeatureSync(t.runtime.db, crypto.randomUUID(), t.clock);
+      expect((await platformJobs(t)).length).toBe(before);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("suspends on downgrade, kills sessions, keeps enforcement from locking learners out, then restores", async () => {
+    const t = await ssoSetup({ billingMode: "cloud", enforcement: "required_for_domains", status: "draft" });
+    try {
+      // School A: Pro -> Business, then activate the connection.
+      await changePlan(t.runtime, t.world, t.world.schoolA.id, "business_month");
+      expect(await schoolHasFeature(t.runtime.billing.billing, t.world.schoolA.id, "learner_sso")).toBe(true);
+      const activate = await dispatch(t.runtime, {
+        method: "POST",
+        path: `/v1/sso/connections/${t.connection.publicId}/activate`,
+        headers: ownerHeaders(t.world),
+        body: {},
+      });
+      expect(activate.status).toBe(200);
+      await processPlatformJobs(t.runtime.db, t.runtime.billing.billing, t.clock, quietLogger);
+      expect(await statusOf(t)).toBe("active");
+
+      // An SSO sign-in works, and its session exists.
+      const { token, requestId } = await t.startSignIn();
+      const ticket = ticketFrom((await t.acs(t.response(requestId!), token!)).headers.get("location"))!;
+      expect((await t.redeem(ticket)).status).toBe(200);
+      // A mid-flight sign-in that will outlive the downgrade.
+      const midFlight = await t.startSignIn();
+
+      // Downgrade: Pro again.
+      await changePlan(t.runtime, t.world, t.world.schoolA.id, "pro_month");
+      expect(await schoolHasFeature(t.runtime.billing.billing, t.world.schoolA.id, "learner_sso")).toBe(false);
+      // The billing hook queued the sync; the connection is still active until it runs.
+      expect(await statusOf(t)).toBe("active");
+      // The plan check at the ACS refuses a ticket even before the sync.
+      const refused = await t.acs(t.response(midFlight.requestId!), midFlight.token!);
+      expect(ticketFrom(refused.headers.get("location"))).toBeNull();
+
+      await processPlatformJobs(t.runtime.db, t.runtime.billing.billing, t.clock, quietLogger);
+      expect(await statusOf(t)).toBe("suspended");
+      expect(await t.runtime.db.select().from(schema.schoolSessions)).toHaveLength(0);
+      const events = await t.runtime.db.select().from(schema.schoolSsoEvents);
+      expect(events.some((event) => event.action === "connection.suspended")).toBe(true);
+      const emails = (await t.runtime.db.select().from(schema.integrationOutboxJobs)).filter((job) => job.type === "send_system_email");
+      expect(emails.some((job) => (job.payload as { subject: string }).subject.includes("suspended"))).toBe(true);
+      // Enforcement is ignored while suspended: email-code sign-in for the SSO domain works.
+      const learner = await seedRealLearner(t.runtime.db, t.clock, t.world.schoolA.publicId, "someone@acme.com");
+      expect(learner.token).toBeTruthy();
+      // Sign-in and the public methods don't offer SSO.
+      expect((await t.startSignIn()).started.status).toBe(403);
+      const methods = await dispatch(t.runtime, { method: "GET", path: `/v1/public/${t.world.schoolA.publicId}/login-methods`, headers: {} });
+      expect((methods.body as { loginMethods: string[] }).loginMethods).not.toContain("sso");
+
+      // Syncing again changes nothing (idempotent).
+      expect(await syncPlanFeatures(t.runtime.db, t.runtime.billing.billing, t.world.schoolA.id, t.clock)).toEqual({ suspended: 0, restored: 0, drafted: 0 });
+
+      // Back to Business: restored, and enforcement ends non-SSO sessions in its domains.
+      await changePlan(t.runtime, t.world, t.world.schoolA.id, "business_month");
+      await processPlatformJobs(t.runtime.db, t.runtime.billing.billing, t.clock, quietLogger);
+      expect(await statusOf(t)).toBe("active");
+      expect(await t.runtime.db.select().from(schema.schoolSessions)).toHaveLength(0);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("goes to draft instead of active when a domain lapsed or the settings changed while suspended", async () => {
+    const t = await ssoSetup({ billingMode: "oss", status: "suspended" });
+    try {
+      // oss mode has the feature, so the sync tries to restore it.
+      await t.runtime.db.update(schema.schoolSsoDomains).set({ verifiedAt: null });
+      const result = await syncPlanFeatures(t.runtime.db, t.runtime.billing.billing, t.world.schoolA.id, t.clock);
+      expect(result).toEqual({ suspended: 0, restored: 0, drafted: 1 });
+      expect(await statusOf(t)).toBe("draft");
+      const emails = (await t.runtime.db.select().from(schema.integrationOutboxJobs)).filter((job) => job.type === "send_system_email");
+      expect(emails.some((job) => (job.payload as { subject: string }).subject.includes("needs attention"))).toBe(true);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("restores a suspended connection whose settings didn't change", async () => {
+    const t = await ssoSetup({ billingMode: "oss", status: "suspended" });
+    try {
+      const result = await syncPlanFeatures(t.runtime.db, t.runtime.billing.billing, t.world.schoolA.id, t.clock);
+      expect(result.restored).toBe(1);
+      expect(await statusOf(t)).toBe("active");
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("a billing read failure in the sync throws instead of suspending anyone", async () => {
+    const t = await ssoSetup({ billingMode: "oss" });
+    try {
+      await expect(
+        syncPlanFeatures(
+          t.runtime.db,
+          {
+            // What the real engine does when billing can't be read: hasFeature
+            // fails closed, a direct state read throws.
+            hasFeature: async () => false,
+            commercialState: async () => {
+              throw new Error("nope");
+            },
+          },
+          t.world.schoolA.id,
+          t.clock,
+        ),
+      ).rejects.toThrow("nope");
+      expect(await statusOf(t)).toBe("active");
+    } finally {
+      await t.close();
+    }
+  });
+});
diff --git a/apps/api/src/plan-features.ts b/apps/api/src/plan-features.ts
new file mode 100644
index 000000000..de2e8d81e
--- /dev/null
+++ b/apps/api/src/plan-features.ts
@@ -0,0 +1,227 @@
+import type { BillingEngine } from "@codelitdev/billing/workflows";
+import { type Clock, uuidv7 } from "@codelitdev/platform";
+import { and, eq, inArray, sql } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { endNonSsoSessionsForEnforcedDomains } from "./sign-in-policy.js";
+import { activationBlocker, SSO_FEATURE } from "./sso-config.js";
+import { notifySsoOwner, recordSsoEvent } from "./sso-events.js";
+import type { AppDb } from "./types.js";
+
+type Billing = Pick<BillingEngine, "hasFeature">;
+type SyncBilling = Pick<BillingEngine, "hasFeature" | "commercialState">;
+
+/**
+ * `hasFeature` fails closed: a billing read error answers false. That is
+ * right for letting someone in, but wrong for taking SSO away from a paying
+ * school, so before the sync acts on a false answer it reads the commercial
+ * state directly, which throws when billing can't be read. The job then
+ * retries instead of suspending every connection on a transient error.
+ */
+export async function planIncludesFeatureOrThrow(
+  billing: SyncBilling,
+  schoolId: string,
+  feature: string,
+): Promise<boolean> {
+  if ((await billing.hasFeature(schoolId, feature)) === true) return true;
+  await billing.commercialState(schoolId);
+  return (await billing.hasFeature(schoolId, feature)) === true;
+}
+
+/**
+ * Whether a school's plan includes a feature. The rules (every feature in
+ * `oss` mode, entitled statuses only) live in `@codelitdev/billing`. This
+ * wrapper only fails closed: if billing can't answer, the answer is no.
+ */
+export async function schoolHasFeature(
+  billing: Billing,
+  schoolInternalId: string,
+  feature: string,
+): Promise<boolean> {
+  try {
+    return (await billing.hasFeature(schoolInternalId, feature)) === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Queue a `sync_plan_features` job for a school. Called by the billing
+ * lifecycle hook inside the billing transaction, so the job commits only if
+ * the plan change does. It never does SSO work itself: in Postgres a failed
+ * statement aborts the whole transaction, so a bug in the sync would roll the
+ * billing write back. The insert is conditional on the school existing so a
+ * billable entity that is not a school can't make it fail.
+ */
+export async function enqueuePlanFeatureSync(
+  client: Pick<AppDb, "execute">,
+  schoolId: string,
+  clock: Clock,
+): Promise<void> {
+  const now = clock.now().toISOString();
+  await client.execute(sql`
+    INSERT INTO integration_outbox_jobs
+      (id, school_id, provider, type, payload, status, attempts, revision, next_attempt_at, created_at, updated_at)
+    SELECT ${uuidv7(clock)}::uuid, s.id, 'platform', 'sync_plan_features', '{}'::jsonb, 'pending', 0, 1,
+           ${now}::timestamptz, ${now}::timestamptz, ${now}::timestamptz
+    FROM schools s
+    WHERE s.id::text = ${schoolId}
+  `);
+}
+
+/**
+ * Bring a school's SSO connections in line with its plan. Safe to run any
+ * number of times: it reads the current plan itself.
+ *
+ * - Without `learner_sso`: active connections become `suspended`, their
+ *   sessions end and the owner is emailed. Enforcement stops applying on its
+ *   own because only an `active` connection is ever consulted.
+ * - With it: suspended connections become `active` again when the activation
+ *   rules still hold (a domain may have lapsed, or the settings changed),
+ *   otherwise `draft`, and the owner is emailed. Turning enforcement back on
+ *   ends the non-SSO sessions of the enforced domains, like the first time.
+ *
+ * A billing read that fails throws, so the job is retried instead of
+ * suspending everyone on a transient error.
+ */
+export async function syncPlanFeatures(
+  db: AppDb,
+  billing: SyncBilling,
+  schoolId: string,
+  clock: Clock,
+): Promise<{ suspended: number; restored: number; drafted: number }> {
+  const result = { suspended: 0, restored: 0, drafted: 0 };
+  const available = await planIncludesFeatureOrThrow(billing, schoolId, SSO_FEATURE);
+  const connections = await db
+    .select()
+    .from(schema.schoolSsoConnections)
+    .where(
+      and(
+        eq(schema.schoolSsoConnections.schoolId, schoolId),
+        inArray(schema.schoolSsoConnections.status, ["active", "suspended"]),
+      ),
+    );
+  const now = clock.now();
+  for (const connection of connections) {
+    if (!available && connection.status === "active") {
+      const changed = await db
+        .update(schema.schoolSsoConnections)
+        .set({ status: "suspended", updatedAt: now })
+        .where(
+          and(
+            eq(schema.schoolSsoConnections.id, connection.id),
+            eq(schema.schoolSsoConnections.status, "active"),
+          ),
+        )
+        .returning({ id: schema.schoolSsoConnections.id });
+      if (!changed[0]) continue;
+      await db
+        .delete(schema.schoolSessions)
+        .where(eq(schema.schoolSessions.ssoConnectionId, connection.id));
+      await recordSsoEvent(
+        db,
+        { schoolId, connectionId: connection.id, action: "connection.suspended", reason: "plan_lost_feature" },
+        clock,
+      );
+      await notifySsoOwner(
+        db,
+        {
+          schoolId,
+          subject: "Single sign-on was suspended",
+          lines: [
+            `Single sign-on (${connection.displayName}) was suspended because your school's plan no longer includes it.`,
+            "Learners can sign in with the other methods you have turned on. Upgrade to the Business plan to restore it; your settings are kept.",
+          ],
+          idempotencyKey: `sso-suspended:${connection.id}:${now.getTime()}`,
+        },
+        clock,
+      );
+      result.suspended += 1;
+    } else if (available && connection.status === "suspended") {
+      const blocker = await activationBlocker(db, connection);
+      if (blocker) {
+        await db
+          .update(schema.schoolSsoConnections)
+          .set({ status: "draft", updatedAt: now })
+          .where(
+            and(
+              eq(schema.schoolSsoConnections.id, connection.id),
+              eq(schema.schoolSsoConnections.status, "suspended"),
+            ),
+          );
+        await recordSsoEvent(
+          db,
+          { schoolId, connectionId: connection.id, action: "connection.drafted", reason: blocker },
+          clock,
+        );
+        await notifySsoOwner(
+          db,
+          {
+            schoolId,
+            subject: "Single sign-on needs attention",
+            lines: [
+              `Your plan includes single sign-on again, but ${connection.displayName} couldn't be turned back on automatically.`,
+              "Open its settings, check the domains and run a test sign-in, then activate it.",
+            ],
+            idempotencyKey: `sso-drafted:${connection.id}:${now.getTime()}`,
+          },
+          clock,
+        );
+        result.drafted += 1;
+        continue;
+      }
+      let restored = false;
+      try {
+        const changed = await db
+          .update(schema.schoolSsoConnections)
+          .set({ status: "active", updatedAt: now })
+          .where(
+            and(
+              eq(schema.schoolSsoConnections.id, connection.id),
+              eq(schema.schoolSsoConnections.status, "suspended"),
+            ),
+          )
+          .returning({ id: schema.schoolSsoConnections.id });
+        restored = Boolean(changed[0]);
+      } catch {
+        // Another connection of this school became active while this one was
+        // suspended; only one can be.
+        await db
+          .update(schema.schoolSsoConnections)
+          .set({ status: "draft", updatedAt: now })
+          .where(eq(schema.schoolSsoConnections.id, connection.id));
+        result.drafted += 1;
+        continue;
+      }
+      if (!restored) continue;
+      if (connection.enforcement === "required_for_domains") {
+        await endNonSsoSessionsForEnforcedDomains(db, connection.id);
+      }
+      await recordSsoEvent(
+        db,
+        { schoolId, connectionId: connection.id, action: "connection.restored" },
+        clock,
+      );
+      await notifySsoOwner(
+        db,
+        {
+          schoolId,
+          subject: "Single sign-on is back on",
+          lines: [`Single sign-on (${connection.displayName}) was turned back on because your plan includes it again.`],
+          idempotencyKey: `sso-restored:${connection.id}:${now.getTime()}`,
+        },
+        clock,
+      );
+      result.restored += 1;
+    }
+  }
+  return result;
+}
+
+/** Schools that have an active or suspended connection, for the daily sweep. */
+export async function schoolsWithSsoConnections(db: AppDb): Promise<string[]> {
+  const rows = await db
+    .selectDistinct({ schoolId: schema.schoolSsoConnections.schoolId })
+    .from(schema.schoolSsoConnections)
+    .where(inArray(schema.schoolSsoConnections.status, ["active", "suspended"]));
+  return rows.map((row) => row.schoolId);
+}
diff --git a/apps/api/src/school-emails.test.ts b/apps/api/src/school-emails.test.ts
index 1eb8f25e5..ed1aeffad 100644
--- a/apps/api/src/school-emails.test.ts
+++ b/apps/api/src/school-emails.test.ts
@@ -311,6 +311,7 @@ describe("space post notifications", () => {
         schoolPublicId: world.schoolA.publicId,
         learnerId: account.id,
         learnerPublicId: account.publicId,
+        authenticationMethod: "email" as const,
       });
     }
     expect(
diff --git a/apps/api/src/schools.ts b/apps/api/src/schools.ts
index 0fb4b75f6..0b2a8ceb5 100644
--- a/apps/api/src/schools.ts
+++ b/apps/api/src/schools.ts
@@ -134,6 +134,7 @@ export async function createSchool(
     status: "active" as const,
     locale: input.locale,
     currency: input.currency,
+    loginMethods: ["email" as const],
     paymentSettingsEncrypted: null,
     codeInjectionHead: "",
     codeInjectionBody: "",
diff --git a/apps/api/src/shadow-users.ts b/apps/api/src/shadow-users.ts
new file mode 100644
index 000000000..15b057e59
--- /dev/null
+++ b/apps/api/src/shadow-users.ts
@@ -0,0 +1,105 @@
+import { type Clock, uuidv7 } from "@codelitdev/platform";
+import { eq, sql } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import type { AppDb } from "./types.js";
+
+/**
+ * Shadow users own SSO-created school accounts, because
+ * `school_accounts.user_id` must point at a platform `user`. They can never
+ * sign in: no password, no `account` rows, an unreachable address, and
+ * Better Auth refuses to start a session for anyone listed in
+ * `sso_shadow_users`.
+ */
+
+export const SHADOW_USER_EMAIL_DOMAIN = "users.invalid";
+
+/** Whether an address is in the reserved domain shadow users live under. */
+export function isShadowUserEmail(email: string): boolean {
+  return email.trim().toLowerCase().endsWith(`@${SHADOW_USER_EMAIL_DOMAIN}`);
+}
+
+export async function isShadowUser(db: AppDb, userId: string): Promise<boolean> {
+  const [row] = await db
+    .select({ userId: schema.ssoShadowUsers.userId })
+    .from(schema.ssoShadowUsers)
+    .where(eq(schema.ssoShadowUsers.userId, userId))
+    .limit(1);
+  return Boolean(row);
+}
+
+/**
+ * Create a shadow user for one school. Call it inside the transaction that
+ * also creates the school account, so a failed insert leaves no user behind.
+ */
+export async function createShadowUser(
+  db: AppDb,
+  input: { schoolId: string; name: string },
+  clock: Clock,
+): Promise<typeof schema.user.$inferSelect> {
+  const now = clock.now();
+  const id = uuidv7(clock);
+  const [created] = await db
+    .insert(schema.user)
+    .values({
+      id,
+      name: input.name.trim().slice(0, 200) || "Learner",
+      email: `sso-${uuidv7(clock)}@${SHADOW_USER_EMAIL_DOMAIN}`,
+      emailVerified: false,
+      createdAt: now,
+      updatedAt: now,
+    })
+    .returning();
+  await db.insert(schema.ssoShadowUsers).values({
+    userId: id,
+    schoolId: input.schoolId,
+    createdAt: now,
+  });
+  return created!;
+}
+
+/**
+ * Delete a shadow user once it owns no school account, so personal data isn't
+ * left behind. A user that isn't a shadow user is never touched.
+ */
+export async function deleteShadowUserIfOrphaned(
+  db: AppDb,
+  userId: string,
+): Promise<boolean> {
+  const deleted = await db.execute(sql`
+    DELETE FROM "user"
+    WHERE id = ${userId}
+      AND EXISTS (SELECT 1 FROM sso_shadow_users WHERE user_id = ${userId})
+      AND NOT EXISTS (SELECT 1 FROM school_accounts WHERE user_id = ${userId})
+    RETURNING id
+  `);
+  const rows = (deleted as { rows?: unknown[] }).rows ?? [];
+  return rows.length > 0;
+}
+
+/**
+ * A school account that an SSO identity is linked to, or that belongs to a
+ * shadow user, matched by user or by email. Such accounts are the IdP's to
+ * sign in as, so they can never be invited to, accept, or be granted a place
+ * on the school's team. Unlinking the identity is the only way back.
+ */
+export async function findSsoBackedAccount(
+  db: AppDb,
+  input: { schoolId: string; userId?: string | null; email?: string | null },
+): Promise<{ id: string } | null> {
+  const matches = [];
+  if (input.userId) matches.push(sql`sa.user_id = ${input.userId}`);
+  if (input.email) matches.push(sql`sa.email = ${input.email.trim().toLowerCase()}`);
+  if (matches.length === 0) return null;
+  const found = await db.execute(sql`
+    SELECT sa.id FROM school_accounts sa
+    WHERE sa.school_id = ${input.schoolId}
+      AND (${sql.join(matches, sql` OR `)})
+      AND (
+        EXISTS (SELECT 1 FROM school_sso_identities i WHERE i.school_account_id = sa.id)
+        OR EXISTS (SELECT 1 FROM sso_shadow_users s WHERE s.user_id = sa.user_id)
+      )
+    LIMIT 1
+  `);
+  const rows = ((found as unknown) as { rows?: { id: string }[] }).rows ?? [];
+  return rows[0] ?? null;
+}
diff --git a/apps/api/src/sign-in-policy.test.ts b/apps/api/src/sign-in-policy.test.ts
new file mode 100644
index 000000000..bcb9bfeeb
--- /dev/null
+++ b/apps/api/src/sign-in-policy.test.ts
@@ -0,0 +1,366 @@
+import { describe, expect, it } from "bun:test";
+import { eq } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import {
+  finishLearnerGoogleSignIn,
+  requestLearnerEmailCode,
+  startLearnerGoogleSignIn,
+} from "./learner-sign-in.js";
+import { authenticateLearner, issueSchoolSession } from "./learners.js";
+import { createPgliteRuntime, freezeRuntimeClock } from "./runtime.js";
+import { seedWorld } from "./seed.js";
+import {
+  endNonSsoSessionsForEnforcedDomains,
+  endSessionsForMethod,
+  sessionMethodAllowed,
+} from "./sign-in-policy.js";
+import { learnerCookie, seedRealLearner, seedSsoConnection } from "./test-sso.js";
+import { linkSsoIdentity } from "./learner-sso.js";
+
+async function setup() {
+  const clock = freezeRuntimeClock(new Date("2026-03-01T00:00:00.000Z"));
+  const runtime = await createPgliteRuntime({ clock });
+  const world = await seedWorld(runtime, clock);
+  const school = async () =>
+    (
+      await runtime.db.select().from(schema.schools).where(eq(schema.schools.id, world.schoolA.id))
+    )[0]!;
+  const setMethods = (loginMethods: ("email" | "google")[]) =>
+    runtime.db
+      .update(schema.schools)
+      .set({ loginMethods })
+      .where(eq(schema.schools.id, world.schoolA.id));
+  const allowed = async (method: "email" | "google" | "sso", email?: string) =>
+    sessionMethodAllowed(runtime.db, { school: await school(), method, email });
+  return { clock, runtime, world, school, setMethods, allowed };
+}
+
+async function withGoogleKeys<T>(on: boolean, fn: () => Promise<T>): Promise<T> {
+  const saved = {
+    id: process.env.GOOGLE_CLIENT_ID,
+    secret: process.env.GOOGLE_CLIENT_SECRET,
+  };
+  if (on) {
+    process.env.GOOGLE_CLIENT_ID = "id";
+    process.env.GOOGLE_CLIENT_SECRET = "secret";
+  } else {
+    delete process.env.GOOGLE_CLIENT_ID;
+    delete process.env.GOOGLE_CLIENT_SECRET;
+  }
+  try {
+    return await fn();
+  } finally {
+    if (saved.id === undefined) delete process.env.GOOGLE_CLIENT_ID;
+    else process.env.GOOGLE_CLIENT_ID = saved.id;
+    if (saved.secret === undefined) delete process.env.GOOGLE_CLIENT_SECRET;
+    else process.env.GOOGLE_CLIENT_SECRET = saved.secret;
+  }
+}
+
+describe.serial("sign-in methods", () => {
+  it("defaults to email only and refuses methods that are off", async () => {
+    const { runtime, allowed } = await setup();
+    await withGoogleKeys(true, async () => {
+      expect((await allowed("email")).allowed).toBe(true);
+      expect(await allowed("google")).toEqual({ allowed: false, reason: "sign_in_method_disabled" });
+      expect(await allowed("sso")).toEqual({ allowed: false, reason: "sign_in_method_disabled" });
+    });
+    await runtime.close();
+  });
+
+  it("turns google on only with school opt-in and platform keys", async () => {
+    const { runtime, setMethods, allowed } = await setup();
+    await setMethods(["email", "google"]);
+    await withGoogleKeys(true, async () => expect((await allowed("google")).allowed).toBe(true));
+    await withGoogleKeys(false, async () => expect((await allowed("google")).allowed).toBe(false));
+    await runtime.close();
+  });
+
+  it("is on for SSO exactly when the school has an active connection", async () => {
+    const { runtime, world, clock, allowed } = await setup();
+    const connection = await seedSsoConnection(runtime.db, clock, {
+      schoolId: world.schoolA.id,
+      status: "draft",
+    });
+    expect((await allowed("sso")).allowed).toBe(false);
+    for (const [status, expected] of [
+      ["active", true],
+      ["suspended", false],
+      ["disabled", false],
+    ] as const) {
+      await runtime.db
+        .update(schema.schoolSsoConnections)
+        .set({ status })
+        .where(eq(schema.schoolSsoConnections.id, connection.id));
+      expect((await allowed("sso")).allowed).toBe(expected);
+    }
+    await runtime.close();
+  });
+
+  it("falls back to email when every method that is on is unusable", async () => {
+    const { runtime, world, clock, setMethods, allowed } = await setup();
+    await setMethods(["google"]);
+    await withGoogleKeys(false, async () => {
+      expect((await allowed("email")).allowed).toBe(true);
+      expect((await allowed("google")).allowed).toBe(false);
+    });
+    // Google works, so email stays off.
+    await withGoogleKeys(true, async () => {
+      expect((await allowed("google")).allowed).toBe(true);
+      expect((await allowed("email")).allowed).toBe(false);
+    });
+    // SSO is the only method on and its connection is suspended: email again.
+    await setMethods([]);
+    const connection = await seedSsoConnection(runtime.db, clock, { schoolId: world.schoolA.id });
+    await withGoogleKeys(false, async () => {
+      expect((await allowed("email")).allowed).toBe(false);
+      await runtime.db
+        .update(schema.schoolSsoConnections)
+        .set({ status: "suspended" })
+        .where(eq(schema.schoolSsoConnections.id, connection.id));
+      expect((await allowed("email")).allowed).toBe(true);
+    });
+    await runtime.close();
+  });
+
+  it("the database refuses unknown login methods", async () => {
+    const { runtime, world } = await setup();
+    await expect(
+      (async () => {
+        await runtime.db
+          .update(schema.schools)
+          .set({ loginMethods: ["email", "sso"] as never })
+          .where(eq(schema.schools.id, world.schoolA.id));
+      })(),
+    ).rejects.toThrow();
+    await runtime.close();
+  });
+
+  it("is enforced at every start endpoint and in issueSchoolSession", async () => {
+    const { runtime, world, clock, setMethods, school } = await setup();
+    await withGoogleKeys(true, async () => {
+      // Email off (google on), so the email code is refused before anything is sent.
+      await setMethods(["google"]);
+      const sent: string[] = [];
+      const code = await requestLearnerEmailCode(
+        runtime.db,
+        { schoolPublicId: world.schoolA.publicId, email: "x@example.com" },
+        clock,
+        async ({ email }) => void sent.push(email),
+      );
+      expect(code.ok).toBe(false);
+      expect(sent).toHaveLength(0);
+      expect(
+        !code.ok && (code.error as { safeDetails?: { reason?: string } }).safeDetails?.reason,
+      ).toBe("sign_in_method_disabled");
+
+      // Google off: the start endpoint refuses.
+      await setMethods(["email"]);
+      const start = await startLearnerGoogleSignIn(
+        runtime.db,
+        {
+          schoolPublicId: world.schoolA.publicId,
+          host: "school-a.localhost:3001",
+          nonce: "n".repeat(43),
+          publicApiUrl: "http://api.localhost:4000",
+        },
+        clock,
+      );
+      expect(start.ok).toBe(false);
+
+      // issueSchoolSession is the backstop for any other path.
+      const learner = await seedRealLearner(runtime.db, clock, world.schoolA.publicId, "pat@example.com");
+      await setMethods(["google"]);
+      const issued = await issueSchoolSession(runtime.db, {
+        school: await school(),
+        schoolAccount: learner.session.schoolAccount,
+        userId: learner.user.id,
+        authenticationMethod: "email",
+        clock,
+      });
+      expect(issued.ok).toBe(false);
+    });
+    await runtime.close();
+  });
+
+  it("turning a method off deletes that school's sessions made with it", async () => {
+    const { runtime, world, clock } = await setup();
+    const a = await seedRealLearner(runtime.db, clock, world.schoolA.publicId, "a@example.com");
+    const b = await seedRealLearner(runtime.db, clock, world.schoolB.publicId, "b@example.com");
+    expect(await endSessionsForMethod(runtime.db, world.schoolA.id, "email")).toBe(1);
+    expect((await authenticateLearner(runtime.db, learnerCookie(a.token), clock)).kind).toBe("rejected");
+    expect((await authenticateLearner(runtime.db, learnerCookie(b.token), clock)).kind).toBe(
+      "authenticated",
+    );
+    await runtime.close();
+  });
+
+  it("existing sessions stop working when their method is switched off", async () => {
+    const { runtime, world, clock, setMethods } = await setup();
+    const a = await seedRealLearner(runtime.db, clock, world.schoolA.publicId, "a@example.com");
+    expect((await authenticateLearner(runtime.db, learnerCookie(a.token), clock)).kind).toBe(
+      "authenticated",
+    );
+    await withGoogleKeys(true, async () => {
+      await setMethods(["google"]);
+      expect((await authenticateLearner(runtime.db, learnerCookie(a.token), clock)).kind).toBe(
+        "rejected",
+      );
+    });
+    await runtime.close();
+  });
+});
+
+describe.serial("sso enforcement", () => {
+  async function enforced() {
+    const ctx = await setup();
+    const connection = await seedSsoConnection(ctx.runtime.db, ctx.clock, {
+      schoolId: ctx.world.schoolA.id,
+      enforcement: "required_for_domains",
+      domains: ["acme.com"],
+      unverifiedDomains: ["pending.com"],
+    });
+    return { ...ctx, connection };
+  }
+
+  it("allows only sso for addresses in verified domains of an enforcing active connection", async () => {
+    const { runtime, allowed, connection } = await enforced();
+    expect(await allowed("email", "x@acme.com")).toEqual({ allowed: false, reason: "sso_required" });
+    expect(await allowed("google", "x@acme.com")).toEqual({ allowed: false, reason: "sso_required" });
+    expect((await allowed("sso", "x@acme.com")).allowed).toBe(true);
+    // Other domains, unverified domains and subdomains aren't affected.
+    expect((await allowed("email", "x@other.org")).allowed).toBe(true);
+    expect((await allowed("email", "x@pending.com")).allowed).toBe(true);
+    expect((await allowed("email", "x@sub.acme.com")).allowed).toBe(true);
+    // Not enforced when optional, or when the connection isn't active.
+    await runtime.db
+      .update(schema.schoolSsoConnections)
+      .set({ enforcement: "optional" })
+      .where(eq(schema.schoolSsoConnections.id, connection.id));
+    expect((await allowed("email", "x@acme.com")).allowed).toBe(true);
+    await runtime.db
+      .update(schema.schoolSsoConnections)
+      .set({ enforcement: "required_for_domains", status: "suspended" })
+      .where(eq(schema.schoolSsoConnections.id, connection.id));
+    expect((await allowed("email", "x@acme.com")).allowed).toBe(true);
+    await runtime.close();
+  });
+
+  it("refuses email codes and google sign-in for enforced domains", async () => {
+    const { runtime, world, clock, setMethods } = await enforced();
+    await setMethods(["email", "google"]);
+    await withGoogleKeys(true, async () => {
+      const sent: string[] = [];
+      const code = await requestLearnerEmailCode(
+        runtime.db,
+        { schoolPublicId: world.schoolA.publicId, email: "Zed@Acme.com" },
+        clock,
+        async ({ email }) => void sent.push(email),
+      );
+      expect(!code.ok && (code.error as { safeDetails?: { reason?: string } }).safeDetails?.reason).toBe(
+        "sso_required",
+      );
+      expect(sent).toHaveLength(0);
+      const ok = await requestLearnerEmailCode(
+        runtime.db,
+        { schoolPublicId: world.schoolA.publicId, email: "zed@other.org" },
+        clock,
+        async ({ email }) => void sent.push(email),
+      );
+      expect(ok.ok).toBe(true);
+
+      // Google: the address is only known on return, before admitting.
+      const start = await startLearnerGoogleSignIn(
+        runtime.db,
+        {
+          schoolPublicId: world.schoolA.publicId,
+          host: "school-a.localhost:3001",
+          nonce: "n".repeat(43),
+          publicApiUrl: "http://api.localhost:4000",
+        },
+        clock,
+      );
+      expect(start.ok).toBe(true);
+      const token = new URL((start as { value: { url: string } }).value.url).searchParams.get("request")!;
+      const accountsBefore = await runtime.db.select().from(schema.schoolAccounts);
+      const finished = await finishLearnerGoogleSignIn(
+        runtime.db,
+        { requestToken: token, user: { id: world.member.id, email: "zed@acme.com", name: "Zed" } },
+        clock,
+      );
+      expect(finished.ok).toBe(false);
+      expect(await runtime.db.select().from(schema.schoolAccounts)).toHaveLength(accountsBefore.length);
+    });
+    await runtime.close();
+  });
+
+  it("refuses email sessions in issueSchoolSession and authenticateLearner for enforced domains", async () => {
+    const { runtime, world, clock, school, connection } = await enforced();
+    // A session that predates enforcement.
+    await runtime.db
+      .update(schema.schoolSsoConnections)
+      .set({ enforcement: "optional" })
+      .where(eq(schema.schoolSsoConnections.id, connection.id));
+    const learner = await seedRealLearner(runtime.db, clock, world.schoolA.publicId, "old@acme.com");
+    expect((await authenticateLearner(runtime.db, learnerCookie(learner.token), clock)).kind).toBe(
+      "authenticated",
+    );
+    await runtime.db
+      .update(schema.schoolSsoConnections)
+      .set({ enforcement: "required_for_domains" })
+      .where(eq(schema.schoolSsoConnections.id, connection.id));
+    expect((await authenticateLearner(runtime.db, learnerCookie(learner.token), clock)).kind).toBe(
+      "rejected",
+    );
+    const issued = await issueSchoolSession(runtime.db, {
+      school: await school(),
+      schoolAccount: learner.session.schoolAccount,
+      userId: learner.user.id,
+      authenticationMethod: "email",
+      clock,
+    });
+    expect(!issued.ok && (issued.error as { safeDetails?: { reason?: string } }).safeDetails?.reason).toBe(
+      "sso_required",
+    );
+    await runtime.close();
+  });
+
+  it("turning enforcement on deletes existing non-sso sessions in enforced domains only", async () => {
+    const { runtime, world, clock, connection } = await enforced();
+    // Sessions that predate enforcement.
+    await runtime.db
+      .update(schema.schoolSsoConnections)
+      .set({ enforcement: "optional" })
+      .where(eq(schema.schoolSsoConnections.id, connection.id));
+    const inDomain = await seedRealLearner(runtime.db, clock, world.schoolA.publicId, "in@acme.com");
+    const outside = await seedRealLearner(runtime.db, clock, world.schoolA.publicId, "out@other.org");
+    const otherSchool = await seedRealLearner(runtime.db, clock, world.schoolB.publicId, "in@acme.com");
+    const sso = await linkSsoIdentity(
+      runtime.db,
+      { connection, issuer: connection.idpEntityId!, subject: "s", email: "sso@acme.com" },
+      clock,
+    );
+    if (!sso.ok) throw new Error();
+    const [school] = await runtime.db.select().from(schema.schools).where(eq(schema.schools.id, world.schoolA.id));
+    const ssoIssued = await issueSchoolSession(runtime.db, {
+      school: school!,
+      schoolAccount: sso.value,
+      userId: sso.value.userId,
+      authenticationMethod: "sso",
+      ssoConnectionId: connection.id,
+      clock,
+    });
+    if (!ssoIssued.ok) throw new Error();
+    await runtime.db
+      .update(schema.schoolSsoConnections)
+      .set({ enforcement: "required_for_domains" })
+      .where(eq(schema.schoolSsoConnections.id, connection.id));
+    expect(await endNonSsoSessionsForEnforcedDomains(runtime.db, connection.id)).toBe(1);
+    const left = (await runtime.db.select().from(schema.schoolSessions)).map((row) => row.id);
+    expect(left).not.toContain(inDomain.session.sessionId);
+    expect(left).toContain(outside.session.sessionId);
+    expect(left).toContain(otherSchool.session.sessionId);
+    expect(left).toContain(ssoIssued.value.session.sessionId);
+    await runtime.close();
+  });
+});
diff --git a/apps/api/src/sign-in-policy.ts b/apps/api/src/sign-in-policy.ts
new file mode 100644
index 000000000..ad5bbf4fb
--- /dev/null
+++ b/apps/api/src/sign-in-policy.ts
@@ -0,0 +1,195 @@
+import { and, eq, inArray, isNotNull, ne } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { emailDomainOf } from "./sso-email.js";
+import type { AppDb } from "./types.js";
+
+export type SignInMethod = "email" | "google" | "sso";
+export type SignInPolicyDenial = "sso_required" | "sign_in_method_disabled";
+export type SignInPolicyResult =
+  | { allowed: true }
+  | { allowed: false; reason: SignInPolicyDenial };
+
+/** Whether the platform has Google keys at all. */
+export function platformGoogleAvailable(): boolean {
+  return Boolean(process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET);
+}
+
+type SchoolForPolicy = Pick<typeof schema.schools.$inferSelect, "id" | "loginMethods">;
+
+/** The school's active SSO connection, if any. */
+export async function activeSsoConnection(db: AppDb, schoolId: string) {
+  const [connection] = await db
+    .select()
+    .from(schema.schoolSsoConnections)
+    .where(
+      and(
+        eq(schema.schoolSsoConnections.schoolId, schoolId),
+        eq(schema.schoolSsoConnections.status, "active"),
+      ),
+    )
+    .limit(1);
+  return connection ?? null;
+}
+
+/** Whether an email's domain is a verified domain of this connection. */
+export async function isVerifiedSsoDomainEmail(
+  db: AppDb,
+  connectionId: string,
+  email: string,
+): Promise<boolean> {
+  const domain = emailDomainOf(email);
+  if (!domain) return false;
+  const [row] = await db
+    .select({ id: schema.schoolSsoDomains.id })
+    .from(schema.schoolSsoDomains)
+    .where(
+      and(
+        eq(schema.schoolSsoDomains.connectionId, connectionId),
+        eq(schema.schoolSsoDomains.domain, domain),
+        isNotNull(schema.schoolSsoDomains.verifiedAt),
+      ),
+    )
+    .limit(1);
+  return Boolean(row);
+}
+
+/**
+ * Whether a school may sign someone in, or keep them signed in, with a
+ * method. This is the one policy check; the start endpoints call it early and
+ * `issueSchoolSession` calls it again, so no path is missed.
+ *
+ * - A method is on when the school turned it on (`login_methods`), or, for
+ *   SSO, exactly when it has an active connection.
+ * - If every method the school has on is unusable (Google without platform
+ *   keys, SSO not active), email codes are allowed so no learner is locked
+ *   out by something the school didn't choose.
+ * - When the active connection requires SSO for its verified domains, an
+ *   address in one of them can only sign in with SSO. Pass `email` whenever
+ *   it is known; Google's start endpoint can't know it yet.
+ */
+export async function sessionMethodAllowed(
+  db: AppDb,
+  input: {
+    school: SchoolForPolicy;
+    email?: string | null;
+    method: SignInMethod;
+    /** For `sso`: the connection the session belongs to. */
+    ssoConnectionId?: string | null;
+  },
+): Promise<SignInPolicyResult> {
+  const connection = await activeSsoConnection(db, input.school.id);
+  if (input.method === "sso") {
+    const ok =
+      Boolean(connection) &&
+      (!input.ssoConnectionId || connection!.id === input.ssoConnectionId);
+    return ok ? { allowed: true } : { allowed: false, reason: "sign_in_method_disabled" };
+  }
+  if (
+    connection &&
+    connection.enforcement === "required_for_domains" &&
+    input.email &&
+    (await isVerifiedSsoDomainEmail(db, connection.id, input.email))
+  ) {
+    return { allowed: false, reason: "sso_required" };
+  }
+  const usable = new Set<SignInMethod>();
+  for (const method of input.school.loginMethods) {
+    if (method === "email") usable.add("email");
+    if (method === "google" && platformGoogleAvailable()) usable.add("google");
+  }
+  if (connection) usable.add("sso");
+  if (usable.size === 0) usable.add("email");
+  return usable.has(input.method)
+    ? { allowed: true }
+    : { allowed: false, reason: "sign_in_method_disabled" };
+}
+
+/**
+ * The methods a school's learners can use right now, as the storefront shows
+ * them: what the policy would allow for an address with no enforcement.
+ */
+export async function usableSignInMethods(
+  db: AppDb,
+  school: SchoolForPolicy,
+): Promise<SignInMethod[]> {
+  const methods: SignInMethod[] = [];
+  for (const method of ["email", "google", "sso"] as const) {
+    const result = await sessionMethodAllowed(db, { school, method });
+    if (result.allowed) methods.push(method);
+  }
+  return methods;
+}
+
+/** End every session a school's learners hold that was created with a method. */
+export async function endSessionsForMethod(
+  db: AppDb,
+  schoolId: string,
+  method: SignInMethod,
+): Promise<number> {
+  const deleted = await db
+    .delete(schema.schoolSessions)
+    .where(
+      and(
+        eq(schema.schoolSessions.schoolId, schoolId),
+        eq(schema.schoolSessions.authenticationMethod, method),
+      ),
+    )
+    .returning({ id: schema.schoolSessions.id });
+  return deleted.length;
+}
+
+/**
+ * Turning enforcement on: end the non-SSO sessions of accounts whose email is
+ * in one of the connection's verified domains. Otherwise people removed from
+ * the IdP would keep their access until their sessions expire.
+ */
+export async function endNonSsoSessionsForEnforcedDomains(
+  db: AppDb,
+  connectionId: string,
+): Promise<number> {
+  const [connection] = await db
+    .select({ schoolId: schema.schoolSsoConnections.schoolId })
+    .from(schema.schoolSsoConnections)
+    .where(eq(schema.schoolSsoConnections.id, connectionId))
+    .limit(1);
+  if (!connection) return 0;
+  const domainRows = await db
+    .select({ domain: schema.schoolSsoDomains.domain })
+    .from(schema.schoolSsoDomains)
+    .where(
+      and(
+        eq(schema.schoolSsoDomains.connectionId, connectionId),
+        isNotNull(schema.schoolSsoDomains.verifiedAt),
+      ),
+    );
+  const domains = new Set(domainRows.map((row) => row.domain));
+  if (domains.size === 0) return 0;
+  const sessions = await db
+    .select({
+      id: schema.schoolSessions.id,
+      email: schema.schoolAccounts.email,
+    })
+    .from(schema.schoolSessions)
+    .innerJoin(
+      schema.schoolAccounts,
+      eq(schema.schoolAccounts.id, schema.schoolSessions.schoolAccountId),
+    )
+    .where(
+      and(
+        eq(schema.schoolSessions.schoolId, connection.schoolId),
+        ne(schema.schoolSessions.authenticationMethod, "sso"),
+      ),
+    );
+  const ids = sessions
+    .filter((row) => {
+      const domain = emailDomainOf(row.email);
+      return domain !== null && domains.has(domain);
+    })
+    .map((row) => row.id);
+  if (ids.length === 0) return 0;
+  const deleted = await db
+    .delete(schema.schoolSessions)
+    .where(inArray(schema.schoolSessions.id, ids))
+    .returning({ id: schema.schoolSessions.id });
+  return deleted.length;
+}
diff --git a/apps/api/src/space-access.ts b/apps/api/src/space-access.ts
index 9c769e26a..6fd734724 100644
--- a/apps/api/src/space-access.ts
+++ b/apps/api/src/space-access.ts
@@ -1,6 +1,7 @@
 import { and, eq, inArray, isNotNull, isNull } from "drizzle-orm";
 import * as schema from "./db/schema/index.js";
 import { parsePermissions } from "./permissions.js";
+import type { SignInMethod } from "./sign-in-policy.js";
 import type { AppDb } from "./types.js";
 
 /**
@@ -51,7 +52,10 @@ export async function staffSpaceIds(
   db: AppDb,
   schoolId: string,
   schoolAccountId: string,
+  authenticationMethod: SignInMethod,
 ): Promise<Set<string>> {
+  // An SSO session never carries team powers, whatever the account holds.
+  if (authenticationMethod === "sso") return new Set();
   const [staff] = await db
     .select({
       isOwner: schema.memberships.isOwner,
@@ -98,8 +102,15 @@ export async function moderatesSpace(
   schoolId: string,
   schoolAccountId: string,
   spaceId: string,
+  authenticationMethod: SignInMethod,
 ): Promise<boolean> {
-  if ((await staffSpaceIds(db, schoolId, schoolAccountId)).has(spaceId)) return true;
+  if (
+    (await staffSpaceIds(db, schoolId, schoolAccountId, authenticationMethod)).has(
+      spaceId,
+    )
+  ) {
+    return true;
+  }
   const ownership = await spaceOwnership(db, schoolId);
   if (ownership.productSpaces.has(spaceId)) return false;
   const [moderator] = await db
@@ -132,10 +143,11 @@ export async function accessibleSpaceIds(
   db: AppDb,
   schoolId: string,
   schoolAccountId: string,
+  authenticationMethod: SignInMethod,
 ): Promise<Set<string>> {
   const [learner, staff] = await Promise.all([
     learnerSpaceIds(db, schoolId, schoolAccountId),
-    staffSpaceIds(db, schoolId, schoolAccountId),
+    staffSpaceIds(db, schoolId, schoolAccountId, authenticationMethod),
   ]);
   for (const id of staff) learner.add(id);
   return learner;
diff --git a/apps/api/src/spaces.ts b/apps/api/src/spaces.ts
index b224aaddb..7891e8c0e 100644
--- a/apps/api/src/spaces.ts
+++ b/apps/api/src/spaces.ts
@@ -661,7 +661,7 @@ export async function listLearnerSpaces(
   db: AppDb,
   viewer: CommunityLearnerViewer,
 ): Promise<Result<{ items: SpaceDto[] }>> {
-  const accessible = await accessibleSpaceIds(db, viewer.schoolId, viewer.learnerId);
+  const accessible = await accessibleSpaceIds(db, viewer.schoolId, viewer.learnerId, viewer.authenticationMethod);
   if (accessible.size === 0) return { ok: true, value: { items: [] } };
   const rows = await db
     .select()
@@ -703,7 +703,7 @@ export async function listLearnerSpaces(
   const communityMembership = memberships.find(
     (membership) => membership.entityType === "community",
   );
-  const staff = await staffSpaceIds(db, viewer.schoolId, viewer.learnerId);
+  const staff = await staffSpaceIds(db, viewer.schoolId, viewer.learnerId, viewer.authenticationMethod);
   const onlyComment =
     communityMembership?.role === "comment" &&
     memberships.every(
@@ -736,7 +736,7 @@ export async function followSpace(
 ): Promise<Result<{ followed: true }>> {
   const row = await loadSpace(db, viewer.schoolId, spacePublicId);
   if (!row) return notFound();
-  const accessible = await accessibleSpaceIds(db, viewer.schoolId, viewer.learnerId);
+  const accessible = await accessibleSpaceIds(db, viewer.schoolId, viewer.learnerId, viewer.authenticationMethod);
   if (!accessible.has(row.id)) return notFound();
   const existing = await db
     .select({ id: schema.spaceFollowers.id })
@@ -767,7 +767,7 @@ export async function unfollowSpace(
 ): Promise<Result<{ followed: false }>> {
   const row = await loadSpace(db, viewer.schoolId, spacePublicId);
   if (!row) return notFound();
-  const accessible = await accessibleSpaceIds(db, viewer.schoolId, viewer.learnerId);
+  const accessible = await accessibleSpaceIds(db, viewer.schoolId, viewer.learnerId, viewer.authenticationMethod);
   if (!accessible.has(row.id)) return notFound();
   await db
     .delete(schema.spaceFollowers)
@@ -794,7 +794,7 @@ export async function createLearnerSpacePost(
 ): Promise<Result<{ id: string; spaceId: string; title: string; content: string }>> {
   const space = await loadSpace(db, viewer.schoolId, spacePublicId);
   if (!space) return notFound();
-  const accessible = await accessibleSpaceIds(db, viewer.schoolId, viewer.learnerId);
+  const accessible = await accessibleSpaceIds(db, viewer.schoolId, viewer.learnerId, viewer.authenticationMethod);
   if (!accessible.has(space.id)) return notFound();
   const memberships = await db
     .select()
@@ -810,7 +810,7 @@ export async function createLearnerSpacePost(
   const onlyComment =
     communityMembership?.role === "comment" &&
     memberships.every((row) => row.entityType === "community" || row.isIncludedInPlan);
-  const staff = await staffSpaceIds(db, viewer.schoolId, viewer.learnerId);
+  const staff = await staffSpaceIds(db, viewer.schoolId, viewer.learnerId, viewer.authenticationMethod);
   // Team members may post wherever their role reaches them.
   if (!staff.has(space.id)) {
     if (space.whoCanPost === "admin") {
@@ -906,7 +906,7 @@ async function notifySpacePost(
   for (const { schoolAccountId } of followers) {
     if (schoolAccountId === viewer.learnerId) continue;
     // Following outlives access; only notify people who can still read it.
-    const accessible = await accessibleSpaceIds(db, viewer.schoolId, schoolAccountId);
+    const accessible = await accessibleSpaceIds(db, viewer.schoolId, schoolAccountId, viewer.authenticationMethod);
     if (!accessible.has(space.id)) continue;
     await createLearnerNotification(
       db,
@@ -964,7 +964,7 @@ export async function listLearnerSpaceFeed(
 > {
   const community = await schoolCommunity(db, viewer.schoolId);
   const banner = community?.banner ?? "";
-  const accessible = await accessibleSpaceIds(db, viewer.schoolId, viewer.learnerId);
+  const accessible = await accessibleSpaceIds(db, viewer.schoolId, viewer.learnerId, viewer.authenticationMethod);
   const cursorWhere = await feedCursorCondition(db, viewer.schoolId, options.cursor);
   if (options.spaceId) {
     const space = await loadSpace(db, viewer.schoolId, options.spaceId);
@@ -1036,7 +1036,7 @@ export async function getLearnerSpacePost(
 ): Promise<Result<LearnerSpaceFeedPostDto>> {
   const space = await loadSpace(db, viewer.schoolId, spacePublicId);
   if (!space) return notFound();
-  const accessible = await accessibleSpaceIds(db, viewer.schoolId, viewer.learnerId);
+  const accessible = await accessibleSpaceIds(db, viewer.schoolId, viewer.learnerId, viewer.authenticationMethod);
   if (!accessible.has(space.id)) return notFound();
   const rows = await db
     .select({ post: schema.communityPosts })
@@ -1054,7 +1054,7 @@ export async function getLearnerSpacePost(
   if (!post) return notFound();
   const [item] = await mapLearnerSpaceFeedPosts(db, viewer, [{ post, space }]);
   if (!item) return notFound();
-  const canModerate = await moderatesSpace(db, viewer.schoolId, viewer.learnerId, space.id);
+  const canModerate = await moderatesSpace(db, viewer.schoolId, viewer.learnerId, space.id, viewer.authenticationMethod);
   return { ok: true, value: { ...item, canModerate } };
 }
 
@@ -1089,7 +1089,7 @@ export async function createLearnerSpaceReport(
 ) {
   const space = await loadSpace(db, viewer.schoolId, spacePublicId);
   if (!space) return notFound();
-  const accessible = await accessibleSpaceIds(db, viewer.schoolId, viewer.learnerId);
+  const accessible = await accessibleSpaceIds(db, viewer.schoolId, viewer.learnerId, viewer.authenticationMethod);
   if (!accessible.has(space.id)) return notFound();
   const community = await schoolCommunity(db, viewer.schoolId);
   if (!community) return notFound();
diff --git a/apps/api/src/sso-admin-routes.ts b/apps/api/src/sso-admin-routes.ts
new file mode 100644
index 000000000..9e2d4c069
--- /dev/null
+++ b/apps/api/src/sso-admin-routes.ts
@@ -0,0 +1,150 @@
+import {
+  addSsoDomainBodySchema,
+  createSsoConnectionBodySchema,
+  startSsoConnectionTestBodySchema,
+  updateSchoolLoginMethodsBodySchema,
+  updateSsoConnectionBodySchema,
+} from "@courselit/api-contract";
+import { createPlatformError, toPublicHttpError } from "@codelitdev/platform";
+import type { DispatchDeps } from "./deps.js";
+import { readSchoolLoginMethods, updateSchoolLoginMethods } from "./login-methods.js";
+import type { ResolvedSchool } from "./school-context.js";
+import {
+  activateSsoConnection,
+  addSsoDomain,
+  createSsoConnection,
+  deleteSsoConnection,
+  deleteSsoDomain,
+  disableSsoConnection,
+  getSsoConnection,
+  getSsoConnectionTestResult,
+  listSsoConnections,
+  type SsoAdminContext,
+  startSsoConnectionTest,
+  unlinkSsoIdentity,
+  updateSsoConnection,
+  verifySsoDomain,
+} from "./sso-admin.js";
+import type { DispatchResponse, IncomingRequest } from "./types.js";
+
+type Outcome<T> = { ok: true; value: T } | { ok: false; error: ReturnType<typeof createPlatformError> };
+
+function respond<T>(result: Outcome<T>, status = 200): DispatchResponse {
+  if (!result.ok) {
+    const mapped = toPublicHttpError(result.error);
+    return { status: mapped.status, body: mapped.body };
+  }
+  return status === 204 ? { status, body: undefined } : { status, body: result.value };
+}
+
+const badRequest = (): DispatchResponse => {
+  const mapped = toPublicHttpError(createPlatformError("validation_failed"));
+  return { status: mapped.status, body: mapped.body };
+};
+
+/**
+ * The school-scoped single sign-on and sign-in-method operations. Credential
+ * kind, ownership, permissions and the recent-sign-in rule are decided by the
+ * operation policy before this runs; this only maps requests to the logic.
+ * Returns null when the request is not one of these operations.
+ */
+export async function handleSsoAdminRequest(
+  deps: DispatchDeps,
+  request: IncomingRequest,
+  path: string,
+  school: ResolvedSchool,
+): Promise<DispatchResponse | null> {
+  const ctx: SsoAdminContext = {
+    db: deps.db,
+    clock: deps.clock,
+    billing: deps.billing.billing,
+    publicApiUrl: deps.auth.publicApiUrl,
+    webOrigin: deps.auth.webOrigin,
+    dnsResolver: deps.dnsResolver,
+    schoolId: school.schoolId,
+    actorSchoolAccountId: school.schoolAccountId,
+  };
+  const method = request.method;
+  const body = request.body ?? {};
+
+  if (path === "/v1/school/login-methods") {
+    if (method === "GET") {
+      return respond(await readSchoolLoginMethods(deps.db, deps.billing.billing, school.schoolId));
+    }
+    if (method === "PATCH") {
+      const parsed = updateSchoolLoginMethodsBodySchema.safeParse(body);
+      if (!parsed.success) return badRequest();
+      return respond(
+        await updateSchoolLoginMethods(
+          deps.db,
+          deps.billing.billing,
+          school.schoolId,
+          parsed.data,
+          deps.clock,
+        ),
+      );
+    }
+    return null;
+  }
+
+  if (path === "/v1/sso/connections") {
+    if (method === "GET") return respond(await listSsoConnections(ctx));
+    if (method === "POST") {
+      const parsed = createSsoConnectionBodySchema.safeParse(body);
+      if (!parsed.success) return badRequest();
+      return respond(await createSsoConnection(ctx, parsed.data), 201);
+    }
+    return null;
+  }
+
+  const identity = /^\/v1\/sso\/identities\/([^/]+)$/.exec(path);
+  if (identity && method === "DELETE") {
+    return respond(await unlinkSsoIdentity(ctx, decodeURIComponent(identity[1]!)), 204);
+  }
+
+  const match = /^\/v1\/sso\/connections\/([^/]+)(?:\/(.*))?$/.exec(path);
+  if (!match) return null;
+  const connectionId = decodeURIComponent(match[1]!);
+  const rest = match[2] ?? "";
+
+  if (rest === "") {
+    if (method === "GET") return respond(await getSsoConnection(ctx, connectionId));
+    if (method === "PATCH") {
+      const parsed = updateSsoConnectionBodySchema.safeParse(body);
+      if (!parsed.success) return badRequest();
+      return respond(await updateSsoConnection(ctx, connectionId, parsed.data));
+    }
+    if (method === "DELETE") return respond(await deleteSsoConnection(ctx, connectionId), 204);
+    return null;
+  }
+  if (rest === "domains" && method === "POST") {
+    const parsed = addSsoDomainBodySchema.safeParse(body);
+    if (!parsed.success) return badRequest();
+    return respond(await addSsoDomain(ctx, connectionId, parsed.data), 201);
+  }
+  const domain = /^domains\/([^/]+)(\/verify)?$/.exec(rest);
+  if (domain) {
+    const name = decodeURIComponent(domain[1]!);
+    if (domain[2] && method === "POST") return respond(await verifySsoDomain(ctx, connectionId, name));
+    if (!domain[2] && method === "DELETE") {
+      return respond(await deleteSsoDomain(ctx, connectionId, name), 204);
+    }
+    return null;
+  }
+  if (rest === "test" && method === "POST") {
+    const parsed = startSsoConnectionTestBodySchema.safeParse(body);
+    if (!parsed.success) return badRequest();
+    return respond(await startSsoConnectionTest(ctx, connectionId, parsed.data));
+  }
+  const result = /^test-results\/([^/]+)$/.exec(rest);
+  if (result && method === "GET") {
+    return respond(await getSsoConnectionTestResult(ctx, connectionId, decodeURIComponent(result[1]!)));
+  }
+  if (rest === "activate" && method === "POST") {
+    return respond(await activateSsoConnection(ctx, connectionId));
+  }
+  if (rest === "disable" && method === "POST") {
+    return respond(await disableSsoConnection(ctx, connectionId));
+  }
+  return null;
+}
diff --git a/apps/api/src/sso-admin.test.ts b/apps/api/src/sso-admin.test.ts
new file mode 100644
index 000000000..93110c480
--- /dev/null
+++ b/apps/api/src/sso-admin.test.ts
@@ -0,0 +1,387 @@
+import { describe, expect, it } from "bun:test";
+import { eq } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { dispatch } from "./dispatch.js";
+import { idpKeys, rotatedKeys } from "./sso-protocol/test-idp.js";
+import { bareCertificate, ownerHeaders, ssoSetup, type SsoSetup } from "./test-sso-flow.js";
+import { seedRealLearner } from "./test-sso.js";
+
+const MD = "urn:oasis:names:tc:SAML:2.0:metadata";
+const metadata = (entity = "https://idp.example/entity", sso = "https://idp.example/sso", cert = idpKeys.cert) =>
+  `<?xml version="1.0"?><md:EntityDescriptor xmlns:md="${MD}" entityID="${entity}"><md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><md:KeyDescriptor use="signing"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>${bareCertificate(cert)}</ds:X509Certificate></ds:X509Data></ds:KeyInfo></md:KeyDescriptor><md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="${sso}"/></md:IDPSSODescriptor></md:EntityDescriptor>`;
+
+const call = (t: SsoSetup, method: string, path: string, body?: unknown, headers: Record<string, string> = ownerHeaders(t.world)) =>
+  dispatch(t.runtime, { method, path, headers, ...(body === undefined ? {} : { body }) });
+
+async function ssoSession(t: SsoSetup, email: string, method: "sso" | "email") {
+  const learner = await seedRealLearner(t.runtime.db, t.clock, t.world.schoolA.publicId, email);
+  if (method === "sso") {
+    await t.runtime.db
+      .update(schema.schoolSessions)
+      .set({ authenticationMethod: "sso", ssoConnectionId: t.connection.id })
+      .where(eq(schema.schoolSessions.id, learner.session.sessionId));
+  }
+  return learner;
+}
+const sessionCount = async (t: SsoSetup, method?: string) =>
+  (await t.runtime.db.select().from(schema.schoolSessions)).filter(
+    (row) => !method || row.authenticationMethod === method,
+  ).length;
+
+describe.serial("SSO management operations", () => {
+  it("refuses every write to API keys, OAuth clients, non-owners and stale sessions", async () => {
+    const t = await ssoSetup();
+    try {
+      const path = `/v1/sso/connections/${t.connection.publicId}`;
+      const writes: Array<[string, string, unknown]> = [
+        ["POST", "/v1/sso/connections", { displayName: "x", idpEntityId: "e" }],
+        ["PATCH", path, { displayName: "y" }],
+        ["POST", `${path}/domains`, { domain: "other.com" }],
+        ["POST", `${path}/domains/acme.com/verify`, {}],
+        ["DELETE", `${path}/domains/acme.com`, undefined],
+        ["POST", `${path}/test`, { returnUrl: `${t.runtime.auth.webOrigin}/x` }],
+        ["POST", `${path}/activate`, {}],
+        ["POST", `${path}/disable`, {}],
+        ["DELETE", path, undefined],
+        ["DELETE", "/v1/sso/identities/cnt_x", undefined],
+      ];
+      const credentials: Record<string, Record<string, string>> = {
+        apiKey: { "x-api-key": t.world.apiKeyA.raw, "x-school-id": t.world.schoolA.publicId },
+        oauth: { authorization: `Bearer ${t.world.owner.oauthToken}`, "x-school-id": t.world.schoolA.publicId },
+        member: { cookie: t.world.member.sessionCookie, "x-school-id": t.world.schoolA.publicId },
+      };
+      for (const [kind, headers] of Object.entries(credentials)) {
+        for (const [method, route, body] of writes) {
+          const response = await call(t, method, route, body, headers);
+          expect([kind, method, route, response.status]).toEqual([kind, method, route, 403]);
+        }
+      }
+      // The owner's session works, but not once it is no longer a recent sign-in.
+      await t.runtime.db
+        .update(schema.session)
+        .set({ createdAt: new Date(t.clock.now().getTime() - 60 * 60 * 1000) })
+        .where(eq(schema.session.userId, t.world.owner.id));
+      for (const [method, route, body] of writes) {
+        const response = await call(t, method, route, body);
+        expect(response.status).toBe(403);
+        expect(response.body).toMatchObject({ details: { reason: "recent_authentication_required" } });
+      }
+      const [still] = await t.runtime.db.select().from(schema.schoolSsoConnections);
+      expect(still!.displayName).toBe("Acme employees");
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("lets every credential read connections, and reads never carry secrets or test attributes", async () => {
+    const t = await ssoSetup();
+    try {
+      await t.runtime.db
+        .update(schema.schoolSsoConnections)
+        .set({ oidcClientSecret: "ENCRYPTED-SECRET", oidcClientId: "client" });
+      await t.runtime.db.insert(schema.schoolSsoRequests).values({
+        id: crypto.randomUUID(),
+        requestDigest: "d",
+        schoolId: t.world.schoolA.id,
+        connectionId: t.connection.id,
+        nonceDigest: "n",
+        returnOrigin: "http://x",
+        nextPath: "/",
+        purpose: "test",
+        testResult: { ok: true, email: "leak@acme.com", attributes: { secret: ["leak-me"] } },
+        testResultExpiresAt: new Date(t.clock.now().getTime() + 60_000),
+        expiresAt: new Date(t.clock.now().getTime() + 60_000),
+        createdAt: t.clock.now(),
+      });
+      for (const headers of [
+        ownerHeaders(t.world),
+        { authorization: `Bearer ${t.world.owner.oauthToken}`, "x-school-id": t.world.schoolA.publicId },
+      ]) {
+        const list = await call(t, "GET", "/v1/sso/connections", undefined, headers);
+        const one = await call(t, "GET", `/v1/sso/connections/${t.connection.publicId}`, undefined, headers);
+        expect([list.status, one.status]).toEqual([200, 200]);
+        const text = JSON.stringify([list.body, one.body]);
+        expect(text).not.toContain("ENCRYPTED-SECRET");
+        expect(text).not.toContain("leak");
+        expect(text.toLowerCase()).not.toContain("clientsecret");
+        expect(one.body).toMatchObject({
+          id: t.connection.publicId,
+          status: "active",
+          testedCurrentConfiguration: true,
+          planAvailable: true,
+          serviceProvider: { acsUrl: t.urls.acsUrl, entityId: t.urls.entityId, metadataUrl: t.urls.metadataUrl },
+        });
+        const domain = (one.body as { domains: Array<{ verificationRecord: { name: string } }> }).domains[0]!;
+        expect(domain.verificationRecord.name).toBe("_courselit-verification.acme.com");
+      }
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("creates a draft from pasted metadata, checks URLs, and keeps the entity ID immutable", async () => {
+    const t = await ssoSetup({ noConnection: true });
+    try {
+      const created = await call(t, "POST", "/v1/sso/connections", { displayName: "Acme", metadataXml: metadata() });
+      expect(created.status).toBe(201);
+      const connection = created.body as { id: string; status: string; idpEntityId: string; idpSsoUrl: string; idpCertificates: string[] };
+      expect(connection).toMatchObject({
+        status: "draft",
+        idpEntityId: "https://idp.example/entity",
+        idpSsoUrl: "https://idp.example/sso",
+        idpCertificates: [bareCertificate(idpKeys.cert)],
+      });
+      const path = `/v1/sso/connections/${connection.id}`;
+      expect((await call(t, "PATCH", path, { idpSsoUrl: "http://idp.example/sso" })).body).toMatchObject({ details: { reason: "unsafe_sso_url" } });
+      expect((await call(t, "PATCH", path, { idpSsoUrl: "javascript:alert(1)" })).status).toBe(400);
+      expect((await call(t, "PATCH", path, { idpCertificates: ["not a cert"] })).status).toBe(400);
+      expect((await call(t, "PATCH", path, { idpEntityId: "https://evil/entity" })).body).toMatchObject({ details: { reason: "idp_entity_id_immutable" } });
+      expect((await call(t, "PATCH", path, { metadataXml: metadata("https://evil/entity") })).body).toMatchObject({ details: { reason: "idp_entity_id_immutable" } });
+      // The same entity ID in new metadata is fine.
+      expect((await call(t, "PATCH", path, { metadataXml: metadata("https://idp.example/entity", "https://idp.example/sso2") })).status).toBe(200);
+      expect((await call(t, "POST", "/v1/sso/connections", { displayName: "No IdP" })).status).toBe(400);
+      expect((await call(t, "POST", "/v1/sso/connections", { displayName: "Bad", metadataXml: "<!DOCTYPE x [<!ENTITY a 'b'>]><x/>" })).status).toBe(400);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("sends an active connection back to draft when what it trusts changes, and ends its sessions", async () => {
+    const t = await ssoSetup();
+    try {
+      await ssoSession(t, "ssoer@acme.com", "sso");
+      const emailer = await ssoSession(t, "emailer@acme.com", "email");
+      expect(await sessionCount(t, "sso")).toBe(1);
+      const path = `/v1/sso/connections/${t.connection.publicId}`;
+      // Changing only the display name keeps it active.
+      expect((await call(t, "PATCH", path, { displayName: "Renamed" })).body).toMatchObject({ status: "active" });
+      expect(await sessionCount(t, "sso")).toBe(1);
+      for (const change of [
+        { idpCertificates: [bareCertificate(idpKeys.cert), bareCertificate(rotatedKeys.cert)] },
+        { idpSsoUrl: "https://idp.example/other" },
+        { subjectAttribute: "objectidentifier" },
+      ]) {
+        await t.runtime.db.update(schema.schoolSsoConnections).set({
+          status: "active", testedAt: t.clock.now(), testedConfigDigest: "x",
+        });
+        await ssoSession(t, `again-${Math.random()}@acme.com`, "sso");
+        const updated = await call(t, "PATCH", path, change);
+        expect(updated.body).toMatchObject({ status: "draft", testedAt: null, testedCurrentConfiguration: false });
+        expect(await sessionCount(t, "sso")).toBe(0);
+        const [row] = await t.runtime.db.select().from(schema.schoolSsoConnections);
+        expect(row!.testedConfigDigest).toBeNull();
+        // The learner's non-SSO session is untouched.
+        expect(await sessionCount(t, "email")).toBeGreaterThan(0);
+      }
+      expect(emailer.session.sessionId).toBeTruthy();
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("sends a turned-off connection back to draft when what it trusts changes, so it can be tested and turned on again", async () => {
+    const t = await ssoSetup();
+    try {
+      const path = `/v1/sso/connections/${t.connection.publicId}`;
+      expect((await call(t, "POST", `${path}/disable`, {})).status).toBe(200);
+      // Unchanged settings: the earlier test still counts, so it turns straight back on.
+      expect((await call(t, "POST", `${path}/activate`, {})).body).toMatchObject({ status: "active" });
+      expect((await call(t, "POST", `${path}/disable`, {})).status).toBe(200);
+      // A display name change keeps it off.
+      expect((await call(t, "PATCH", path, { displayName: "Renamed" })).body).toMatchObject({ status: "disabled" });
+      // A trust change makes it a draft that can be tested again.
+      const updated = await call(t, "PATCH", path, { idpSsoUrl: "https://idp.example/other" });
+      expect(updated.body).toMatchObject({ status: "draft", testedAt: null });
+      const test = await call(t, "POST", `${path}/test`, { returnUrl: `${t.runtime.auth.webOrigin}/x` });
+      expect(test.status).toBe(200);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("turning enforcement on ends non-SSO sessions of enforced domains only", async () => {
+    const t = await ssoSetup();
+    try {
+      await ssoSession(t, "inside@acme.com", "email");
+      await ssoSession(t, "outside@example.org", "email");
+      const updated = await call(t, "PATCH", `/v1/sso/connections/${t.connection.publicId}`, { enforcement: "required_for_domains" });
+      expect(updated.body).toMatchObject({ enforcement: "required_for_domains", status: "active" });
+      const remaining = await t.runtime.db
+        .select({ email: schema.schoolAccounts.email })
+        .from(schema.schoolSessions)
+        .innerJoin(schema.schoolAccounts, eq(schema.schoolAccounts.id, schema.schoolSessions.schoolAccountId));
+      expect(remaining.map((row) => row.email)).toEqual(["outside@example.org"]);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("verifies domains through DNS with a per-domain token, rejects bad ones, and rate limits verification", async () => {
+    const t = await ssoSetup({ status: "draft", tested: false, domains: [] });
+    try {
+      const txt = new Map<string, string[][]>();
+      t.runtime.dnsResolver = {
+        resolveTxt: async (name) => txt.get(name) ?? [],
+        resolveCname: async () => [],
+        resolve4: async () => [],
+      };
+      const path = `/v1/sso/connections/${t.connection.publicId}`;
+      const added = await call(t, "POST", `${path}/domains`, { domain: "@Acme.COM" });
+      expect(added.status).toBe(201);
+      const first = added.body as { domain: string; verified: boolean; verificationRecord: { type: string; name: string; value: string } };
+      expect(first).toMatchObject({ domain: "acme.com", verified: false });
+      expect(first.verificationRecord).toMatchObject({ type: "TXT", name: "_courselit-verification.acme.com" });
+      const other = (await call(t, "POST", `${path}/domains`, { domain: "other.com" })).body as typeof first;
+      expect(other.verificationRecord.value).not.toBe(first.verificationRecord.value);
+      expect(first.verificationRecord.value).toMatch(/^[0-9a-f]{32}$/);
+
+      for (const bad of ["localhost", "1.2.3.4", "com", "co.uk", "https://acme.com/x", "a b.com"]) {
+        expect([bad, (await call(t, "POST", `${path}/domains`, { domain: bad })).status]).toEqual([bad, 400]);
+      }
+      expect((await call(t, "POST", `${path}/domains`, { domain: "acme.com" })).status).toBe(409);
+
+      // Not published yet; another domain's token doesn't count.
+      expect((await call(t, "POST", `${path}/domains/acme.com/verify`, {})).body).toMatchObject({ verified: false });
+      txt.set("_courselit-verification.acme.com", [[other.verificationRecord.value]]);
+      expect((await call(t, "POST", `${path}/domains/acme.com/verify`, {})).body).toMatchObject({ verified: false });
+      txt.set("_courselit-verification.acme.com", [[first.verificationRecord.value.slice(0, 10), first.verificationRecord.value.slice(10)]]);
+      expect((await call(t, "POST", `${path}/domains/acme.com/verify`, {})).body).toMatchObject({ verified: true });
+      expect((await call(t, "DELETE", `${path}/domains/other.com`)).status).toBe(204);
+      expect((await call(t, "DELETE", `${path}/domains/other.com`)).status).toBe(404);
+
+      let status = 200;
+      for (let i = 0; i < 40 && status !== 429; i += 1) {
+        status = (await call(t, "POST", `${path}/domains/acme.com/verify`, {})).status;
+      }
+      expect(status).toBe(429);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("activates only with a verified domain, a test of the current settings, and the plan", async () => {
+    const t = await ssoSetup({ status: "draft", tested: false, domains: [] });
+    try {
+      const path = `/v1/sso/connections/${t.connection.publicId}`;
+      const activate = async () => call(t, "POST", `${path}/activate`, {});
+      expect((await activate()).body).toMatchObject({ details: { reason: "no_verified_domain" } });
+      await t.runtime.db.insert(schema.schoolSsoDomains).values({
+        id: crypto.randomUUID(), connectionId: t.connection.id, schoolId: t.world.schoolA.id,
+        domain: "acme.com", verificationToken: "t", verifiedAt: t.clock.now(), createdAt: t.clock.now(),
+      });
+      expect((await activate()).body).toMatchObject({ details: { reason: "not_tested" } });
+      const { connectionConfigDigest } = await import("./sso-config.js");
+      const [row] = await t.runtime.db.select().from(schema.schoolSsoConnections);
+      await t.runtime.db.update(schema.schoolSsoConnections).set({ testedAt: t.clock.now(), testedConfigDigest: "stale" });
+      expect((await activate()).body).toMatchObject({ details: { reason: "not_tested" } });
+      await t.runtime.db.update(schema.schoolSsoConnections).set({ testedConfigDigest: connectionConfigDigest(row!) });
+      const activated = await activate();
+      expect(activated.status).toBe(200);
+      expect(activated.body).toMatchObject({ status: "active" });
+      expect((await call(t, "POST", `${path}/disable`, {})).body).toMatchObject({ status: "disabled" });
+      // Re-activation after disabling works while the rules hold.
+      expect((await activate()).body).toMatchObject({ status: "active" });
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("refuses activation without the plan, while drafts can be prepared on any plan", async () => {
+    const t = await ssoSetup({ billingMode: "cloud", status: "draft", tested: true });
+    try {
+      const path = `/v1/sso/connections/${t.connection.publicId}`;
+      // School A is on Pro, which doesn't include SSO.
+      const refused = await call(t, "POST", `${path}/activate`, {});
+      expect(refused.status).toBe(403);
+      expect(refused.body).toMatchObject({ details: { reason: "plan_required" } });
+      expect((await call(t, "GET", path)).body).toMatchObject({ planAvailable: false, status: "draft" });
+      expect((await call(t, "PATCH", path, { displayName: "Prepared" })).status).toBe(200);
+      expect((await call(t, "POST", `${path}/domains`, { domain: "prep.com" })).status).toBe(201);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("allows only one active connection per school", async () => {
+    const t = await ssoSetup();
+    try {
+      const second = await call(t, "POST", "/v1/sso/connections", { displayName: "Second", metadataXml: metadata("https://idp2.example/entity") });
+      const id = (second.body as { id: string }).id;
+      await t.runtime.db.update(schema.schoolSsoConnections).set({ testedAt: t.clock.now() }).where(eq(schema.schoolSsoConnections.publicId, id));
+      await t.runtime.db.insert(schema.schoolSsoDomains).values({
+        id: crypto.randomUUID(), connectionId: (await t.runtime.db.select().from(schema.schoolSsoConnections).where(eq(schema.schoolSsoConnections.publicId, id)))[0]!.id,
+        schoolId: t.world.schoolA.id, domain: "second.com", verificationToken: "t", verifiedAt: t.clock.now(), createdAt: t.clock.now(),
+      });
+      const [row] = await t.runtime.db.select().from(schema.schoolSsoConnections).where(eq(schema.schoolSsoConnections.publicId, id));
+      const { connectionConfigDigest } = await import("./sso-config.js");
+      await t.runtime.db.update(schema.schoolSsoConnections).set({ testedConfigDigest: connectionConfigDigest(row!) }).where(eq(schema.schoolSsoConnections.id, row!.id));
+      const result = await call(t, "POST", `/v1/sso/connections/${id}/activate`, {});
+      expect(result.status).toBe(409);
+      expect(result.body).toMatchObject({ details: { reason: "another_connection_active" } });
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("only returns to the admin app from a test sign-in", async () => {
+    const t = await ssoSetup({ status: "draft", tested: false });
+    try {
+      const path = `/v1/sso/connections/${t.connection.publicId}/test`;
+      for (const returnUrl of ["https://evil.example/x", "https://user:pw@evil.example/", "javascript:alert(1)", `${t.runtime.auth.webOrigin}.evil.example/x`]) {
+        const response = await call(t, "POST", path, { returnUrl });
+        expect([returnUrl, response.status]).toEqual([returnUrl, 400]);
+      }
+      expect((await call(t, "POST", path, { returnUrl: `${t.runtime.auth.webOrigin}/settings` })).status).toBe(200);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("disables and deletes connections, ending sessions, and unlinks identities", async () => {
+    const t = await ssoSetup();
+    try {
+      const learner = await ssoSession(t, "linked@acme.com", "sso");
+      const [account] = await t.runtime.db.select().from(schema.schoolAccounts).where(eq(schema.schoolAccounts.email, "linked@acme.com"));
+      await t.runtime.db.insert(schema.schoolSsoIdentities).values({
+        id: crypto.randomUUID(), schoolId: t.world.schoolA.id, connectionId: t.connection.id,
+        issuer: "https://idp.example/entity", subject: "s-1", schoolAccountId: account!.id,
+        lastEmail: "linked@acme.com", createdAt: t.clock.now(),
+      });
+      expect((await call(t, "DELETE", `/v1/sso/identities/${account!.publicId}`)).status).toBe(204);
+      expect(await sessionCount(t, "sso")).toBe(0);
+      expect(await t.runtime.db.select().from(schema.schoolSsoIdentities)).toHaveLength(0);
+      expect((await call(t, "DELETE", `/v1/sso/identities/${account!.publicId}`)).status).toBe(404);
+
+      await ssoSession(t, "second@acme.com", "sso");
+      expect((await call(t, "POST", `/v1/sso/connections/${t.connection.publicId}/disable`, {})).body).toMatchObject({ status: "disabled" });
+      expect(await sessionCount(t, "sso")).toBe(0);
+      expect((await call(t, "DELETE", `/v1/sso/connections/${t.connection.publicId}`)).status).toBe(204);
+      expect((await call(t, "GET", `/v1/sso/connections/${t.connection.publicId}`)).status).toBe(404);
+      expect(learner.token).toBeTruthy();
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("audits every write and emails the owner what changed", async () => {
+    const t = await ssoSetup({ status: "draft", tested: false, domains: [] });
+    try {
+      const path = `/v1/sso/connections/${t.connection.publicId}`;
+      await call(t, "PATCH", path, { displayName: "New name", subjectAttribute: "oid" });
+      await call(t, "POST", `${path}/domains`, { domain: "audit.com" });
+      await call(t, "POST", `${path}/disable`, {});
+      const events = await t.runtime.db.select().from(schema.schoolSsoEvents);
+      expect(events.map((event) => event.action).sort()).toEqual(["connection.disabled", "connection.updated", "domain.added"]);
+      expect(events.every((event) => event.actorSchoolAccountId)).toBe(true);
+      const mails = (await t.runtime.db.select().from(schema.integrationOutboxJobs)).filter(
+        (job) => job.type === "send_system_email" || job.type === "send_school_email",
+      );
+      expect(mails).toHaveLength(3);
+      const payloads = mails.map((job) => job.payload as { to: string; text: string });
+      expect(payloads.every((payload) => payload.to === "owner@example.com")).toBe(true);
+      expect(payloads.some((payload) => payload.text.includes("name") && payload.text.includes("subject attribute"))).toBe(true);
+    } finally {
+      await t.close();
+    }
+  });
+});
diff --git a/apps/api/src/sso-admin.ts b/apps/api/src/sso-admin.ts
new file mode 100644
index 000000000..d804ad18c
--- /dev/null
+++ b/apps/api/src/sso-admin.ts
@@ -0,0 +1,756 @@
+import { randomBytes } from "node:crypto";
+import type { BillingEngine } from "@codelitdev/billing/workflows";
+import {
+  type Clock,
+  createDnsResolver,
+  createDomainVerification,
+  createPlatformError,
+  createPublicId,
+  type DnsResolver,
+  issueOwnershipToken,
+  normalizeHostname,
+  type PlatformError,
+  uuidv7,
+} from "@codelitdev/platform";
+import type { z } from "zod";
+import type {
+  addSsoDomainBodySchema,
+  createSsoConnectionBodySchema,
+  ssoConnectionSchema,
+  ssoConnectionTestResultSchema,
+  ssoDomainSchema,
+  startSsoConnectionTestBodySchema,
+  updateSsoConnectionBodySchema,
+} from "@courselit/api-contract";
+import { and, asc, count, eq } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { digestToken } from "./learners.js";
+import { schoolHasFeature } from "./plan-features.js";
+import { assertRateLimit } from "./rate-limit.js";
+import { endNonSsoSessionsForEnforcedDomains } from "./sign-in-policy.js";
+import {
+  activationBlocker,
+  connectionConfigDigest,
+  type SsoConnectionRow,
+  SSO_FEATURE,
+  ssoConfigDigest,
+  ssoServiceProviderUrls,
+} from "./sso-config.js";
+import { notifySsoOwner, recordSsoEvent } from "./sso-events.js";
+import { normalizeCertificate } from "./sso-protocol/certificates.js";
+import { isSafeIdpUrl, parseSamlIdpMetadata } from "./sso-protocol/index.js";
+import type { AppDb } from "./types.js";
+
+export const SSO_DOMAIN_LABEL = "_courselit-verification";
+const MAX_CONNECTIONS_PER_SCHOOL = 10;
+const MAX_DOMAINS_PER_CONNECTION = 20;
+const TEST_REQUEST_TTL_MS = 10 * 60 * 1000;
+const VERIFY_WINDOW_MS = 60 * 60 * 1000;
+const VERIFY_LIMIT = 30;
+
+type Billing = Pick<BillingEngine, "hasFeature">;
+type Result<T> = { ok: true; value: T } | { ok: false; error: PlatformError };
+export type SsoConnectionDto = z.infer<typeof ssoConnectionSchema>;
+export type SsoDomainDto = z.infer<typeof ssoDomainSchema>;
+export type SsoTestResultDto = z.infer<typeof ssoConnectionTestResultSchema>;
+
+export type SsoAdminContext = {
+  db: AppDb;
+  clock: Clock;
+  billing: Billing;
+  publicApiUrl: string;
+  /** The admin app's origin: the only place a test sign-in may return to. */
+  webOrigin: string;
+  /** Injectable DNS for tests; defaults to `SSO_DNS_SERVERS` or the system resolver. */
+  dnsResolver?: DnsResolver;
+  schoolId: string;
+  /** The signed-in admin's school account. */
+  actorSchoolAccountId: string;
+};
+
+const invalid = (reason: string): { ok: false; error: PlatformError } => ({
+  ok: false,
+  error: createPlatformError("validation_failed", { safeDetails: { reason } }),
+});
+const conflict = (reason: string): { ok: false; error: PlatformError } => ({
+  ok: false,
+  error: createPlatformError("conflict", { safeDetails: { reason } }),
+});
+const notFound = (): { ok: false; error: PlatformError } => ({
+  ok: false,
+  error: createPlatformError("not_found"),
+});
+
+/** `SSO_DNS_SERVERS` as a comma list of trusted recursive resolvers. */
+export function ssoDnsResolver(env: NodeJS.ProcessEnv = process.env): DnsResolver {
+  const servers = (env.SSO_DNS_SERVERS ?? "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+  return createDnsResolver(servers.length > 0 ? { servers } : {});
+}
+
+function domainVerification(resolver?: DnsResolver) {
+  return createDomainVerification({
+    label: SSO_DOMAIN_LABEL,
+    ...(resolver ? { resolver } : {}),
+  });
+}
+
+const iso = (value: Date | null) => (value ? value.toISOString() : null);
+
+export function toDomainDto(row: typeof schema.schoolSsoDomains.$inferSelect): SsoDomainDto {
+  return {
+    domain: row.domain,
+    verified: row.verifiedAt !== null,
+    verifiedAt: iso(row.verifiedAt),
+    verificationRecord: domainVerification().ownershipRecord(row.domain, row.verificationToken),
+    consecutiveCheckFailures: row.consecutiveCheckFailures,
+    lastCheckedAt: iso(row.lastCheckedAt),
+  };
+}
+
+export async function toConnectionDto(
+  ctx: SsoAdminContext,
+  connection: SsoConnectionRow,
+): Promise<SsoConnectionDto> {
+  const domains = await ctx.db
+    .select()
+    .from(schema.schoolSsoDomains)
+    .where(eq(schema.schoolSsoDomains.connectionId, connection.id))
+    .orderBy(asc(schema.schoolSsoDomains.createdAt), asc(schema.schoolSsoDomains.domain));
+  return {
+    id: connection.publicId,
+    protocol: connection.protocol,
+    status: connection.status,
+    displayName: connection.displayName,
+    enforcement: connection.enforcement,
+    maxSessionMinutes: connection.maxSessionMinutes,
+    idpEntityId: connection.idpEntityId,
+    idpSsoUrl: connection.idpSsoUrl,
+    idpCertificates: connection.idpCertificates,
+    subjectAttribute: connection.subjectAttribute,
+    serviceProvider: ssoServiceProviderUrls(ctx.publicApiUrl, connection.publicId),
+    domains: domains.map(toDomainDto),
+    testedAt: iso(connection.testedAt),
+    testedCurrentConfiguration:
+      connection.testedAt !== null &&
+      connection.testedConfigDigest === connectionConfigDigest(connection),
+    planAvailable: await schoolHasFeature(ctx.billing, connection.schoolId, SSO_FEATURE),
+    createdAt: connection.createdAt.toISOString(),
+    updatedAt: connection.updatedAt.toISOString(),
+  };
+}
+
+async function loadConnection(
+  ctx: SsoAdminContext,
+  publicId: string,
+): Promise<SsoConnectionRow | null> {
+  const [row] = await ctx.db
+    .select()
+    .from(schema.schoolSsoConnections)
+    .where(
+      and(
+        eq(schema.schoolSsoConnections.publicId, publicId),
+        eq(schema.schoolSsoConnections.schoolId, ctx.schoolId),
+      ),
+    )
+    .limit(1);
+  return row ?? null;
+}
+
+/** Record the change and tell the owner. `what` is a short, secret-free summary. */
+async function audit(
+  ctx: SsoAdminContext,
+  connection: { id: string | null; displayName: string },
+  action: string,
+  what: string,
+  metadata: Record<string, unknown> = {},
+) {
+  const eventId = await recordSsoEvent(
+    ctx.db,
+    {
+      schoolId: ctx.schoolId,
+      connectionId: connection.id,
+      actorSchoolAccountId: ctx.actorSchoolAccountId,
+      action,
+      metadata,
+    },
+    ctx.clock,
+  );
+  await notifySsoOwner(
+    ctx.db,
+    {
+      schoolId: ctx.schoolId,
+      subject: "Single sign-on settings changed",
+      lines: [
+        `${what} (${connection.displayName}).`,
+        "If you didn't make this change, review your school's sign-in settings right away.",
+      ],
+      idempotencyKey: `sso-event:${eventId}`,
+    },
+    ctx.clock,
+  );
+}
+
+type Settings = {
+  idpEntityId?: string;
+  idpSsoUrl?: string;
+  idpCertificates?: string[];
+};
+
+/** Entity ID, SSO URL and certificates from pasted metadata and/or explicit fields. */
+function resolveIdpSettings(input: {
+  metadataXml?: string;
+  idpEntityId?: string;
+  idpSsoUrl?: string;
+  idpCertificates?: string[];
+}): { ok: true; value: Settings } | { ok: false; error: PlatformError } {
+  const value: Settings = {};
+  if (input.metadataXml !== undefined) {
+    const parsed = parseSamlIdpMetadata(input.metadataXml);
+    if (!parsed.ok) return invalid(`metadata_${parsed.reason}`);
+    value.idpEntityId = parsed.entityId;
+    value.idpSsoUrl = parsed.ssoUrl;
+    value.idpCertificates = parsed.signingCertificates;
+  }
+  if (input.idpEntityId !== undefined) value.idpEntityId = input.idpEntityId;
+  if (input.idpSsoUrl !== undefined) value.idpSsoUrl = input.idpSsoUrl;
+  if (input.idpCertificates !== undefined) {
+    const normalized: string[] = [];
+    for (const raw of input.idpCertificates) {
+      const bare = normalizeCertificate(raw);
+      if (!bare) return invalid("invalid_certificate");
+      if (!normalized.includes(bare)) normalized.push(bare);
+    }
+    value.idpCertificates = normalized;
+  }
+  if (value.idpSsoUrl !== undefined && !isSafeIdpUrl(value.idpSsoUrl)) {
+    return invalid("unsafe_sso_url");
+  }
+  return { ok: true, value };
+}
+
+export async function listSsoConnections(
+  ctx: SsoAdminContext,
+): Promise<Result<{ items: SsoConnectionDto[] }>> {
+  const rows = await ctx.db
+    .select()
+    .from(schema.schoolSsoConnections)
+    .where(eq(schema.schoolSsoConnections.schoolId, ctx.schoolId))
+    .orderBy(asc(schema.schoolSsoConnections.createdAt));
+  return {
+    ok: true,
+    value: { items: await Promise.all(rows.map((row) => toConnectionDto(ctx, row))) },
+  };
+}
+
+export async function getSsoConnection(
+  ctx: SsoAdminContext,
+  publicId: string,
+): Promise<Result<SsoConnectionDto>> {
+  const connection = await loadConnection(ctx, publicId);
+  return connection ? { ok: true, value: await toConnectionDto(ctx, connection) } : notFound();
+}
+
+export async function createSsoConnection(
+  ctx: SsoAdminContext,
+  body: z.infer<typeof createSsoConnectionBodySchema>,
+): Promise<Result<SsoConnectionDto>> {
+  const settings = resolveIdpSettings(body);
+  if (!settings.ok) return settings;
+  if (!settings.value.idpEntityId) return invalid("idp_entity_id_required");
+  const [existing] = await ctx.db
+    .select({ n: count() })
+    .from(schema.schoolSsoConnections)
+    .where(eq(schema.schoolSsoConnections.schoolId, ctx.schoolId));
+  if (Number(existing?.n ?? 0) >= MAX_CONNECTIONS_PER_SCHOOL) {
+    return conflict("too_many_connections");
+  }
+  const now = ctx.clock.now();
+  const [created] = await ctx.db
+    .insert(schema.schoolSsoConnections)
+    .values({
+      id: uuidv7(ctx.clock),
+      publicId: createPublicId("sso", ctx.clock),
+      schoolId: ctx.schoolId,
+      protocol: "saml",
+      status: "draft",
+      displayName: body.displayName,
+      enforcement: body.enforcement ?? "optional",
+      maxSessionMinutes: body.maxSessionMinutes ?? null,
+      idpEntityId: settings.value.idpEntityId,
+      idpSsoUrl: settings.value.idpSsoUrl ?? null,
+      idpCertificates: settings.value.idpCertificates ?? [],
+      subjectAttribute: body.subjectAttribute ?? null,
+      createdAt: now,
+      updatedAt: now,
+    })
+    .returning();
+  await audit(ctx, created!, "connection.created", "A single sign-on connection was created");
+  return { ok: true, value: await toConnectionDto(ctx, created!) };
+}
+
+export async function updateSsoConnection(
+  ctx: SsoAdminContext,
+  publicId: string,
+  body: z.infer<typeof updateSsoConnectionBodySchema>,
+): Promise<Result<SsoConnectionDto>> {
+  const connection = await loadConnection(ctx, publicId);
+  if (!connection) return notFound();
+  const settings = resolveIdpSettings(body);
+  if (!settings.ok) return settings;
+  // Pointing at a different IdP means a new connection, which starts with no
+  // identities, so identities can never be inherited by another IdP.
+  if (
+    settings.value.idpEntityId !== undefined &&
+    settings.value.idpEntityId !== connection.idpEntityId
+  ) {
+    return invalid("idp_entity_id_immutable");
+  }
+  const next = {
+    idpEntityId: connection.idpEntityId,
+    idpSsoUrl: settings.value.idpSsoUrl ?? connection.idpSsoUrl,
+    idpCertificates: settings.value.idpCertificates ?? connection.idpCertificates,
+    subjectAttribute:
+      body.subjectAttribute === undefined ? connection.subjectAttribute : body.subjectAttribute,
+  };
+  const trustChanged = ssoConfigDigest(next) !== connectionConfigDigest(connection);
+  const enforcement = body.enforcement ?? connection.enforcement;
+  const changed: string[] = [];
+  if (body.displayName !== undefined && body.displayName !== connection.displayName) {
+    changed.push("name");
+  }
+  if (next.idpSsoUrl !== connection.idpSsoUrl) changed.push("sign-in URL");
+  if (
+    ssoConfigDigest({ ...connection, idpCertificates: next.idpCertificates }) !==
+    ssoConfigDigest(connection)
+  ) {
+    changed.push("certificates");
+  }
+  if (next.subjectAttribute !== connection.subjectAttribute) changed.push("subject attribute");
+  if (enforcement !== connection.enforcement) changed.push("enforcement");
+  if (
+    body.maxSessionMinutes !== undefined &&
+    body.maxSessionMinutes !== connection.maxSessionMinutes
+  ) {
+    changed.push("session length");
+  }
+  // What the connection trusts changing sends it back to draft: it has to be
+  // tested again, and everyone signed in through it signs in again. A turned
+  // off connection goes to draft too, because only a draft or active one can
+  // be tested: left disabled, it could never be tested or turned back on.
+  const backToDraft =
+    trustChanged &&
+    (connection.status === "active" ||
+      connection.status === "suspended" ||
+      connection.status === "disabled");
+  const [updated] = await ctx.db
+    .update(schema.schoolSsoConnections)
+    .set({
+      displayName: body.displayName ?? connection.displayName,
+      enforcement,
+      maxSessionMinutes:
+        body.maxSessionMinutes === undefined ? connection.maxSessionMinutes : body.maxSessionMinutes,
+      idpSsoUrl: next.idpSsoUrl,
+      idpCertificates: next.idpCertificates,
+      subjectAttribute: next.subjectAttribute,
+      ...(trustChanged ? { testedAt: null, testedConfigDigest: null } : {}),
+      ...(backToDraft ? { status: "draft" as const } : {}),
+      updatedAt: ctx.clock.now(),
+    })
+    .where(eq(schema.schoolSsoConnections.id, connection.id))
+    .returning();
+  if (backToDraft) {
+    await ctx.db
+      .delete(schema.schoolSessions)
+      .where(eq(schema.schoolSessions.ssoConnectionId, connection.id));
+  }
+  if (
+    updated!.status === "active" &&
+    enforcement === "required_for_domains" &&
+    connection.enforcement !== "required_for_domains"
+  ) {
+    await endNonSsoSessionsForEnforcedDomains(ctx.db, connection.id);
+  }
+  if (changed.length > 0) {
+    await audit(
+      ctx,
+      updated!,
+      "connection.updated",
+      `Changed ${changed.join(", ")}${backToDraft ? "; the connection went back to draft and must be tested again" : ""}`,
+      { changed, backToDraft },
+    );
+  }
+  return { ok: true, value: await toConnectionDto(ctx, updated!) };
+}
+
+export async function deleteSsoConnection(
+  ctx: SsoAdminContext,
+  publicId: string,
+): Promise<Result<null>> {
+  const connection = await loadConnection(ctx, publicId);
+  if (!connection) return notFound();
+  // Sessions, identities, domains and requests go with it (cascade).
+  await ctx.db
+    .delete(schema.schoolSsoConnections)
+    .where(eq(schema.schoolSsoConnections.id, connection.id));
+  // The connection row is gone, so the event can't point at it.
+  await audit(ctx, { id: null, displayName: connection.displayName }, "connection.deleted", "The connection was deleted", {
+    connection: connection.publicId,
+  });
+  return { ok: true, value: null };
+}
+
+export async function addSsoDomain(
+  ctx: SsoAdminContext,
+  publicId: string,
+  body: z.infer<typeof addSsoDomainBodySchema>,
+): Promise<Result<SsoDomainDto>> {
+  const connection = await loadConnection(ctx, publicId);
+  if (!connection) return notFound();
+  const domain = normalizeHostname(body.domain.replace(/^@/, ""));
+  if (!domain) return invalid("invalid_domain");
+  const [existing] = await ctx.db
+    .select({ n: count() })
+    .from(schema.schoolSsoDomains)
+    .where(eq(schema.schoolSsoDomains.connectionId, connection.id));
+  if (Number(existing?.n ?? 0) >= MAX_DOMAINS_PER_CONNECTION) return conflict("too_many_domains");
+  const [duplicate] = await ctx.db
+    .select({ id: schema.schoolSsoDomains.id })
+    .from(schema.schoolSsoDomains)
+    .where(
+      and(
+        eq(schema.schoolSsoDomains.schoolId, ctx.schoolId),
+        eq(schema.schoolSsoDomains.domain, domain),
+      ),
+    )
+    .limit(1);
+  if (duplicate) return conflict("domain_already_added");
+  const [row] = await ctx.db
+    .insert(schema.schoolSsoDomains)
+    .values({
+      id: uuidv7(ctx.clock),
+      connectionId: connection.id,
+      schoolId: ctx.schoolId,
+      domain,
+      // Random for each (school, domain) pair and never derived from another token.
+      verificationToken: issueOwnershipToken(),
+      createdAt: ctx.clock.now(),
+    })
+    .returning();
+  await audit(ctx, connection, "domain.added", `The domain ${domain} was added`, { domain });
+  return { ok: true, value: toDomainDto(row!) };
+}
+
+async function loadDomain(ctx: SsoAdminContext, connection: SsoConnectionRow, rawDomain: string) {
+  const domain = normalizeHostname(rawDomain);
+  if (!domain) return null;
+  const [row] = await ctx.db
+    .select()
+    .from(schema.schoolSsoDomains)
+    .where(
+      and(
+        eq(schema.schoolSsoDomains.connectionId, connection.id),
+        eq(schema.schoolSsoDomains.domain, domain),
+      ),
+    )
+    .limit(1);
+  return row ?? null;
+}
+
+export async function verifySsoDomain(
+  ctx: SsoAdminContext,
+  publicId: string,
+  rawDomain: string,
+): Promise<Result<SsoDomainDto>> {
+  const connection = await loadConnection(ctx, publicId);
+  if (!connection) return notFound();
+  const domain = await loadDomain(ctx, connection, rawDomain);
+  if (!domain) return notFound();
+  const limited = await assertRateLimit(
+    ctx.db,
+    {
+      schoolId: ctx.schoolId,
+      userId: "school",
+      scope: "learner_sso",
+      action: "verify_domain",
+      subjectId: ctx.schoolId,
+      windowMs: VERIFY_WINDOW_MS,
+      limit: VERIFY_LIMIT,
+    },
+    ctx.clock,
+  );
+  if (!limited.ok) return limited;
+  const proven = await domainVerification(ctx.dnsResolver ?? ssoDnsResolver()).verifyOwnership(
+    domain.domain,
+    domain.verificationToken,
+  );
+  const now = ctx.clock.now();
+  const [updated] = await ctx.db
+    .update(schema.schoolSsoDomains)
+    .set(
+      proven
+        ? { verifiedAt: domain.verifiedAt ?? now, consecutiveCheckFailures: 0, lastCheckedAt: now }
+        : { lastCheckedAt: now },
+    )
+    .where(eq(schema.schoolSsoDomains.id, domain.id))
+    .returning();
+  if (proven && !domain.verifiedAt) {
+    await audit(ctx, connection, "domain.verified", `The domain ${domain.domain} was verified`, {
+      domain: domain.domain,
+    });
+  }
+  return { ok: true, value: toDomainDto(updated!) };
+}
+
+export async function deleteSsoDomain(
+  ctx: SsoAdminContext,
+  publicId: string,
+  rawDomain: string,
+): Promise<Result<null>> {
+  const connection = await loadConnection(ctx, publicId);
+  if (!connection) return notFound();
+  const domain = await loadDomain(ctx, connection, rawDomain);
+  if (!domain) return notFound();
+  await ctx.db.delete(schema.schoolSsoDomains).where(eq(schema.schoolSsoDomains.id, domain.id));
+  await audit(ctx, connection, "domain.removed", `The domain ${domain.domain} was removed`, {
+    domain: domain.domain,
+  });
+  return { ok: true, value: null };
+}
+
+/** The admin origin plus a path, from a return URL the admin app sent. */
+function adminReturn(webOrigin: string, returnUrl: string): { origin: string; path: string } | null {
+  let target: URL;
+  try {
+    target = new URL(returnUrl);
+  } catch {
+    return null;
+  }
+  if (
+    target.origin !== new URL(webOrigin).origin ||
+    target.username ||
+    target.password ||
+    (target.protocol !== "https:" && target.protocol !== "http:")
+  ) {
+    return null;
+  }
+  return { origin: target.origin, path: `${target.pathname}${target.search}` };
+}
+
+export async function startSsoConnectionTest(
+  ctx: SsoAdminContext,
+  publicId: string,
+  body: z.infer<typeof startSsoConnectionTestBodySchema>,
+): Promise<Result<{ url: string }>> {
+  const connection = await loadConnection(ctx, publicId);
+  if (!connection) return notFound();
+  if (connection.status !== "draft" && connection.status !== "active") {
+    return conflict("connection_not_testable");
+  }
+  if (
+    connection.protocol !== "saml" ||
+    !connection.idpSsoUrl ||
+    !isSafeIdpUrl(connection.idpSsoUrl) ||
+    connection.idpCertificates.length === 0
+  ) {
+    return invalid("incomplete_configuration");
+  }
+  const target = adminReturn(ctx.webOrigin, body.returnUrl);
+  if (!target) return invalid("return_url_not_allowed");
+  const token = randomBytes(32).toString("base64url");
+  const now = ctx.clock.now();
+  await ctx.db.insert(schema.schoolSsoRequests).values({
+    id: uuidv7(ctx.clock),
+    requestDigest: digestToken(token),
+    schoolId: ctx.schoolId,
+    connectionId: connection.id,
+    // A test needs no browser nonce; nothing ever redeems a ticket for it.
+    nonceDigest: digestToken(randomBytes(32).toString("base64url")),
+    returnOrigin: target.origin,
+    nextPath: target.path.slice(0, 1000),
+    purpose: "test",
+    startedBySchoolAccountId: ctx.actorSchoolAccountId,
+    expiresAt: new Date(now.getTime() + TEST_REQUEST_TTL_MS),
+    createdAt: now,
+  });
+  await recordSsoEvent(
+    ctx.db,
+    {
+      schoolId: ctx.schoolId,
+      connectionId: connection.id,
+      actorSchoolAccountId: ctx.actorSchoolAccountId,
+      action: "test.started",
+    },
+    ctx.clock,
+  );
+  const url = new URL(
+    `/learner-login/sso/${encodeURIComponent(connection.publicId)}/start`,
+    ctx.publicApiUrl,
+  );
+  url.searchParams.set("request", token);
+  return { ok: true, value: { url: url.toString() } };
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** What the IdP sent in a test sign-in, for the admin who started it, for 15 minutes. */
+export async function getSsoConnectionTestResult(
+  ctx: SsoAdminContext,
+  publicId: string,
+  requestId: string,
+): Promise<Result<SsoTestResultDto>> {
+  const connection = await loadConnection(ctx, publicId);
+  if (!connection || !UUID.test(requestId)) return notFound();
+  const [row] = await ctx.db
+    .select()
+    .from(schema.schoolSsoRequests)
+    .where(
+      and(
+        eq(schema.schoolSsoRequests.id, requestId.toLowerCase()),
+        eq(schema.schoolSsoRequests.connectionId, connection.id),
+        eq(schema.schoolSsoRequests.purpose, "test"),
+        eq(schema.schoolSsoRequests.startedBySchoolAccountId, ctx.actorSchoolAccountId),
+      ),
+    )
+    .limit(1);
+  const result = row?.testResult as Record<string, unknown> | null | undefined;
+  if (
+    !row ||
+    !result ||
+    !row.testResultExpiresAt ||
+    row.testResultExpiresAt.getTime() <= ctx.clock.now().getTime()
+  ) {
+    return notFound();
+  }
+  const str = (value: unknown) => (typeof value === "string" ? value : null);
+  return {
+    ok: true,
+    value: {
+      ok: result.ok === true,
+      reason: str(result.reason),
+      issuer: str(result.issuer),
+      subject: str(result.subject),
+      email: str(result.email),
+      name: str(result.name),
+      emailDomainVerified:
+        typeof result.emailDomainVerified === "boolean" ? result.emailDomainVerified : null,
+      attributes: (result.attributes ?? {}) as Record<string, string[]>,
+      expiresAt: row.testResultExpiresAt.toISOString(),
+    },
+  };
+}
+
+export async function activateSsoConnection(
+  ctx: SsoAdminContext,
+  publicId: string,
+): Promise<Result<SsoConnectionDto>> {
+  const connection = await loadConnection(ctx, publicId);
+  if (!connection) return notFound();
+  if (connection.status === "active") {
+    return { ok: true, value: await toConnectionDto(ctx, connection) };
+  }
+  if (connection.status === "suspended") {
+    // The system restores a suspended connection when the plan is back.
+    return conflict("connection_suspended");
+  }
+  if (!(await schoolHasFeature(ctx.billing, ctx.schoolId, SSO_FEATURE))) {
+    return {
+      ok: false,
+      error: createPlatformError("forbidden", { safeDetails: { reason: "plan_required" } }),
+    };
+  }
+  const blocker = await activationBlocker(ctx.db, connection);
+  if (blocker) return conflict(blocker);
+  let activated: SsoConnectionRow | undefined;
+  try {
+    [activated] = await ctx.db
+      .update(schema.schoolSsoConnections)
+      .set({ status: "active", updatedAt: ctx.clock.now() })
+      .where(eq(schema.schoolSsoConnections.id, connection.id))
+      .returning();
+  } catch {
+    return conflict("another_connection_active");
+  }
+  if (activated!.enforcement === "required_for_domains") {
+    await endNonSsoSessionsForEnforcedDomains(ctx.db, connection.id);
+  }
+  await audit(ctx, activated!, "connection.activated", "The connection was turned on");
+  return { ok: true, value: await toConnectionDto(ctx, activated!) };
+}
+
+export async function disableSsoConnection(
+  ctx: SsoAdminContext,
+  publicId: string,
+): Promise<Result<SsoConnectionDto>> {
+  const connection = await loadConnection(ctx, publicId);
+  if (!connection) return notFound();
+  const [disabled] = await ctx.db
+    .update(schema.schoolSsoConnections)
+    .set({ status: "disabled", updatedAt: ctx.clock.now() })
+    .where(eq(schema.schoolSsoConnections.id, connection.id))
+    .returning();
+  await ctx.db
+    .delete(schema.schoolSessions)
+    .where(eq(schema.schoolSessions.ssoConnectionId, connection.id));
+  await audit(ctx, disabled!, "connection.disabled", "The connection was turned off and its sessions ended");
+  return { ok: true, value: await toConnectionDto(ctx, disabled!) };
+}
+
+/** Remove a learner's SSO link and end their SSO sessions. */
+export async function unlinkSsoIdentity(
+  ctx: SsoAdminContext,
+  schoolAccountPublicId: string,
+): Promise<Result<null>> {
+  const [account] = await ctx.db
+    .select({ id: schema.schoolAccounts.id })
+    .from(schema.schoolAccounts)
+    .where(
+      and(
+        eq(schema.schoolAccounts.publicId, schoolAccountPublicId),
+        eq(schema.schoolAccounts.schoolId, ctx.schoolId),
+      ),
+    )
+    .limit(1);
+  if (!account) return notFound();
+  const removed = await ctx.db
+    .delete(schema.schoolSsoIdentities)
+    .where(
+      and(
+        eq(schema.schoolSsoIdentities.schoolAccountId, account.id),
+        eq(schema.schoolSsoIdentities.schoolId, ctx.schoolId),
+      ),
+    )
+    .returning({ connectionId: schema.schoolSsoIdentities.connectionId });
+  if (removed.length === 0) return notFound();
+  await ctx.db
+    .delete(schema.schoolSessions)
+    .where(
+      and(
+        eq(schema.schoolSessions.schoolAccountId, account.id),
+        eq(schema.schoolSessions.authenticationMethod, "sso"),
+      ),
+    );
+  const eventId = await recordSsoEvent(
+    ctx.db,
+    {
+      schoolId: ctx.schoolId,
+      connectionId: removed[0]!.connectionId,
+      actorSchoolAccountId: ctx.actorSchoolAccountId,
+      action: "identity.unlinked",
+    },
+    ctx.clock,
+  );
+  await notifySsoOwner(
+    ctx.db,
+    {
+      schoolId: ctx.schoolId,
+      subject: "Single sign-on settings changed",
+      lines: ["A learner's single sign-on link was removed and their SSO sessions ended."],
+      idempotencyKey: `sso-event:${eventId}`,
+    },
+    ctx.clock,
+  );
+  return { ok: true, value: null };
+}
diff --git a/apps/api/src/sso-config.test.ts b/apps/api/src/sso-config.test.ts
new file mode 100644
index 000000000..bfc9a3465
--- /dev/null
+++ b/apps/api/src/sso-config.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from "bun:test";
+import { ssoConfigDigest, ssoServiceProviderUrls } from "./sso-config.js";
+import { idpKeys, rotatedKeys } from "./sso-protocol/test-idp.js";
+
+const bare = (pem: string) => pem.replace(/-----[A-Z ]+-----/g, "").replace(/\s+/g, "");
+const base = {
+  idpEntityId: "https://idp.example/entity",
+  idpSsoUrl: "https://idp.example/sso",
+  idpCertificates: [bare(idpKeys.cert)],
+  subjectAttribute: null,
+};
+
+describe("ssoConfigDigest", () => {
+  it("ignores certificate order, PEM armour and duplicates", () => {
+    const one = ssoConfigDigest({ ...base, idpCertificates: [bare(idpKeys.cert), bare(rotatedKeys.cert)] });
+    const two = ssoConfigDigest({ ...base, idpCertificates: [rotatedKeys.cert, idpKeys.cert, bare(idpKeys.cert)] });
+    expect(one).toBe(two);
+  });
+  it("changes with the entity ID, SSO URL, certificates and subject attribute", () => {
+    const digest = ssoConfigDigest(base);
+    const variants = [
+      { ...base, idpEntityId: "https://other/entity" },
+      { ...base, idpSsoUrl: "https://idp.example/other" },
+      { ...base, idpCertificates: [bare(rotatedKeys.cert)] },
+      { ...base, subjectAttribute: "oid" },
+    ];
+    for (const variant of variants) expect(ssoConfigDigest(variant)).not.toBe(digest);
+    expect(new Set(variants.map(ssoConfigDigest)).size).toBe(variants.length);
+  });
+});
+
+describe("ssoServiceProviderUrls", () => {
+  it("puts the ACS and metadata on the API host, per connection", () => {
+    expect(ssoServiceProviderUrls("https://api.example.com/", "sso_abc")).toEqual({
+      entityId: "https://api.example.com/learner-login/sso/sso_abc/metadata",
+      metadataUrl: "https://api.example.com/learner-login/sso/sso_abc/metadata",
+      acsUrl: "https://api.example.com/learner-login/sso/sso_abc/acs",
+    });
+  });
+});
diff --git a/apps/api/src/sso-config.ts b/apps/api/src/sso-config.ts
new file mode 100644
index 000000000..0559c319c
--- /dev/null
+++ b/apps/api/src/sso-config.ts
@@ -0,0 +1,117 @@
+import { createHash } from "node:crypto";
+import { and, eq, isNotNull } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { normalizeCertificate } from "./sso-protocol/certificates.js";
+import { isSafeIdpUrl } from "./sso-protocol/url.js";
+import type { SamlConnectionConfig } from "./sso-protocol/index.js";
+import type { AppDb } from "./types.js";
+
+export type SsoConnectionRow = typeof schema.schoolSsoConnections.$inferSelect;
+
+/** The plan feature learner SSO is gated behind. */
+export const SSO_FEATURE = "learner_sso";
+
+/**
+ * Where a school's IdP sends people and metadata is read from. Both live on
+ * the API host and are unique per connection, so a school changing its custom
+ * domain never breaks its IdP setup, and a response meant for one connection
+ * fails the audience check of every other.
+ */
+export function ssoServiceProviderUrls(publicApiUrl: string, connectionPublicId: string) {
+  const id = encodeURIComponent(connectionPublicId);
+  const metadataUrl = new URL(`/learner-login/sso/${id}/metadata`, publicApiUrl).toString();
+  return {
+    entityId: metadataUrl,
+    metadataUrl,
+    acsUrl: new URL(`/learner-login/sso/${id}/acs`, publicApiUrl).toString(),
+  };
+}
+
+/**
+ * A stable hash of what a connection trusts: entity ID, SSO URL, certificates
+ * (order and PEM armour ignored) and the subject attribute. A test sign-in
+ * records it, and activation requires it to still match, so a draft can't be
+ * tested with one certificate and activated with another.
+ */
+export function ssoConfigDigest(config: {
+  idpEntityId: string | null;
+  idpSsoUrl: string | null;
+  idpCertificates: readonly string[];
+  subjectAttribute: string | null;
+}): string {
+  const certificates = [
+    ...new Set(config.idpCertificates.map((value) => normalizeCertificate(value) ?? value)),
+  ].sort();
+  return createHash("sha256")
+    .update(
+      JSON.stringify([
+        config.idpEntityId ?? "",
+        config.idpSsoUrl ?? "",
+        certificates,
+        config.subjectAttribute ?? "",
+      ]),
+    )
+    .digest("hex");
+}
+
+export function connectionConfigDigest(connection: SsoConnectionRow): string {
+  return ssoConfigDigest(connection);
+}
+
+export function samlConfigFor(
+  connection: SsoConnectionRow,
+  publicApiUrl: string,
+): SamlConnectionConfig {
+  const urls = ssoServiceProviderUrls(publicApiUrl, connection.publicId);
+  return {
+    spEntityId: urls.entityId,
+    acsUrl: urls.acsUrl,
+    idpEntityId: connection.idpEntityId ?? "",
+    idpSsoUrl: connection.idpSsoUrl ?? "",
+    idpCertificates: connection.idpCertificates,
+    subjectAttribute: connection.subjectAttribute,
+  };
+}
+
+export type ActivationBlocker =
+  | "incomplete_configuration"
+  | "no_verified_domain"
+  | "not_tested";
+
+/**
+ * The activation rules that don't depend on the plan: a complete SAML
+ * configuration, at least one verified domain, and a successful test against
+ * exactly the current settings. Null when all hold.
+ */
+export async function activationBlocker(
+  db: AppDb,
+  connection: SsoConnectionRow,
+): Promise<ActivationBlocker | null> {
+  if (
+    connection.protocol !== "saml" ||
+    !connection.idpEntityId ||
+    !connection.idpSsoUrl ||
+    !isSafeIdpUrl(connection.idpSsoUrl) ||
+    connection.idpCertificates.length === 0
+  ) {
+    return "incomplete_configuration";
+  }
+  const [domain] = await db
+    .select({ id: schema.schoolSsoDomains.id })
+    .from(schema.schoolSsoDomains)
+    .where(
+      and(
+        eq(schema.schoolSsoDomains.connectionId, connection.id),
+        isNotNull(schema.schoolSsoDomains.verifiedAt),
+      ),
+    )
+    .limit(1);
+  if (!domain) return "no_verified_domain";
+  if (
+    !connection.testedAt ||
+    connection.testedConfigDigest !== connectionConfigDigest(connection)
+  ) {
+    return "not_tested";
+  }
+  return null;
+}
diff --git a/apps/api/src/sso-email.ts b/apps/api/src/sso-email.ts
new file mode 100644
index 000000000..e81650370
--- /dev/null
+++ b/apps/api/src/sso-email.ts
@@ -0,0 +1,41 @@
+import { normalizeHostname } from "@codelitdev/platform";
+
+function hasControlCharacter(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+const LOCAL_PART = /^[a-z0-9!#$%&'*+/=?^_`{|}~-]+(\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*$/;
+
+/**
+ * Parse an email an IdP sent. Plain `local@domain` only: no quoted local
+ * part, comments, second `@`, whitespace or control characters. The domain
+ * becomes lowercase punycode; the local part is lowercased like every other
+ * school account email. Null for anything else.
+ */
+export function parseSsoEmail(
+  raw: unknown,
+): { email: string; local: string; domain: string } | null {
+  if (typeof raw !== "string" || raw.length === 0 || raw.length > 254) return null;
+  if (/\s/.test(raw) || hasControlCharacter(raw)) return null;
+  const at = raw.indexOf("@");
+  if (at <= 0 || at !== raw.lastIndexOf("@")) return null;
+  const local = raw.slice(0, at).toLowerCase();
+  const rawDomain = raw.slice(at + 1);
+  // A bare domain only: `normalizeHostname` also accepts a URL-ish form
+  // (`https://acme.com/`), which is never a valid email domain.
+  if (/[/:?#[\]\\]/.test(rawDomain)) return null;
+  const domain = normalizeHostname(rawDomain);
+  if (!domain || local.length > 64 || !LOCAL_PART.test(local)) return null;
+  return { email: `${local}@${domain}`, local, domain };
+}
+
+/** The normalized domain of an already-stored or typed email, or null. */
+export function emailDomainOf(email: string): string | null {
+  const at = email.lastIndexOf("@");
+  if (at < 0) return null;
+  return normalizeHostname(email.slice(at + 1));
+}
diff --git a/apps/api/src/sso-events.ts b/apps/api/src/sso-events.ts
new file mode 100644
index 000000000..194df8fd1
--- /dev/null
+++ b/apps/api/src/sso-events.ts
@@ -0,0 +1,84 @@
+import { type Clock, uuidv7 } from "@codelitdev/platform";
+import { and, eq } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { queueSchoolEmail, renderSchoolEmail } from "./school-emails.js";
+import { adminSiteUrl } from "./school-emails.js";
+import type { AppDb } from "./types.js";
+
+/** One row in the SSO audit log. Reason codes only; never assertion contents. */
+export async function recordSsoEvent(
+  db: AppDb,
+  input: {
+    schoolId: string;
+    connectionId?: string | null;
+    actorSchoolAccountId?: string | null;
+    action: string;
+    reason?: string | null;
+    metadata?: Record<string, unknown>;
+  },
+  clock: Clock,
+): Promise<string> {
+  const id = uuidv7(clock);
+  await db.insert(schema.schoolSsoEvents).values({
+    id,
+    schoolId: input.schoolId,
+    connectionId: input.connectionId ?? null,
+    actorSchoolAccountId: input.actorSchoolAccountId ?? null,
+    action: input.action,
+    reason: input.reason ?? null,
+    metadata: input.metadata ?? {},
+    createdAt: clock.now(),
+  });
+  return id;
+}
+
+/** The email address of the school's owner, or null. */
+export async function schoolOwnerEmail(db: AppDb, schoolId: string): Promise<string | null> {
+  const [owner] = await db
+    .select({ email: schema.schoolAccounts.email })
+    .from(schema.memberships)
+    .innerJoin(
+      schema.schoolAccounts,
+      eq(schema.schoolAccounts.id, schema.memberships.schoolAccountId),
+    )
+    .where(and(eq(schema.memberships.schoolId, schoolId), eq(schema.memberships.isOwner, true)))
+    .limit(1);
+  return owner?.email ?? null;
+}
+
+/**
+ * Tell the school's owner what changed about its SSO setup, through the same
+ * school email path as other owner notifications.
+ */
+export async function notifySsoOwner(
+  db: AppDb,
+  input: {
+    schoolId: string;
+    subject: string;
+    lines: string[];
+    idempotencyKey: string;
+  },
+  clock: Clock,
+): Promise<void> {
+  const [school] = await db
+    .select({ name: schema.schools.name })
+    .from(schema.schools)
+    .where(eq(schema.schools.id, input.schoolId))
+    .limit(1);
+  const to = await schoolOwnerEmail(db, input.schoolId);
+  if (!school || !to) return;
+  const rendered = renderSchoolEmail({
+    schoolName: school.name,
+    paragraphs: input.lines,
+    footer: {
+      text: "You're receiving this because you own this school.",
+      link: { label: "Review sign-in settings", url: `${adminSiteUrl()}/settings/login-providers` },
+    },
+  });
+  await queueSchoolEmail(
+    db,
+    input.schoolId,
+    { to, subject: input.subject, ...rendered, idempotencyKey: input.idempotencyKey },
+    clock,
+  );
+}
diff --git a/apps/api/src/sso-jobs.test.ts b/apps/api/src/sso-jobs.test.ts
new file mode 100644
index 000000000..4a080d0f1
--- /dev/null
+++ b/apps/api/src/sso-jobs.test.ts
@@ -0,0 +1,127 @@
+import { describe, expect, it } from "bun:test";
+import { eq } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { cleanupSsoRequests } from "./learner-sso-sign-in.js";
+import { freezeRuntimeClock } from "./runtime.js";
+import { recheckSsoDomains, syncAllSsoPlanFeatures } from "./sso-jobs.js";
+import { ssoSetup } from "./test-sso-flow.js";
+
+const DAY = 24 * 60 * 60 * 1000;
+const resolverFor = (records: Record<string, string[][]>) => ({
+  resolveTxt: async (name: string) => records[name] ?? [],
+  resolveCname: async () => [],
+  resolve4: async () => [],
+});
+const domainRow = async (t: Awaited<ReturnType<typeof ssoSetup>>) =>
+  (await t.runtime.db.select().from(schema.schoolSsoDomains))[0]!;
+
+describe.serial("SSO background jobs", () => {
+  it("clears a domain's verification only after three failed weekly checks in a row", async () => {
+    const t = await ssoSetup();
+    try {
+      const resolver = resolverFor({});
+      const runAt = async (days: number) => {
+        const later = freezeRuntimeClock(new Date(t.clock.now().getTime() + days * DAY));
+        return recheckSsoDomains(t.runtime.db, later, { resolver });
+      };
+      expect(await runAt(7)).toEqual({ checked: 1, unverified: 0 });
+      expect((await domainRow(t)).consecutiveCheckFailures).toBe(1);
+      expect((await domainRow(t)).verifiedAt).not.toBeNull();
+      // Running again the same week doesn't count again.
+      expect(await runAt(7.2)).toEqual({ checked: 0, unverified: 0 });
+      expect((await domainRow(t)).consecutiveCheckFailures).toBe(1);
+      expect(await runAt(14)).toEqual({ checked: 1, unverified: 0 });
+      expect((await domainRow(t)).verifiedAt).not.toBeNull();
+      expect(await runAt(21)).toEqual({ checked: 1, unverified: 1 });
+      const lapsed = await domainRow(t);
+      expect(lapsed.verifiedAt).toBeNull();
+      expect(lapsed.consecutiveCheckFailures).toBe(3);
+      const events = await t.runtime.db.select().from(schema.schoolSsoEvents);
+      expect(events.some((event) => event.action === "domain.lapsed")).toBe(true);
+      const mails = (await t.runtime.db.select().from(schema.integrationOutboxJobs)).filter(
+        (job) => job.type === "send_system_email" || job.type === "send_school_email",
+      );
+      expect(mails.some((job) => (job.payload as { to: string }).to === "owner@example.com")).toBe(true);
+      // A lapsed domain isn't checked again.
+      expect(await runAt(28)).toEqual({ checked: 0, unverified: 0 });
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("a successful check resets the failure count", async () => {
+    const t = await ssoSetup();
+    try {
+      const [row] = await t.runtime.db.select().from(schema.schoolSsoDomains);
+      await t.runtime.db.update(schema.schoolSsoDomains).set({ consecutiveCheckFailures: 2 });
+      const later = freezeRuntimeClock(new Date(t.clock.now().getTime() + 8 * DAY));
+      const result = await recheckSsoDomains(t.runtime.db, later, {
+        resolver: resolverFor({ "_courselit-verification.acme.com": [[row!.verificationToken]] }),
+      });
+      expect(result).toEqual({ checked: 1, unverified: 0 });
+      const after = await domainRow(t);
+      expect(after.consecutiveCheckFailures).toBe(0);
+      expect(after.verifiedAt).not.toBeNull();
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("cleans up expired requests, test results and replay-cache rows only", async () => {
+    const t = await ssoSetup();
+    try {
+      const now = t.clock.now();
+      const base = {
+        schoolId: t.world.schoolA.id,
+        connectionId: t.connection.id,
+        nonceDigest: "n",
+        returnOrigin: "http://x",
+        nextPath: "/",
+        createdAt: now,
+      };
+      const ago = (ms: number) => new Date(now.getTime() - ms);
+      await t.runtime.db.insert(schema.schoolSsoRequests).values([
+        { ...base, id: crypto.randomUUID(), requestDigest: "expired", expiresAt: ago(1000) },
+        { ...base, id: crypto.randomUUID(), requestDigest: "open", expiresAt: new Date(now.getTime() + 60_000) },
+        { ...base, id: crypto.randomUUID(), requestDigest: "result-live", purpose: "test", expiresAt: ago(1000), testResult: { ok: true }, testResultExpiresAt: new Date(now.getTime() + 60_000) },
+        { ...base, id: crypto.randomUUID(), requestDigest: "result-dead", purpose: "test", expiresAt: ago(1000), testResult: { ok: true }, testResultExpiresAt: ago(1000) },
+      ]);
+      await t.runtime.db.insert(schema.schoolSsoAssertionIds).values([
+        { connectionId: t.connection.id, assertionId: "old", expiresAt: ago(1000) },
+        { connectionId: t.connection.id, assertionId: "new", expiresAt: new Date(now.getTime() + 60_000) },
+      ]);
+      expect(await cleanupSsoRequests(t.runtime.db, t.clock)).toEqual({ requests: 2, assertionIds: 1 });
+      const left = (await t.runtime.db.select().from(schema.schoolSsoRequests)).map((row) => row.requestDigest).sort();
+      expect(left).toEqual(["open", "result-live"]);
+      expect((await t.runtime.db.select().from(schema.schoolSsoAssertionIds)).map((row) => row.assertionId)).toEqual(["new"]);
+    } finally {
+      await t.close();
+    }
+  });
+
+  it("the daily sync covers schools with active or suspended connections and survives a failing school", async () => {
+    const t = await ssoSetup({ status: "suspended" });
+    try {
+      expect(await syncAllSsoPlanFeatures(t.runtime.db, t.runtime.billing.billing, t.clock)).toBe(1);
+      expect((await t.runtime.db.select().from(schema.schoolSsoConnections))[0]!.status).toBe("active");
+      // The real engine answers false when billing can't be read; a direct
+      // state read throws.
+      const failing = {
+        hasFeature: async () => false,
+        commercialState: async () => {
+          throw new Error("billing down");
+        },
+      };
+      const logged: unknown[] = [];
+      expect(await syncAllSsoPlanFeatures(t.runtime.db, failing, t.clock, { warn: (...args: unknown[]) => logged.push(args) } as never)).toBe(0);
+      expect(logged).toHaveLength(1);
+      // The connection wasn't suspended by the failure.
+      expect((await t.runtime.db.select().from(schema.schoolSsoConnections).where(eq(schema.schoolSsoConnections.id, t.connection.id)))[0]!.status).toBe("active");
+      // Draft and disabled connections aren't synced.
+      await t.runtime.db.update(schema.schoolSsoConnections).set({ status: "draft" });
+      expect(await syncAllSsoPlanFeatures(t.runtime.db, t.runtime.billing.billing, t.clock)).toBe(0);
+    } finally {
+      await t.close();
+    }
+  });
+});
diff --git a/apps/api/src/sso-jobs.ts b/apps/api/src/sso-jobs.ts
new file mode 100644
index 000000000..cb3508f82
--- /dev/null
+++ b/apps/api/src/sso-jobs.ts
@@ -0,0 +1,215 @@
+import type { BillingEngine } from "@codelitdev/billing/workflows";
+import type { Clock } from "@codelitdev/platform";
+import { and, eq, inArray, isNotNull, isNull, lt, or } from "drizzle-orm";
+import type { Logger } from "pino";
+import * as schema from "./db/schema/index.js";
+import { processNextPlatformJob } from "./integration-provisioning.js";
+import { cleanupSsoRequests } from "./learner-sso-sign-in.js";
+import { schoolsWithSsoConnections, syncPlanFeatures } from "./plan-features.js";
+import { SSO_DOMAIN_LABEL, ssoDnsResolver } from "./sso-admin.js";
+import { notifySsoOwner, recordSsoEvent } from "./sso-events.js";
+import { createDomainVerification, type DnsResolver } from "@codelitdev/platform";
+import type { AppDb } from "./types.js";
+
+type Billing = Pick<BillingEngine, "hasFeature" | "commercialState">;
+
+/** Failed weekly checks in a row before a domain stops counting as verified. */
+export const DOMAIN_FAILURES_BEFORE_UNVERIFIED = 3;
+const DOMAIN_RECHECK_INTERVAL_MS = 6.5 * 24 * 60 * 60 * 1000;
+
+/** Drain the platform jobs the billing hook queued (`sync_plan_features`). */
+export async function processPlatformJobs(
+  db: AppDb,
+  billing: Billing,
+  clock: Clock,
+  logger: Logger,
+): Promise<number> {
+  let processed = 0;
+  while (
+    await processNextPlatformJob(db, clock, logger, async (job) => {
+      if (job.type !== "sync_plan_features") {
+        throw new Error(`Unknown platform job type: ${job.type}`);
+      }
+      await syncPlanFeatures(db, billing, job.schoolId, clock);
+    })
+  ) {
+    processed += 1;
+  }
+  return processed;
+}
+
+/** The daily backstop: re-sync every school that has an active or suspended connection. */
+export async function syncAllSsoPlanFeatures(
+  db: AppDb,
+  billing: Billing,
+  clock: Clock,
+  logger?: Logger,
+): Promise<number> {
+  let synced = 0;
+  for (const schoolId of await schoolsWithSsoConnections(db)) {
+    try {
+      await syncPlanFeatures(db, billing, schoolId, clock);
+      synced += 1;
+    } catch (error) {
+      logger?.warn(
+        { schoolId, error: error instanceof Error ? error.message : String(error) },
+        "SSO plan sync failed",
+      );
+    }
+  }
+  return synced;
+}
+
+/**
+ * The weekly domain re-check. A verified domain whose TXT record is missing
+ * is only cleared after three checks in a row, so one DNS error doesn't take
+ * sign-in away. Each domain is checked at most about once a week, so running
+ * this more often (or from several workers) never inflates the count.
+ */
+export async function recheckSsoDomains(
+  db: AppDb,
+  clock: Clock,
+  options: { resolver?: DnsResolver; logger?: Logger } = {},
+): Promise<{ checked: number; unverified: number }> {
+  const now = clock.now();
+  const dueBefore = new Date(now.getTime() - DOMAIN_RECHECK_INTERVAL_MS);
+  const due = await db
+    .select({ domain: schema.schoolSsoDomains, connection: schema.schoolSsoConnections })
+    .from(schema.schoolSsoDomains)
+    .innerJoin(
+      schema.schoolSsoConnections,
+      eq(schema.schoolSsoConnections.id, schema.schoolSsoDomains.connectionId),
+    )
+    .where(
+      and(
+        isNotNull(schema.schoolSsoDomains.verifiedAt),
+        inArray(schema.schoolSsoConnections.status, ["active", "suspended", "draft"]),
+        or(
+          isNull(schema.schoolSsoDomains.lastCheckedAt),
+          lt(schema.schoolSsoDomains.lastCheckedAt, dueBefore),
+        ),
+      ),
+    );
+  const verification = createDomainVerification({
+    label: SSO_DOMAIN_LABEL,
+    resolver: options.resolver ?? ssoDnsResolver(),
+  });
+  const result = { checked: 0, unverified: 0 };
+  for (const { domain, connection } of due) {
+    const proven = await verification.verifyOwnership(domain.domain, domain.verificationToken);
+    result.checked += 1;
+    if (proven) {
+      await db
+        .update(schema.schoolSsoDomains)
+        .set({ consecutiveCheckFailures: 0, lastCheckedAt: now })
+        .where(eq(schema.schoolSsoDomains.id, domain.id));
+      continue;
+    }
+    const failures = domain.consecutiveCheckFailures + 1;
+    const lapsed = failures >= DOMAIN_FAILURES_BEFORE_UNVERIFIED;
+    await db
+      .update(schema.schoolSsoDomains)
+      .set({
+        consecutiveCheckFailures: failures,
+        lastCheckedAt: now,
+        ...(lapsed ? { verifiedAt: null } : {}),
+      })
+      .where(eq(schema.schoolSsoDomains.id, domain.id));
+    if (!lapsed) continue;
+    result.unverified += 1;
+    const eventId = await recordSsoEvent(
+      db,
+      {
+        schoolId: connection.schoolId,
+        connectionId: connection.id,
+        action: "domain.lapsed",
+        reason: "txt_record_missing",
+        metadata: { domain: domain.domain },
+      },
+      clock,
+    );
+    await notifySsoOwner(
+      db,
+      {
+        schoolId: connection.schoolId,
+        subject: "An SSO domain is no longer verified",
+        lines: [
+          `We couldn't find the DNS record that proves you own ${domain.domain} on ${failures} checks in a row, so it is no longer verified.`,
+          "Until it's verified again, new learners from this domain can't sign in with single sign-on and enforcement for it stops. Add the record back and verify the domain again.",
+        ],
+        idempotencyKey: `sso-event:${eventId}`,
+      },
+      clock,
+    );
+  }
+  return result;
+}
+
+/**
+ * Starts the SSO background work on the worker: platform jobs every few
+ * seconds, and an hourly sweep that runs cleanup, the weekly domain re-check
+ * (self-limiting by `last_checked_at`) and the daily plan sync.
+ */
+export function startSsoJobs(options: {
+  db: AppDb;
+  billing: Billing;
+  clock: Clock;
+  logger: Logger;
+  onError?: (task: string, error: unknown) => void;
+}): () => void {
+  const { db, billing, clock, logger } = options;
+  const fail = (task: string, error: unknown) => {
+    logger.error(
+      { sso_task: task, error: error instanceof Error ? error.message : String(error) },
+      "SSO background task failed",
+    );
+    options.onError?.(task, error);
+  };
+  let stopped = false;
+  let jobsRunning = false;
+  let sweepRunning = false;
+  let lastPlanSync = 0;
+  const jobsTimer = setInterval(async () => {
+    if (jobsRunning || stopped) return;
+    jobsRunning = true;
+    try {
+      await processPlatformJobs(db, billing, clock, logger);
+    } catch (error) {
+      fail("platform_jobs", error);
+    } finally {
+      jobsRunning = false;
+    }
+  }, 5_000);
+  const sweep = async () => {
+    if (sweepRunning || stopped) return;
+    sweepRunning = true;
+    try {
+      await cleanupSsoRequests(db, clock);
+    } catch (error) {
+      fail("cleanup", error);
+    }
+    try {
+      await recheckSsoDomains(db, clock, { logger });
+    } catch (error) {
+      fail("domain_recheck", error);
+    }
+    try {
+      if (clock.now().getTime() - lastPlanSync >= 24 * 60 * 60 * 1000) {
+        await syncAllSsoPlanFeatures(db, billing, clock, logger);
+        lastPlanSync = clock.now().getTime();
+      }
+    } catch (error) {
+      fail("plan_sync", error);
+    }
+    sweepRunning = false;
+  };
+  // The first sweep runs a minute after start, never at boot.
+  const firstSweep = setTimeout(sweep, 60_000);
+  const sweepTimer = setInterval(sweep, 60 * 60 * 1000);
+  return () => {
+    stopped = true;
+    clearInterval(jobsTimer);
+    clearInterval(sweepTimer);
+    clearTimeout(firstSweep);
+  };
+}
diff --git a/apps/api/src/sso-protocol/certificates.ts b/apps/api/src/sso-protocol/certificates.ts
new file mode 100644
index 000000000..9745f6982
--- /dev/null
+++ b/apps/api/src/sso-protocol/certificates.ts
@@ -0,0 +1,26 @@
+import { X509Certificate } from "node:crypto";
+
+/** Bare base64 (no PEM armour, no whitespace) of a DER certificate, or null. */
+export function normalizeCertificate(input: string): string | null {
+  if (typeof input !== "string") {
+    return null;
+  }
+  const bare = input
+    .replace(/-----BEGIN CERTIFICATE-----/g, "")
+    .replace(/-----END CERTIFICATE-----/g, "")
+    .replace(/\s+/g, "");
+  if (!bare || !/^[A-Za-z0-9+/]+={0,2}$/.test(bare)) {
+    return null;
+  }
+  try {
+    new X509Certificate(toPem(bare));
+  } catch {
+    return null;
+  }
+  return bare;
+}
+
+export function toPem(bare: string): string {
+  const lines = bare.match(/.{1,64}/g) ?? [];
+  return `-----BEGIN CERTIFICATE-----\n${lines.join("\n")}\n-----END CERTIFICATE-----`;
+}
diff --git a/apps/api/src/sso-protocol/dom.ts b/apps/api/src/sso-protocol/dom.ts
new file mode 100644
index 000000000..857f3ca21
--- /dev/null
+++ b/apps/api/src/sso-protocol/dom.ts
@@ -0,0 +1,33 @@
+import { DOMParser } from "@xmldom/xmldom";
+
+/** The small part of the DOM this module reads. */
+export interface XmlNode {
+  nodeType: number;
+  localName: string | null;
+  namespaceURI: string | null;
+  textContent: string | null;
+  childNodes: { length: number; [index: number]: XmlNode };
+  getAttribute(name: string): string;
+  hasAttribute(name: string): boolean;
+}
+
+export interface XmlDocument extends XmlNode {
+  documentElement: XmlNode;
+}
+
+export function parseXmlDocument(xml: string): XmlDocument | null {
+  const fail = (message: string) => {
+    throw new Error(message);
+  };
+  try {
+    const document = new DOMParser({
+      errorHandler: { warning: () => {}, error: fail, fatalError: fail },
+    }).parseFromString(xml, "text/xml") as unknown as XmlDocument;
+    if (!document?.documentElement) {
+      return null;
+    }
+    return document;
+  } catch {
+    return null;
+  }
+}
diff --git a/apps/api/src/sso-protocol/index.ts b/apps/api/src/sso-protocol/index.ts
new file mode 100644
index 000000000..0ea653382
--- /dev/null
+++ b/apps/api/src/sso-protocol/index.ts
@@ -0,0 +1,11 @@
+export { createSamlServiceProvider } from "./saml.js";
+export { parseSamlIdpMetadata } from "./metadata.js";
+export { isSafeIdpUrl } from "./url.js";
+export type {
+  AssertionReplayStore,
+  SamlAssertion,
+  SamlConnectionConfig,
+  SamlFailureReason,
+  SamlValidationResult,
+  SsoRequestStore,
+} from "./types.js";
diff --git a/apps/api/src/sso-protocol/metadata.test.ts b/apps/api/src/sso-protocol/metadata.test.ts
new file mode 100644
index 000000000..82a859e42
--- /dev/null
+++ b/apps/api/src/sso-protocol/metadata.test.ts
@@ -0,0 +1,134 @@
+import { describe, expect, it } from "bun:test";
+import { parseSamlIdpMetadata } from "./metadata.js";
+import { attackerKeys, idpKeys, rotatedKeys } from "./test-idp.js";
+import { isSafeIdpUrl } from "./url.js";
+
+const bare = (pem: string) => pem.replace(/-----[A-Z ]+-----/g, "").replace(/\s+/g, "");
+const MD = "urn:oasis:names:tc:SAML:2.0:metadata";
+const REDIRECT = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect";
+const POST = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST";
+
+const key = (cert: string, use?: string) =>
+  `<md:KeyDescriptor${use ? ` use="${use}"` : ""}><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>${cert}</ds:X509Certificate></ds:X509Data></ds:KeyInfo></md:KeyDescriptor>`;
+
+const okta = (sso = "https://dev-1.okta.com/app/abc/sso/saml") =>
+  `<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="${MD}" entityID="http://www.okta.com/exk1">` +
+  `<md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">` +
+  key(`\n${bare(idpKeys.cert).match(/.{1,64}/g)?.join("\n")}\n`, "signing") +
+  `<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>` +
+  `<md:SingleSignOnService Binding="${POST}" Location="https://dev-1.okta.com/app/abc/sso/saml"/>` +
+  `<md:SingleSignOnService Binding="${REDIRECT}" Location="${sso}"/>` +
+  `</md:IDPSSODescriptor></md:EntityDescriptor>`;
+
+const entra =
+  `<EntityDescriptor xmlns="${MD}" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" ID="_x" entityID="https://sts.windows.net/tenant/">` +
+  `<ds:Signature><ds:SignedInfo/></ds:Signature>` +
+  `<IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">` +
+  `<KeyDescriptor use="signing"><ds:KeyInfo><ds:X509Data><ds:X509Certificate>${bare(idpKeys.cert)}</ds:X509Certificate></ds:X509Data></ds:KeyInfo></KeyDescriptor>` +
+  `<KeyDescriptor use="signing"><ds:KeyInfo><ds:X509Data><ds:X509Certificate>${bare(rotatedKeys.cert)}</ds:X509Certificate></ds:X509Data></ds:KeyInfo></KeyDescriptor>` +
+  `<KeyDescriptor use="signing"><ds:KeyInfo><ds:X509Data><ds:X509Certificate>${bare(idpKeys.cert)}</ds:X509Certificate></ds:X509Data></ds:KeyInfo></KeyDescriptor>` +
+  `<SingleLogoutService Binding="${REDIRECT}" Location="https://login.microsoftonline.com/tenant/saml2"/>` +
+  `<SingleSignOnService Binding="${REDIRECT}" Location="https://login.microsoftonline.com/tenant/saml2"/>` +
+  `<SingleSignOnService Binding="${POST}" Location="https://login.microsoftonline.com/tenant/saml2"/>` +
+  `</IDPSSODescriptor></EntityDescriptor>`;
+
+describe("parseSamlIdpMetadata", () => {
+  it("reads Okta-shaped metadata and strips certificate whitespace", () => {
+    expect(parseSamlIdpMetadata(okta())).toEqual({
+      ok: true,
+      entityId: "http://www.okta.com/exk1",
+      ssoUrl: "https://dev-1.okta.com/app/abc/sso/saml",
+      signingCertificates: [bare(idpKeys.cert)],
+    });
+  });
+
+  it("reads Entra-shaped default-namespace metadata, with several keys deduplicated", () => {
+    expect(parseSamlIdpMetadata(entra)).toEqual({
+      ok: true,
+      entityId: "https://sts.windows.net/tenant/",
+      ssoUrl: "https://login.microsoftonline.com/tenant/saml2",
+      signingCertificates: [bare(idpKeys.cert), bare(rotatedKeys.cert)],
+    });
+  });
+
+  it("accepts an EntitiesDescriptor holding one entity", () => {
+    const inner = okta().replace(/^<\?xml[^>]*\?>/, "");
+    const result = parseSamlIdpMetadata(`<md:EntitiesDescriptor xmlns:md="${MD}">${inner}</md:EntitiesDescriptor>`);
+    expect(result.ok).toBe(true);
+  });
+
+  it("ignores encryption-only certificates", () => {
+    const xml = okta().replace(
+      key(`\n${bare(idpKeys.cert).match(/.{1,64}/g)?.join("\n")}\n`, "signing"),
+      key(bare(attackerKeys.cert), "encryption") + key(bare(rotatedKeys.cert)),
+    );
+    const result = parseSamlIdpMetadata(xml);
+    expect(result.ok && result.signingCertificates).toEqual([bare(rotatedKeys.cert)]);
+  });
+
+  it("reports no signing certificate when only encryption keys exist", () => {
+    const xml = okta().replace(/use="signing"/, 'use="encryption"');
+    expect(parseSamlIdpMetadata(xml)).toEqual({ ok: false, reason: "no_signing_certificate" });
+  });
+
+  it("drops certificates that do not parse", () => {
+    const xml = okta().replace(/<ds:X509Certificate>[\s\S]*<\/ds:X509Certificate>/, "<ds:X509Certificate>AAAA</ds:X509Certificate>");
+    expect(parseSamlIdpMetadata(xml)).toEqual({ ok: false, reason: "no_signing_certificate" });
+  });
+
+  it("refuses an http SSO URL", () => {
+    expect(parseSamlIdpMetadata(okta("http://dev-1.okta.com/sso"))).toEqual({ ok: false, reason: "unsafe_sso_url" });
+  });
+
+  it("refuses an SSO URL with credentials", () => {
+    expect(parseSamlIdpMetadata(okta("https://user:pw@idp.example/sso"))).toEqual({ ok: false, reason: "unsafe_sso_url" });
+  });
+
+  it("requires the HTTP-Redirect binding", () => {
+    const xml = okta().replace(REDIRECT, POST);
+    expect(parseSamlIdpMetadata(xml)).toEqual({ ok: false, reason: "no_redirect_binding" });
+  });
+
+  it("refuses DTDs and entities", () => {
+    expect(parseSamlIdpMetadata(`<!DOCTYPE x [<!ENTITY e "v">]>${okta()}`)).toEqual({ ok: false, reason: "dtd_not_allowed" });
+    expect(parseSamlIdpMetadata(okta().replace("<md:IDPSSODescriptor", '<!ENTITY e "v"><md:IDPSSODescriptor'))).toEqual({ ok: false, reason: "dtd_not_allowed" });
+  });
+
+  it("refuses oversize metadata", () => {
+    expect(parseSamlIdpMetadata(`${okta()}<!--${"a".repeat(600 * 1024)}-->`)).toEqual({ ok: false, reason: "too_large" });
+  });
+
+  it("refuses malformed or unrelated documents", () => {
+    for (const xml of ["", "   ", "<a", "<root/>", `<md:EntityDescriptor xmlns:md="${MD}"/>`, `<md:EntityDescriptor xmlns:md="${MD}" entityID="x"/>`]) {
+      expect(parseSamlIdpMetadata(xml)).toEqual({ ok: false, reason: "invalid" });
+    }
+  });
+});
+
+describe("isSafeIdpUrl", () => {
+  it("accepts absolute https URLs", () => {
+    expect(isSafeIdpUrl("https://idp.example/sso")).toBe(true);
+    expect(isSafeIdpUrl("https://idp.example:8443/sso?x=1")).toBe(true);
+  });
+
+  it("refuses everything else", () => {
+    for (const value of [
+      "http://idp.example/sso",
+      "https://user@idp.example/sso",
+      "https://user:pw@idp.example/sso",
+      "//idp.example/sso",
+      "/sso",
+      "javascript:alert(1)",
+      "file:///etc/passwd",
+      "https://",
+      "https://idp.example/ sso",
+      "https://idp.example/sso\n",
+      "",
+      "not a url",
+    ]) {
+      expect(isSafeIdpUrl(value)).toBe(false);
+    }
+    expect(isSafeIdpUrl(undefined as unknown as string)).toBe(false);
+    expect(isSafeIdpUrl(`https://idp.example/${"a".repeat(3000)}`)).toBe(false);
+  });
+});
diff --git a/apps/api/src/sso-protocol/metadata.ts b/apps/api/src/sso-protocol/metadata.ts
new file mode 100644
index 000000000..73b1c45fd
--- /dev/null
+++ b/apps/api/src/sso-protocol/metadata.ts
@@ -0,0 +1,95 @@
+import { parseXmlDocument } from "./dom.js";
+import { normalizeCertificate } from "./certificates.js";
+import { isSafeIdpUrl } from "./url.js";
+import { NS, attribute, childElements, hasDtdOrEntity, text } from "./xml.js";
+
+export const MAX_IDP_METADATA_BYTES = 512 * 1024;
+
+const REDIRECT_BINDING = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect";
+
+export type SamlIdpMetadataResult =
+  | { ok: true; entityId: string; ssoUrl: string; signingCertificates: string[] }
+  | {
+      ok: false;
+      reason:
+        | "too_large"
+        | "dtd_not_allowed"
+        | "invalid"
+        | "no_redirect_binding"
+        | "unsafe_sso_url"
+        | "no_signing_certificate";
+    };
+
+/**
+ * Reads the entity id, HTTP-Redirect SSO URL and signing certificates from IdP
+ * metadata. The metadata itself is not signature-checked: the admin supplies
+ * it, and the certificates it names become pinned only once saved.
+ */
+export function parseSamlIdpMetadata(xml: string): SamlIdpMetadataResult {
+  if (typeof xml !== "string" || xml.trim().length === 0) {
+    return { ok: false, reason: "invalid" };
+  }
+  if (Buffer.byteLength(xml, "utf8") > MAX_IDP_METADATA_BYTES) {
+    return { ok: false, reason: "too_large" };
+  }
+  if (hasDtdOrEntity(xml)) {
+    return { ok: false, reason: "dtd_not_allowed" };
+  }
+  const document = parseXmlDocument(xml);
+  if (!document) {
+    return { ok: false, reason: "invalid" };
+  }
+
+  let entity = document.documentElement;
+  if (entity.localName === "EntitiesDescriptor" && entity.namespaceURI === NS.metadata) {
+    const entities = childElements(entity, "EntityDescriptor", NS.metadata);
+    if (entities.length !== 1) {
+      return { ok: false, reason: "invalid" };
+    }
+    entity = entities[0];
+  }
+  if (entity.localName !== "EntityDescriptor" || entity.namespaceURI !== NS.metadata) {
+    return { ok: false, reason: "invalid" };
+  }
+  const entityId = (attribute(entity, "entityID") ?? "").trim();
+  if (!entityId) {
+    return { ok: false, reason: "invalid" };
+  }
+  const idp = childElements(entity, "IDPSSODescriptor", NS.metadata)[0];
+  if (!idp) {
+    return { ok: false, reason: "invalid" };
+  }
+
+  const redirects = childElements(idp, "SingleSignOnService", NS.metadata).filter(
+    (service) => attribute(service, "Binding") === REDIRECT_BINDING,
+  );
+  if (redirects.length === 0) {
+    return { ok: false, reason: "no_redirect_binding" };
+  }
+  const ssoUrl = (attribute(redirects[0], "Location") ?? "").trim();
+  if (!isSafeIdpUrl(ssoUrl)) {
+    return { ok: false, reason: "unsafe_sso_url" };
+  }
+
+  const certificates: string[] = [];
+  for (const descriptor of childElements(idp, "KeyDescriptor", NS.metadata)) {
+    const use = attribute(descriptor, "use");
+    if (use !== null && use !== "signing") {
+      continue; // encryption-only keys never verify assertions
+    }
+    for (const keyInfo of childElements(descriptor, "KeyInfo", NS.dsig)) {
+      for (const data of childElements(keyInfo, "X509Data", NS.dsig)) {
+        for (const cert of childElements(data, "X509Certificate", NS.dsig)) {
+          const normalized = normalizeCertificate(text(cert));
+          if (normalized && !certificates.includes(normalized)) {
+            certificates.push(normalized);
+          }
+        }
+      }
+    }
+  }
+  if (certificates.length === 0) {
+    return { ok: false, reason: "no_signing_certificate" };
+  }
+  return { ok: true, entityId, ssoUrl, signingCertificates: certificates };
+}
diff --git a/apps/api/src/sso-protocol/saml.test.ts b/apps/api/src/sso-protocol/saml.test.ts
new file mode 100644
index 000000000..ed50e5c7e
--- /dev/null
+++ b/apps/api/src/sso-protocol/saml.test.ts
@@ -0,0 +1,555 @@
+import { describe, expect, it } from "bun:test";
+import { createSamlServiceProvider } from "./saml.js";
+import type { SamlConnectionConfig, SamlFailureReason } from "./types.js";
+import {
+  ACS_URL,
+  DIGEST_SHA1,
+  EMAIL_FORMAT,
+  MemoryReplayStore,
+  MemoryRequestStore,
+  OTHER_SP_ENTITY_ID,
+  PERSISTENT,
+  SIG_RSA_SHA1,
+  SP_ENTITY_ID,
+  TRANSIENT,
+  assertionXml,
+  attackerKeys,
+  b64,
+  baseConfig,
+  idpKeys,
+  iso,
+  newId,
+  responseXml,
+  rotatedKeys,
+  signRoot,
+  signedResponse,
+} from "./test-idp.js";
+
+const RELAY = "relay-token-1";
+
+async function run(
+  buildResponse: (requestId: string) => string,
+  options: {
+    config?: SamlConnectionConfig;
+    requests?: MemoryRequestStore;
+    replay?: MemoryReplayStore;
+    relayState?: string;
+    checkConnection?: () => Promise<boolean>;
+    now?: () => Date;
+    requestId?: string;
+  } = {},
+) {
+  const requestId = options.requestId ?? newId();
+  const requests = options.requests ?? new MemoryRequestStore();
+  if (!options.requests) {
+    requests.add(RELAY, requestId);
+  }
+  const replay = options.replay ?? new MemoryReplayStore();
+  const provider = createSamlServiceProvider(options.config ?? baseConfig(), {
+    now: options.now,
+  });
+  const result = await provider.validatePostResponse({
+    samlResponse: buildResponse(requestId),
+    relayState: options.relayState ?? RELAY,
+    requests,
+    replay,
+    checkConnection: options.checkConnection,
+  });
+  return { result, requests, replay, requestId };
+}
+
+async function expectReason(
+  reason: SamlFailureReason,
+  buildResponse: (requestId: string) => string,
+  options: Parameters<typeof run>[1] = {},
+) {
+  const { result, requests, replay } = await run(buildResponse, options);
+  expect(result).toEqual({ ok: false, reason });
+  return { requests, replay };
+}
+
+describe("validatePostResponse: accepted responses", () => {
+  it("accepts a signed assertion with a persistent NameID", async () => {
+    const { result, replay } = await run((id) =>
+      signedResponse(id, { nameId: "abc-123", attributes: {
+        email: ["Learner@Example.com"],
+        givenName: ["Lena"],
+        surname: ["Learner"],
+        groups: ["a", "b"],
+      } }),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.assertion.subject).toBe("abc-123");
+    expect(result.assertion.issuer).toBe("https://idp.example/entity");
+    expect(result.assertion.email).toBe("Learner@Example.com");
+    expect(result.assertion.name).toBe("Lena Learner");
+    expect(result.assertion.attributes.groups).toEqual(["a", "b"]);
+    expect(result.assertion.sessionNotOnOrAfter).toBeInstanceOf(Date);
+    expect(replay.seen.has(result.assertion.assertionId)).toBe(true);
+  });
+
+  it("uses the configured subject attribute instead of a transient NameID", async () => {
+    const { result } = await run(
+      (id) =>
+        signedResponse(id, {
+          nameIdFormat: TRANSIENT,
+          attributes: { employeeId: ["E-42"], mail: ["x@example.com"] },
+        }),
+      { config: baseConfig({ subjectAttribute: "employeeId" }) },
+    );
+    expect(result.ok && result.assertion.subject).toBe("E-42");
+    expect(result.ok && result.assertion.email).toBe("x@example.com");
+  });
+
+  it("reads the email and name claims Entra uses", async () => {
+    const claims = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims";
+    const { result } = await run((id) =>
+      signedResponse(id, {
+        attributes: { [`${claims}/emailaddress`]: ["e@example.com"], [`${claims}/name`]: ["E Name"] },
+      }),
+    );
+    expect(result.ok && result.assertion.email).toBe("e@example.com");
+    expect(result.ok && result.assertion.name).toBe("E Name");
+  });
+
+  it("returns a null email when the attribute is multi-valued", async () => {
+    const { result } = await run((id) =>
+      signedResponse(id, { attributes: { email: ["a@example.com", "b@example.com"] } }),
+    );
+    expect(result.ok && result.assertion.email).toBeNull();
+  });
+
+  it("accepts a rotated certificate when several are pinned", async () => {
+    const { result } = await run(
+      (id) => signedResponse(id, {}, {}, { keys: rotatedKeys }),
+      { config: baseConfig({ idpCertificates: [idpKeys.cert, rotatedKeys.cert] }) },
+    );
+    expect(result.ok).toBe(true);
+  });
+
+  it("accepts bare base64 certificates", async () => {
+    const bare = idpKeys.cert.replace(/-----[A-Z ]+-----/g, "").replace(/\s+/g, "");
+    const { result } = await run((id) => signedResponse(id), {
+      config: baseConfig({ idpCertificates: [bare] }),
+    });
+    expect(result.ok).toBe(true);
+  });
+
+  it("accepts a response whose Destination is absent", async () => {
+    const { result } = await run((id) => signedResponse(id, {}, { destination: null }));
+    expect(result.ok).toBe(true);
+  });
+
+  it("reports a null SessionNotOnOrAfter when the IdP sends none", async () => {
+    const { result } = await run((id) => signedResponse(id, { sessionNotOnOrAfter: null }));
+    expect(result.ok && result.assertion.sessionNotOnOrAfter).toBeNull();
+  });
+});
+
+describe("validatePostResponse: signature", () => {
+  it("rejects an unsigned assertion", async () => {
+    await expectReason("signature_invalid", (id) =>
+      b64(responseXml({ requestId: id, assertion: assertionXml(id) })),
+    );
+  });
+
+  it("rejects an assertion signed by the wrong certificate", async () => {
+    await expectReason("signature_invalid", (id) =>
+      signedResponse(id, {}, {}, { keys: attackerKeys }),
+    );
+  });
+
+  it("never trusts a certificate carried in KeyInfo", async () => {
+    await expectReason("signature_invalid", (id) =>
+      signedResponse(id, {}, {}, { keys: attackerKeys, keyInfoCert: attackerKeys.cert }),
+    );
+  });
+
+  it("rejects an assertion tampered with after signing", async () => {
+    await expectReason("signature_invalid", (id) => {
+      const signed = signRoot(assertionXml(id, { nameId: "victim" }), { keys: idpKeys }, "Assertion");
+      return b64(responseXml({ requestId: id, assertion: signed.replace("victim", "attacker") }));
+    });
+  });
+
+  it("rejects a signed Response that wraps an unsigned assertion", async () => {
+    await expectReason("signature_invalid", (id) => {
+      const unsigned = responseXml({ requestId: id, assertion: assertionXml(id) });
+      return b64(signRoot(unsigned, { keys: idpKeys }, "Response"));
+    });
+  });
+
+  it("rejects a SHA-1 signature even from the trusted key", async () => {
+    await expectReason("weak_algorithm", (id) =>
+      signedResponse(id, {}, {}, { keys: idpKeys, signatureAlgorithm: SIG_RSA_SHA1 }),
+    );
+  });
+
+  it("rejects a SHA-1 digest even from the trusted key", async () => {
+    await expectReason("weak_algorithm", (id) =>
+      signedResponse(id, {}, {}, { keys: idpKeys, digestAlgorithm: DIGEST_SHA1 }),
+    );
+  });
+
+  describe("signature wrapping", () => {
+    const evil = (id: string) => assertionXml(id, { nameId: "attacker-subject" });
+    const signedGood = (id: string) =>
+      signRoot(assertionXml(id, { nameId: "victim-subject" }), { keys: idpKeys }, "Assertion");
+
+    it("rejects an unsigned assertion placed next to a signed one", async () => {
+      await expectReason("signature_invalid", (id) =>
+        b64(responseXml({ requestId: id, assertion: evil(id) + signedGood(id) })),
+      );
+      await expectReason("signature_invalid", (id) =>
+        b64(responseXml({ requestId: id, assertion: signedGood(id) + evil(id) })),
+      );
+    });
+
+    it("rejects a signed assertion moved into Extensions behind an unsigned one", async () => {
+      await expectReason("signature_invalid", (id) =>
+        b64(
+          responseXml({
+            requestId: id,
+            extensions: `<samlp:Extensions>${signedGood(id)}</samlp:Extensions>`,
+            assertion: evil(id),
+          }),
+        ),
+      );
+    });
+
+    it("rejects an unsigned assertion that wraps the signed one in Advice", async () => {
+      await expectReason("signature_invalid", (id) => {
+        const wrapper = evil(id).replace(
+          "</saml:Issuer>",
+          `</saml:Issuer><saml:Advice>${signedGood(id)}</saml:Advice>`,
+        );
+        return b64(responseXml({ requestId: id, assertion: wrapper }));
+      });
+    });
+
+    it("rejects an unsigned assertion that reuses the signed assertion's ID", async () => {
+      await expectReason("signature_invalid", (id) => {
+        const good = assertionXml(id, { nameId: "victim-subject", id: "_sharedid" });
+        const signed = signRoot(good, { keys: idpKeys }, "Assertion");
+        const forged = assertionXml(id, { nameId: "attacker-subject", id: "_sharedid" });
+        return b64(responseXml({ requestId: id, extensions: `<samlp:Extensions>${signed}</samlp:Extensions>`, assertion: forged }));
+      });
+    });
+
+    it("rejects a signature lifted onto a forged assertion", async () => {
+      await expectReason("signature_invalid", (id) => {
+        const signed = signedGood(id);
+        const signature = signed.match(/<ds:Signature[\s\S]*<\/ds:Signature>/)?.[0] ?? "";
+        const forged = evil(id).replace("</saml:Issuer>", `</saml:Issuer>${signature}`);
+        return b64(responseXml({ requestId: id, assertion: forged }));
+      });
+    });
+  });
+});
+
+describe("validatePostResponse: assertion checks", () => {
+  it("rejects another connection's audience", async () => {
+    await expectReason("wrong_audience", (id) =>
+      signedResponse(id, { audience: OTHER_SP_ENTITY_ID }),
+    );
+  });
+
+  it("rejects the wrong Destination", async () => {
+    await expectReason("wrong_destination", (id) =>
+      signedResponse(id, {}, { destination: "https://school.example/learner-login/sso/conn_2/acs" }),
+    );
+  });
+
+  it("rejects the wrong Recipient", async () => {
+    await expectReason("wrong_recipient", (id) =>
+      signedResponse(id, { recipient: "https://evil.example/acs" }),
+    );
+  });
+
+  it("rejects a non-bearer subject confirmation", async () => {
+    await expectReason("wrong_recipient", (id) => signedResponse(id, { bearer: false }));
+  });
+
+  it("rejects an expired subject confirmation", async () => {
+    await expectReason("expired", (id) =>
+      signedResponse(id, { scdNotOnOrAfter: iso(-600_000) }),
+    );
+  });
+
+  it("rejects a subject confirmation that expires within the same assertion window only", async () => {
+    // Conditions still valid, confirmation expired: delivery window is bounded separately.
+    await expectReason("expired", (id) =>
+      signedResponse(id, { scdNotOnOrAfter: iso(-300_000), notOnOrAfter: iso(300_000) }),
+    );
+  });
+
+  it("rejects the wrong issuer", async () => {
+    await expectReason("wrong_issuer", (id) =>
+      signedResponse(id, { issuer: "https://evil.example/entity" }),
+    );
+  });
+
+  it("rejects an expired assertion", async () => {
+    await expectReason("expired", (id) =>
+      signedResponse(id, { notOnOrAfter: iso(-600_000), scdNotOnOrAfter: iso(-600_000) }),
+    );
+  });
+
+  it("tolerates two minutes of clock skew", async () => {
+    const { result } = await run((id) =>
+      signedResponse(id, { notOnOrAfter: iso(-60_000), scdNotOnOrAfter: iso(-60_000) }),
+    );
+    expect(result.ok).toBe(true);
+  });
+
+  it("rejects an assertion whose NotBefore is in the future", async () => {
+    await expectReason("not_yet_valid", (id) =>
+      signedResponse(id, { notBefore: iso(600_000) }),
+    );
+  });
+
+  it("applies the injected clock to its own checks", async () => {
+    await expectReason("expired", (id) => signedResponse(id), {
+      now: () => new Date(Date.now() + 3_600_000),
+    });
+  });
+
+  it("rejects a Response that reports a failed status, with or without an assertion", async () => {
+    const responder = "urn:oasis:names:tc:SAML:2.0:status:Responder";
+    await expectReason("status_not_success", (id) =>
+      b64(responseXml({ requestId: id, statusValue: responder })),
+    );
+    await expectReason("status_not_success", (id) =>
+      signedResponse(id, {}, { statusValue: responder }),
+    );
+  });
+
+  it("rejects an assertion whose InResponseTo names another request", async () => {
+    await expectReason("in_response_to_mismatch", (id) =>
+      signedResponse(id, { inResponseTo: newId() }),
+    );
+  });
+
+  it("rejects a Response whose InResponseTo names another request", async () => {
+    await expectReason("in_response_to_mismatch", (id) =>
+      signedResponse(id, {}, { responseInResponseTo: newId() }),
+    );
+  });
+
+  it("rejects an IdP-initiated response with no InResponseTo", async () => {
+    await expectReason("in_response_to_mismatch", (id) =>
+      signedResponse(id, { inResponseTo: null }, { responseInResponseTo: null }),
+    );
+  });
+
+  it("rejects an EncryptedAssertion it cannot read", async () => {
+    await expectReason("invalid_response", (id) =>
+      b64(
+        responseXml({
+          requestId: id,
+          assertion: "<saml:EncryptedAssertion><xenc:EncryptedData xmlns:xenc=\"http://www.w3.org/2001/04/xmlenc#\"/></saml:EncryptedAssertion>",
+        }),
+      ),
+    );
+  });
+});
+
+describe("validatePostResponse: request, replay and input handling", () => {
+  it("rejects an unknown RelayState before looking at the response", async () => {
+    const requests = new MemoryRequestStore();
+    await expectReason("request_not_found", (id) => signedResponse(id), { requests });
+  });
+
+  it("rejects an empty RelayState", async () => {
+    await expectReason("request_not_found", (id) => signedResponse(id), { relayState: "" });
+  });
+
+  it("rejects a request that was already used and leaves it unusable", async () => {
+    const requests = new MemoryRequestStore();
+    const requestId = newId();
+    requests.add(RELAY, requestId);
+    const replay = new MemoryReplayStore();
+    const first = await run((id) => signedResponse(id), { requests, replay, requestId });
+    expect(first.result.ok).toBe(true);
+    // The store no longer reports it open, so a second delivery stops at lookup.
+    const second = await run((id) => signedResponse(id), { requests, replay, requestId });
+    expect(second.result).toEqual({ ok: false, reason: "request_not_found" });
+  });
+
+  it("maps a lost race on the request to request_already_used", async () => {
+    const requestId = newId();
+    const racing = {
+      async findOpen() {
+        return { requestId };
+      },
+      async consume() {
+        return false;
+      },
+    };
+    const provider = createSamlServiceProvider(baseConfig());
+    const replay = new MemoryReplayStore();
+    const result = await provider.validatePostResponse({
+      samlResponse: signedResponse(requestId),
+      relayState: RELAY,
+      requests: racing,
+      replay,
+    });
+    expect(result).toEqual({ ok: false, reason: "request_already_used" });
+    expect(replay.seen.size).toBe(0);
+  });
+
+  it("rejects a replayed assertion ID", async () => {
+    const requestId = newId();
+    const replay = new MemoryReplayStore();
+    const response = signedResponse(requestId, { id: "_fixedassertion" });
+    const a = new MemoryRequestStore();
+    a.add(RELAY, requestId);
+    const b = new MemoryRequestStore();
+    b.add(RELAY, requestId);
+    const first = await run(() => response, { requests: a, replay, requestId });
+    expect(first.result.ok).toBe(true);
+    const second = await run(() => response, { requests: b, replay, requestId });
+    expect(second.result).toEqual({ ok: false, reason: "replayed_assertion" });
+  });
+
+  it("does not use up the request when the signature is invalid", async () => {
+    const requests = new MemoryRequestStore();
+    const requestId = newId();
+    requests.add(RELAY, requestId);
+    await run((id) => signedResponse(id, {}, {}, { keys: attackerKeys }), { requests, requestId });
+    expect(requests.consumeCalls).toBe(0);
+    expect(await requests.findOpen(RELAY)).toEqual({ requestId });
+  });
+
+  it("rejects a DOCTYPE or entity declaration", async () => {
+    await expectReason("dtd_not_allowed", (id) =>
+      b64(`<!DOCTYPE foo [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>${responseXml({ requestId: id })}`),
+    );
+    await expectReason("dtd_not_allowed", (id) =>
+      b64(responseXml({ requestId: id }).replace("<samlp:Status>", '<!ENTITY a "b"><samlp:Status>')),
+    );
+  });
+
+  it("rejects a UTF-16 document that would hide a DOCTYPE from the check", async () => {
+    await expectReason("invalid_response", (id) =>
+      Buffer.from(
+        `<!DOCTYPE foo [<!ENTITY x "y">]>${responseXml({ requestId: id })}`,
+        "utf16le",
+      ).toString("base64"),
+    );
+  });
+
+  it("rejects a body over 256 KB before decoding it", async () => {
+    await expectReason("response_too_large", () => "A".repeat(256 * 1024 + 1));
+  });
+
+  it("rejects malformed input without throwing", async () => {
+    await expectReason("invalid_response", () => "");
+    await expectReason("invalid_response", () => "not base64 !!!");
+    await expectReason("invalid_response", () => b64("<not-closed"));
+    await expectReason("invalid_response", () => b64("<a/>"));
+  });
+
+  it("rejects when the connection is no longer usable, before validating the signature", async () => {
+    let called = 0;
+    await expectReason("connection_unavailable", (id) => signedResponse(id), {
+      checkConnection: async () => {
+        called++;
+        return false;
+      },
+    });
+    expect(called).toBe(1);
+  });
+
+  it("does not call checkConnection when the request is unknown", async () => {
+    let called = 0;
+    await expectReason("request_not_found", (id) => signedResponse(id), {
+      requests: new MemoryRequestStore(),
+      checkConnection: async () => {
+        called++;
+        return true;
+      },
+    });
+    expect(called).toBe(0);
+  });
+
+  it("treats a connection with no usable certificate as unavailable", async () => {
+    await expectReason("connection_unavailable", (id) => signedResponse(id), {
+      config: baseConfig({ idpCertificates: ["not a certificate"] }),
+    });
+  });
+});
+
+describe("validatePostResponse: subject", () => {
+  it("rejects a transient NameID without a subject attribute", async () => {
+    await expectReason("unstable_subject", (id) => signedResponse(id, { nameIdFormat: TRANSIENT }));
+  });
+
+  it("rejects an email NameID without a subject attribute", async () => {
+    await expectReason("unstable_subject", (id) =>
+      signedResponse(id, { nameIdFormat: EMAIL_FORMAT, nameId: "x@example.com" }),
+    );
+  });
+
+  it("ignores the NameID when a subject attribute is configured but absent", async () => {
+    await expectReason("missing_subject", (id) => signedResponse(id), {
+      config: baseConfig({ subjectAttribute: "employeeId" }),
+    });
+  });
+
+  it("rejects a subject attribute with several values", async () => {
+    await expectReason("missing_subject", (id) => signedResponse(id, { attributes: { employeeId: ["a", "b"] } }), {
+      config: baseConfig({ subjectAttribute: "employeeId" }),
+    });
+  });
+
+  it("rejects an empty persistent NameID", async () => {
+    await expectReason("missing_subject", (id) => signedResponse(id, { nameId: "  ", nameIdFormat: PERSISTENT }));
+  });
+
+  it("does not consume the request or record the assertion when the subject is unusable", async () => {
+    const { requests, replay } = await expectReason("unstable_subject", (id) =>
+      signedResponse(id, { nameIdFormat: TRANSIENT }),
+    );
+    expect(requests.consumeCalls).toBe(0);
+    expect(replay.seen.size).toBe(0);
+  });
+});
+
+describe("buildAuthnRequestUrl", () => {
+  it("builds a redirect to the IdP carrying the RelayState and a fresh request id", async () => {
+    const provider = createSamlServiceProvider(baseConfig());
+    const a = await provider.buildAuthnRequestUrl({ relayState: "tok-1" });
+    const b = await provider.buildAuthnRequestUrl({ relayState: "tok-2" });
+    const url = new URL(a.url);
+    expect(url.origin + url.pathname).toBe("https://idp.example/sso");
+    expect(url.searchParams.get("RelayState")).toBe("tok-1");
+    expect(url.searchParams.get("SAMLRequest")).toBeTruthy();
+    expect(a.requestId).toMatch(/^_[0-9a-f]{40}$/);
+    expect(a.requestId).not.toBe(b.requestId);
+    const inflated = (await import("node:zlib"))
+      .inflateRawSync(Buffer.from(url.searchParams.get("SAMLRequest") ?? "", "base64"))
+      .toString("utf8");
+    expect(inflated).toContain(`ID="${a.requestId}"`);
+    expect(inflated).toContain(ACS_URL);
+    expect(inflated).toContain(SP_ENTITY_ID);
+  });
+
+  it("refuses an unsafe IdP URL", async () => {
+    const provider = createSamlServiceProvider(baseConfig({ idpSsoUrl: "http://idp.example/sso" }));
+    await expect(provider.buildAuthnRequestUrl({ relayState: "x" })).rejects.toThrow();
+  });
+});
+
+describe("serviceProviderMetadata", () => {
+  it("names the entity id and the ACS URL, escaped", () => {
+    const xml = createSamlServiceProvider(
+      baseConfig({ acsUrl: "https://school.example/acs?a=1&b=2" }),
+    ).serviceProviderMetadata();
+    expect(xml).toContain(`entityID="${SP_ENTITY_ID}"`);
+    expect(xml).toContain('Location="https://school.example/acs?a=1&amp;b=2"');
+    expect(xml).toContain('WantAssertionsSigned="true"');
+    expect(xml).toContain(PERSISTENT);
+  });
+});
diff --git a/apps/api/src/sso-protocol/saml.ts b/apps/api/src/sso-protocol/saml.ts
new file mode 100644
index 000000000..ed7d21e47
--- /dev/null
+++ b/apps/api/src/sso-protocol/saml.ts
@@ -0,0 +1,499 @@
+import { randomBytes } from "node:crypto";
+import { SAML, SamlStatusError, ValidateInResponseTo } from "@node-saml/node-saml";
+import { normalizeCertificate, toPem } from "./certificates.js";
+import { type XmlDocument, type XmlNode, parseXmlDocument } from "./dom.js";
+import { isSafeIdpUrl } from "./url.js";
+import type {
+  SamlAssertion,
+  SamlConnectionConfig,
+  SamlFailureReason,
+  SamlServiceProvider,
+} from "./types.js";
+import {
+  NS,
+  attribute,
+  childElements,
+  descendantElements,
+  escapeXml,
+  hasDtdOrEntity,
+  parseDateTime,
+  text,
+} from "./xml.js";
+
+export const MAX_SAML_RESPONSE_BASE64_LENGTH = 256 * 1024;
+export const CLOCK_SKEW_MS = 120_000;
+
+const PERSISTENT = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent";
+const BEARER = "urn:oasis:names:tc:SAML:2.0:cm:bearer";
+const STATUS_SUCCESS = "urn:oasis:names:tc:SAML:2.0:status:Success";
+
+/** Anything not listed here (SHA-1, MD5, HMAC, unknown) is refused. */
+const ALLOWED_SIGNATURE_ALGORITHMS = new Set([
+  "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
+  "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512",
+]);
+const ALLOWED_DIGEST_ALGORITHMS = new Set([
+  "http://www.w3.org/2001/04/xmlenc#sha256",
+  "http://www.w3.org/2001/04/xmlenc#sha512",
+]);
+
+const EMAIL_ATTRIBUTES = [
+  "email",
+  "mail",
+  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+];
+const DISPLAY_NAME_ATTRIBUTES = [
+  "displayName",
+  "name",
+  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
+];
+const GIVEN_NAME_ATTRIBUTES = [
+  "givenName",
+  "firstName",
+  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
+];
+const SURNAME_ATTRIBUTES = [
+  "surname",
+  "sn",
+  "lastName",
+  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
+];
+
+type Fail = { ok: false; reason: SamlFailureReason };
+const fail = (reason: SamlFailureReason): Fail => ({ ok: false, reason });
+
+function createSaml(
+  config: SamlConnectionConfig,
+  certificates: string[],
+  generateUniqueId?: () => string,
+): SAML {
+  return new SAML({
+    callbackUrl: config.acsUrl,
+    entryPoint: config.idpSsoUrl,
+    issuer: config.spEntityId,
+    audience: config.spEntityId,
+    idpIssuer: config.idpEntityId,
+    idpCert: certificates.map(toPem),
+    wantAssertionsSigned: true,
+    wantAuthnResponseSigned: false,
+    signatureAlgorithm: "sha256",
+    digestAlgorithm: "sha256",
+    acceptedClockSkewMs: CLOCK_SKEW_MS,
+    identifierFormat: PERSISTENT,
+    disableRequestedAuthnContext: true,
+    // InResponseTo is bound to our own stores and checked in this module,
+    // against the signed SubjectConfirmationData.
+    validateInResponseTo: ValidateInResponseTo.never,
+    rejectReplayedAssertions: false,
+    ...(generateUniqueId ? { generateUniqueId } : {}),
+  });
+}
+
+function usableCertificates(config: SamlConnectionConfig): string[] {
+  const out: string[] = [];
+  for (const raw of config.idpCertificates ?? []) {
+    const bare = normalizeCertificate(raw);
+    if (bare && !out.includes(bare)) {
+      out.push(bare);
+    }
+  }
+  return out;
+}
+
+function decodeResponse(samlResponse: unknown): { xml: string } | Fail {
+  if (typeof samlResponse !== "string" || samlResponse.length === 0) {
+    return fail("invalid_response");
+  }
+  if (samlResponse.length > MAX_SAML_RESPONSE_BASE64_LENGTH) {
+    return fail("response_too_large");
+  }
+  if (!/^[A-Za-z0-9+/=\s]+$/.test(samlResponse)) {
+    return fail("invalid_response");
+  }
+  const xml = Buffer.from(samlResponse, "base64").toString("utf8");
+  // Only plain UTF-8 XML. A UTF-16 (or otherwise encoded) document would hide
+  // a DOCTYPE from the check below, so anything with NUL bytes or not
+  // starting with markup is refused outright.
+  if (xml.includes("\u0000") || !/^?\s*</.test(xml)) {
+    return fail("invalid_response");
+  }
+  if (hasDtdOrEntity(xml)) {
+    return fail("dtd_not_allowed");
+  }
+  return { xml };
+}
+
+/** Every signature in the message must use SHA-2 for both signing and digest. */
+function hasWeakAlgorithm(document: XmlDocument): boolean {
+  for (const signature of descendantElements(document.documentElement, "Signature", NS.dsig)) {
+    const signedInfo = childElements(signature, "SignedInfo", NS.dsig)[0];
+    if (!signedInfo) {
+      return true;
+    }
+    const method = childElements(signedInfo, "SignatureMethod", NS.dsig)[0];
+    if (!method || !ALLOWED_SIGNATURE_ALGORITHMS.has(attribute(method, "Algorithm") ?? "")) {
+      return true;
+    }
+    const references = childElements(signedInfo, "Reference", NS.dsig);
+    if (references.length === 0) {
+      return true;
+    }
+    for (const reference of references) {
+      const digest = childElements(reference, "DigestMethod", NS.dsig)[0];
+      if (!digest || !ALLOWED_DIGEST_ALGORITHMS.has(attribute(digest, "Algorithm") ?? "")) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function mapLibraryError(error: unknown): SamlFailureReason {
+  if (error instanceof SamlStatusError) {
+    return "status_not_success";
+  }
+  const message = error instanceof Error ? error.message : "";
+  if (/not yet valid/i.test(message)) return "not_yet_valid";
+  if (/expired|too old|No valid subject confirmation/i.test(message)) return "expired";
+  if (/audience/i.test(message)) return "wrong_audience";
+  if (/issuer/i.test(message)) return "wrong_issuer";
+  if (/signature/i.test(message)) return "signature_invalid";
+  return "invalid_response";
+}
+
+function readAttributes(assertion: XmlNode): Record<string, string[]> {
+  const merged = new Map<string, string[]>();
+  for (const statement of childElements(assertion, "AttributeStatement", NS.assertion)) {
+    for (const attr of childElements(statement, "Attribute", NS.assertion)) {
+      const name = attribute(attr, "Name");
+      if (!name) {
+        continue;
+      }
+      const values = merged.get(name) ?? [];
+      for (const value of childElements(attr, "AttributeValue", NS.assertion)) {
+        const content = text(value);
+        if (content) {
+          values.push(content);
+        }
+      }
+      merged.set(name, values);
+    }
+  }
+  return Object.fromEntries(merged);
+}
+
+function firstSingle(attributes: Record<string, string[]>, names: string[]): string | null {
+  for (const name of names) {
+    if (Object.hasOwn(attributes, name) && attributes[name].length === 1) {
+      return attributes[name][0];
+    }
+  }
+  return null;
+}
+
+function readName(attributes: Record<string, string[]>): string | null {
+  const display = firstSingle(attributes, DISPLAY_NAME_ATTRIBUTES);
+  if (display) {
+    return display;
+  }
+  const given = firstSingle(attributes, GIVEN_NAME_ATTRIBUTES);
+  const surname = firstSingle(attributes, SURNAME_ATTRIBUTES);
+  const joined = [given, surname].filter(Boolean).join(" ");
+  return joined || null;
+}
+
+type Checked = {
+  assertion: XmlNode;
+  assertionId: string;
+  issuer: string;
+  replayExpiresAt: Date;
+  sessionNotOnOrAfter: Date | null;
+};
+
+/**
+ * Checks on the signed assertion (the bytes the signature covers, not the
+ * received document), plus the few unsigned Response attributes that are
+ * checked as defence in depth.
+ */
+function checkSignedAssertion(
+  config: SamlConnectionConfig,
+  received: XmlDocument,
+  assertionXml: string,
+  requestId: string,
+  now: Date,
+): Checked | Fail {
+  const root = received.documentElement;
+  if (root.localName !== "Response" || root.namespaceURI !== NS.protocol) {
+    return fail("invalid_response");
+  }
+
+  const status = childElements(root, "Status", NS.protocol)[0];
+  const statusCode = status ? childElements(status, "StatusCode", NS.protocol)[0] : undefined;
+  if (!statusCode) {
+    return fail("invalid_response");
+  }
+  if (attribute(statusCode, "Value") !== STATUS_SUCCESS) {
+    return fail("status_not_success");
+  }
+
+  const destination = attribute(root, "Destination");
+  if (destination !== null && destination !== config.acsUrl) {
+    return fail("wrong_destination");
+  }
+
+  const document = parseXmlDocument(assertionXml);
+  const assertion = document?.documentElement;
+  if (assertion?.localName !== "Assertion" || assertion.namespaceURI !== NS.assertion) {
+    return fail("invalid_response");
+  }
+  const assertionId = attribute(assertion, "ID");
+  if (!assertionId) {
+    return fail("invalid_response");
+  }
+
+  const issuers = childElements(assertion, "Issuer", NS.assertion);
+  if (issuers.length !== 1 || text(issuers[0]) !== config.idpEntityId) {
+    return fail("wrong_issuer");
+  }
+
+  const nowMs = now.getTime();
+  const conditionsList = childElements(assertion, "Conditions", NS.assertion);
+  if (conditionsList.length !== 1) {
+    return fail("wrong_audience");
+  }
+  const conditions = conditionsList[0];
+  const restrictions = childElements(conditions, "AudienceRestriction", NS.assertion);
+  const audienceOk =
+    restrictions.length > 0 &&
+    restrictions.every((restriction) =>
+      childElements(restriction, "Audience", NS.assertion).some(
+        (audience) => text(audience) === config.spEntityId,
+      ),
+    );
+  if (!audienceOk) {
+    return fail("wrong_audience");
+  }
+  let conditionsNotOnOrAfter: Date | null = null;
+  const conditionsNotBefore = attribute(conditions, "NotBefore");
+  if (conditionsNotBefore !== null) {
+    const notBefore = parseDateTime(conditionsNotBefore);
+    if (!notBefore) return fail("invalid_response");
+    if (nowMs + CLOCK_SKEW_MS < notBefore.getTime()) return fail("not_yet_valid");
+  }
+  const conditionsEnd = attribute(conditions, "NotOnOrAfter");
+  if (conditionsEnd !== null) {
+    conditionsNotOnOrAfter = parseDateTime(conditionsEnd);
+    if (!conditionsNotOnOrAfter) return fail("invalid_response");
+    if (nowMs - CLOCK_SKEW_MS >= conditionsNotOnOrAfter.getTime()) return fail("expired");
+  }
+
+  const subjects = childElements(assertion, "Subject", NS.assertion);
+  if (subjects.length !== 1) {
+    return fail("missing_subject");
+  }
+  let firstRejection: SamlFailureReason | null = null;
+  let confirmedUntil: Date | null = null;
+  for (const confirmation of childElements(subjects[0], "SubjectConfirmation", NS.assertion)) {
+    if (attribute(confirmation, "Method") !== BEARER) {
+      continue;
+    }
+    const data = childElements(confirmation, "SubjectConfirmationData", NS.assertion)[0];
+    if (!data || attribute(data, "Recipient") !== config.acsUrl) {
+      firstRejection ??= "wrong_recipient";
+      continue;
+    }
+    const end = parseDateTime(attribute(data, "NotOnOrAfter"));
+    if (!end) {
+      firstRejection ??= "invalid_response";
+      continue;
+    }
+    if (nowMs - CLOCK_SKEW_MS >= end.getTime()) {
+      firstRejection ??= "expired";
+      continue;
+    }
+    const start = attribute(data, "NotBefore");
+    if (start !== null) {
+      const notBefore = parseDateTime(start);
+      if (!notBefore || nowMs + CLOCK_SKEW_MS < notBefore.getTime()) {
+        firstRejection ??= notBefore ? "not_yet_valid" : "invalid_response";
+        continue;
+      }
+    }
+    if (attribute(data, "InResponseTo") !== requestId) {
+      firstRejection ??= "in_response_to_mismatch";
+      continue;
+    }
+    confirmedUntil = end;
+    break;
+  }
+  if (!confirmedUntil) {
+    return fail(firstRejection ?? "wrong_recipient");
+  }
+  // The Response's own InResponseTo is unsigned; it can only add a refusal.
+  const responseInResponseTo = attribute(root, "InResponseTo");
+  if (responseInResponseTo !== null && responseInResponseTo !== requestId) {
+    return fail("in_response_to_mismatch");
+  }
+
+  let sessionNotOnOrAfter: Date | null = null;
+  const authnStatements = childElements(assertion, "AuthnStatement", NS.assertion);
+  const sessionEnd = authnStatements[0] ? attribute(authnStatements[0], "SessionNotOnOrAfter") : null;
+  if (sessionEnd !== null) {
+    sessionNotOnOrAfter = parseDateTime(sessionEnd);
+    if (!sessionNotOnOrAfter) return fail("invalid_response");
+  }
+
+  const latest =
+    conditionsNotOnOrAfter && conditionsNotOnOrAfter.getTime() > confirmedUntil.getTime()
+      ? conditionsNotOnOrAfter
+      : confirmedUntil;
+  return {
+    assertion,
+    assertionId,
+    issuer: text(issuers[0]),
+    // Keep the ID on record for as long as the assertion could still be accepted.
+    replayExpiresAt: new Date(latest.getTime() + CLOCK_SKEW_MS),
+    sessionNotOnOrAfter,
+  };
+}
+
+function readSubject(
+  config: SamlConnectionConfig,
+  assertion: XmlNode,
+  attributes: Record<string, string[]>,
+): { subject: string } | Fail {
+  if (config.subjectAttribute) {
+    const values = Object.hasOwn(attributes, config.subjectAttribute)
+      ? attributes[config.subjectAttribute]
+      : [];
+    return values.length === 1 && values[0] ? { subject: values[0] } : fail("missing_subject");
+  }
+  const subject = childElements(assertion, "Subject", NS.assertion)[0];
+  const nameIds = subject ? childElements(subject, "NameID", NS.assertion) : [];
+  if (nameIds.length !== 1 || !text(nameIds[0])) {
+    return fail("missing_subject");
+  }
+  if (attribute(nameIds[0], "Format") !== PERSISTENT) {
+    return fail("unstable_subject");
+  }
+  return { subject: text(nameIds[0]) };
+}
+
+export function createSamlServiceProvider(
+  config: SamlConnectionConfig,
+  options: { now?: () => Date } = {},
+): SamlServiceProvider {
+  const now = options.now ?? (() => new Date());
+
+  return {
+    async buildAuthnRequestUrl({ relayState }) {
+      if (!isSafeIdpUrl(config.idpSsoUrl)) {
+        throw new Error("The identity provider SSO URL is not a safe https URL");
+      }
+      const certificates = usableCertificates(config);
+      if (certificates.length === 0) {
+        throw new Error("The connection has no usable identity provider certificate");
+      }
+      const requestId = `_${randomBytes(20).toString("hex")}`;
+      const saml = createSaml(config, certificates, () => requestId);
+      const url = await saml.getAuthorizeUrlAsync(relayState, undefined, {});
+      return { url, requestId };
+    },
+
+    async validatePostResponse({ samlResponse, relayState, requests, replay, checkConnection }) {
+      // 1. size, encoding, DTD
+      const decoded = decodeResponse(samlResponse);
+      if ("ok" in decoded) {
+        return decoded;
+      }
+
+      // 2. the request this response answers
+      if (typeof relayState !== "string" || relayState.length === 0) {
+        return fail("request_not_found");
+      }
+      const open = await requests.findOpen(relayState);
+      if (!open) {
+        return fail("request_not_found");
+      }
+
+      // 3. the connection is still usable
+      if (checkConnection && !(await checkConnection())) {
+        return fail("connection_unavailable");
+      }
+      const certificates = usableCertificates(config);
+      if (certificates.length === 0) {
+        return fail("connection_unavailable");
+      }
+
+      // 4. signature and the checks node-saml makes
+      const received = parseXmlDocument(decoded.xml);
+      if (!received) {
+        return fail("invalid_response");
+      }
+      const receivedRoot = received.documentElement;
+      if (receivedRoot.localName !== "Response" || receivedRoot.namespaceURI !== NS.protocol) {
+        return fail("invalid_response");
+      }
+      if (hasWeakAlgorithm(received)) {
+        return fail("weak_algorithm");
+      }
+      let assertionXml: string;
+      try {
+        const { profile } = await createSaml(config, certificates).validatePostResponseAsync({
+          SAMLResponse: samlResponse.replace(/\s+/g, ""),
+        });
+        if (!profile) {
+          return fail("status_not_success");
+        }
+        if (typeof profile.getAssertionXml !== "function") {
+          return fail("invalid_response");
+        }
+        assertionXml = profile.getAssertionXml();
+      } catch (error) {
+        return fail(mapLibraryError(error));
+      }
+
+      // 5. our own checks, on the signed assertion only
+      const checked = checkSignedAssertion(config, received, assertionXml, open.requestId, now());
+      if ("ok" in checked) {
+        return checked;
+      }
+      const attributes = readAttributes(checked.assertion);
+      const subject = readSubject(config, checked.assertion, attributes);
+      if ("ok" in subject) {
+        return subject;
+      }
+
+      // 6. use up the request, 7. remember the assertion
+      if (!(await requests.consume(relayState, open.requestId))) {
+        return fail("request_already_used");
+      }
+      if (!(await replay.remember(checked.assertionId, checked.replayExpiresAt))) {
+        return fail("replayed_assertion");
+      }
+
+      const assertion: SamlAssertion = {
+        issuer: checked.issuer,
+        assertionId: checked.assertionId,
+        subject: subject.subject,
+        email: firstSingle(attributes, EMAIL_ATTRIBUTES),
+        name: readName(attributes),
+        attributes,
+        sessionNotOnOrAfter: checked.sessionNotOnOrAfter,
+      };
+      return { ok: true, assertion };
+    },
+
+    serviceProviderMetadata() {
+      return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<md:EntityDescriptor xmlns:md="${NS.metadata}" entityID="${escapeXml(config.spEntityId)}">`,
+        `<md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="${NS.protocol}">`,
+        `<md:NameIDFormat>${PERSISTENT}</md:NameIDFormat>`,
+        `<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="${escapeXml(config.acsUrl)}" index="0" isDefault="true"/>`,
+        "</md:SPSSODescriptor>",
+        "</md:EntityDescriptor>",
+      ].join("");
+    },
+  };
+}
diff --git a/apps/api/src/sso-protocol/test-idp.ts b/apps/api/src/sso-protocol/test-idp.ts
new file mode 100644
index 000000000..d58d2de14
--- /dev/null
+++ b/apps/api/src/sso-protocol/test-idp.ts
@@ -0,0 +1,220 @@
+// Fixture identity provider for the sso-protocol tests. Its key pairs are
+// made fresh for each test run with openssl, so no private key is committed
+// and none is trusted anywhere outside these tests.
+import { randomBytes } from "node:crypto";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SignedXml } from "xml-crypto";
+import type {
+  AssertionReplayStore,
+  SamlConnectionConfig,
+  SsoRequestStore,
+} from "./types.js";
+
+export type KeyPair = { key: string; cert: string };
+
+/** A self-signed RSA-2048 key pair, like the certificates IdPs publish. */
+function generateKeyPair(commonName: string): KeyPair {
+  const dir = mkdtempSync(join(tmpdir(), "courselit-test-idp-"));
+  try {
+    const key = join(dir, "key.pem");
+    const cert = join(dir, "cert.pem");
+    const result = Bun.spawnSync(
+      ["openssl", "req", "-x509", "-newkey", "rsa:2048", "-nodes", "-sha256", "-days", "2",
+        "-subj", `/CN=${commonName}`, "-keyout", key, "-out", cert],
+      { stdout: "ignore", stderr: "pipe" },
+    );
+    if (!result.success) {
+      throw new Error(`openssl couldn't make a test key pair: ${result.stderr.toString()}`);
+    }
+    return { key: readFileSync(key, "utf8"), cert: readFileSync(cert, "utf8") };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export const idpKeys = generateKeyPair("test-idp.example");
+export const rotatedKeys = generateKeyPair("test-idp-rotated.example");
+export const attackerKeys = generateKeyPair("test-attacker.example");
+
+export const SIG_RSA_SHA256 = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256";
+export const SIG_RSA_SHA1 = "http://www.w3.org/2000/09/xmldsig#rsa-sha1";
+export const DIGEST_SHA256 = "http://www.w3.org/2001/04/xmlenc#sha256";
+export const DIGEST_SHA1 = "http://www.w3.org/2000/09/xmldsig#sha1";
+export const PERSISTENT = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent";
+export const TRANSIENT = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient";
+export const EMAIL_FORMAT = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress";
+
+export const SP_ENTITY_ID = "https://school.example/learner-login/sso/conn_1/metadata";
+export const OTHER_SP_ENTITY_ID = "https://school.example/learner-login/sso/conn_2/metadata";
+export const ACS_URL = "https://school.example/learner-login/sso/conn_1/acs";
+export const IDP_ENTITY_ID = "https://idp.example/entity";
+export const IDP_SSO_URL = "https://idp.example/sso";
+
+export const baseConfig = (overrides: Partial<SamlConnectionConfig> = {}): SamlConnectionConfig => ({
+  spEntityId: SP_ENTITY_ID,
+  acsUrl: ACS_URL,
+  idpEntityId: IDP_ENTITY_ID,
+  idpSsoUrl: IDP_SSO_URL,
+  idpCertificates: [idpKeys.cert],
+  subjectAttribute: null,
+  ...overrides,
+});
+
+export const iso = (offsetMs = 0) => new Date(Date.now() + offsetMs).toISOString();
+export const newId = () => `_${randomBytes(12).toString("hex")}`;
+
+export type SigningOptions = {
+  keys: KeyPair;
+  signatureAlgorithm?: string;
+  digestAlgorithm?: string;
+  /** Put this certificate in the signature's KeyInfo. */
+  keyInfoCert?: string;
+};
+
+export type AssertionOptions = {
+  id?: string;
+  issuer?: string;
+  audience?: string;
+  nameId?: string;
+  nameIdFormat?: string;
+  inResponseTo?: string | null;
+  recipient?: string;
+  bearer?: boolean;
+  notBefore?: string | null;
+  notOnOrAfter?: string;
+  scdNotOnOrAfter?: string;
+  sessionNotOnOrAfter?: string | null;
+  attributes?: Record<string, string[]>;
+};
+
+const esc = (value: string) =>
+  value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;");
+
+export function assertionXml(requestId: string, options: AssertionOptions = {}): string {
+  const id = options.id ?? newId();
+  const attributes = options.attributes ?? {
+    email: ["learner@example.com"],
+    displayName: ["Lena Learner"],
+  };
+  const inResponseTo =
+    options.inResponseTo === undefined ? requestId : options.inResponseTo;
+  const notBefore = options.notBefore === undefined ? iso(-60_000) : options.notBefore;
+  const attributeXml = Object.entries(attributes)
+    .map(
+      ([name, values]) =>
+        `<saml:Attribute Name="${esc(name)}">${values
+          .map((value) => `<saml:AttributeValue>${esc(value)}</saml:AttributeValue>`)
+          .join("")}</saml:Attribute>`,
+    )
+    .join("");
+  const session =
+    options.sessionNotOnOrAfter === null
+      ? ""
+      : ` SessionNotOnOrAfter="${options.sessionNotOnOrAfter ?? iso(3_600_000)}"`;
+  return (
+    `<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="${id}" Version="2.0" IssueInstant="${iso()}">` +
+    `<saml:Issuer>${options.issuer ?? IDP_ENTITY_ID}</saml:Issuer>` +
+    `<saml:Subject><saml:NameID Format="${options.nameIdFormat ?? PERSISTENT}">${esc(options.nameId ?? "subject-123")}</saml:NameID>` +
+    `<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:${options.bearer === false ? "holder-of-key" : "bearer"}">` +
+    `<saml:SubjectConfirmationData Recipient="${options.recipient ?? ACS_URL}" NotOnOrAfter="${options.scdNotOnOrAfter ?? iso(300_000)}"${inResponseTo === null ? "" : ` InResponseTo="${inResponseTo}"`}/>` +
+    `</saml:SubjectConfirmation></saml:Subject>` +
+    `<saml:Conditions${notBefore === null ? "" : ` NotBefore="${notBefore}"`} NotOnOrAfter="${options.notOnOrAfter ?? iso(300_000)}">` +
+    `<saml:AudienceRestriction><saml:Audience>${options.audience ?? SP_ENTITY_ID}</saml:Audience></saml:AudienceRestriction></saml:Conditions>` +
+    `<saml:AuthnStatement AuthnInstant="${iso(-5_000)}"${session}><saml:AuthnContext><saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef></saml:AuthnContext></saml:AuthnStatement>` +
+    `<saml:AttributeStatement>${attributeXml}</saml:AttributeStatement>` +
+    `</saml:Assertion>`
+  );
+}
+
+/** Enveloped signature over the document's root element, placed after its Issuer. */
+export function signRoot(xml: string, signing: SigningOptions, rootName: string): string {
+  const sig = new SignedXml({
+    privateKey: signing.keys.key,
+    signatureAlgorithm: signing.signatureAlgorithm ?? SIG_RSA_SHA256,
+    canonicalizationAlgorithm: "http://www.w3.org/2001/10/xml-exc-c14n#",
+    ...(signing.keyInfoCert ? { publicCert: signing.keyInfoCert } : {}),
+  });
+  sig.addReference({
+    xpath: `/*[local-name(.)='${rootName}']`,
+    transforms: [
+      "http://www.w3.org/2000/09/xmldsig#enveloped-signature",
+      "http://www.w3.org/2001/10/xml-exc-c14n#",
+    ],
+    digestAlgorithm: signing.digestAlgorithm ?? DIGEST_SHA256,
+  });
+  sig.computeSignature(xml, {
+    location: { reference: `/*[local-name(.)='${rootName}']/*[local-name(.)='Issuer']`, action: "after" },
+  });
+  return sig.getSignedXml();
+}
+
+export type ResponseOptions = {
+  requestId: string;
+  destination?: string | null;
+  responseInResponseTo?: string | null;
+  statusValue?: string;
+  /** The assertion markup placed inside the Response. */
+  assertion?: string;
+  extensions?: string;
+};
+
+export function responseXml(options: ResponseOptions): string {
+  const destination = options.destination === undefined ? ACS_URL : options.destination;
+  const inResponseTo =
+    options.responseInResponseTo === undefined ? options.requestId : options.responseInResponseTo;
+  return (
+    `<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="${newId()}" Version="2.0" IssueInstant="${iso()}"` +
+    `${destination === null ? "" : ` Destination="${destination}"`}${inResponseTo === null ? "" : ` InResponseTo="${inResponseTo}"`}>` +
+    `<saml:Issuer>${IDP_ENTITY_ID}</saml:Issuer>` +
+    `<samlp:Status><samlp:StatusCode Value="${options.statusValue ?? "urn:oasis:names:tc:SAML:2.0:status:Success"}"/></samlp:Status>` +
+    `${options.extensions ?? ""}${options.assertion ?? ""}` +
+    `</samlp:Response>`
+  );
+}
+
+export const b64 = (xml: string) => Buffer.from(xml, "utf8").toString("base64");
+
+/** A fully valid, correctly signed response; tweak through the options. */
+export function signedResponse(
+  requestId: string,
+  assertion: AssertionOptions = {},
+  response: Partial<ResponseOptions> = {},
+  signing: SigningOptions = { keys: idpKeys },
+): string {
+  const signed = signRoot(assertionXml(requestId, assertion), signing, "Assertion");
+  return b64(responseXml({ requestId, assertion: signed, ...response }));
+}
+
+export class MemoryRequestStore implements SsoRequestStore {
+  private readonly requests = new Map<string, { requestId: string; used: boolean }>();
+  consumeCalls = 0;
+  add(relayState: string, requestId: string) {
+    this.requests.set(relayState, { requestId, used: false });
+  }
+  async findOpen(relayState: string) {
+    const entry = this.requests.get(relayState);
+    return entry && !entry.used ? { requestId: entry.requestId } : null;
+  }
+  async consume(relayState: string, inResponseTo: string) {
+    this.consumeCalls++;
+    const entry = this.requests.get(relayState);
+    if (!entry || entry.used || entry.requestId !== inResponseTo) {
+      return false;
+    }
+    entry.used = true;
+    return true;
+  }
+}
+
+export class MemoryReplayStore implements AssertionReplayStore {
+  readonly seen = new Map<string, Date>();
+  async remember(assertionId: string, expiresAt: Date) {
+    if (this.seen.has(assertionId)) {
+      return false;
+    }
+    this.seen.set(assertionId, expiresAt);
+    return true;
+  }
+}
diff --git a/apps/api/src/sso-protocol/types.ts b/apps/api/src/sso-protocol/types.ts
new file mode 100644
index 000000000..599c4bd0d
--- /dev/null
+++ b/apps/api/src/sso-protocol/types.ts
@@ -0,0 +1,75 @@
+export type SamlConnectionConfig = {
+  /** Per-connection SP entity id (an https URL). */
+  spEntityId: string;
+  /** Per-connection assertion consumer service URL. */
+  acsUrl: string;
+  idpEntityId: string;
+  /** Must pass `isSafeIdpUrl`. */
+  idpSsoUrl: string;
+  /** PEM or bare base64; at least one; several allowed for rotation. */
+  idpCertificates: string[];
+  /** Attribute to use as the subject when the NameID isn't persistent. */
+  subjectAttribute?: string | null;
+};
+
+export interface SsoRequestStore {
+  /** The open (unused, unexpired) request for this RelayState token, without using it up. */
+  findOpen(relayState: string): Promise<{ requestId: string } | null>;
+  /** Atomically use up the request iff still open and its AuthnRequest ID equals inResponseTo. */
+  consume(relayState: string, inResponseTo: string): Promise<boolean>;
+}
+
+export interface AssertionReplayStore {
+  /** Record an assertion ID until expiresAt; false if it was already recorded. */
+  remember(assertionId: string, expiresAt: Date): Promise<boolean>;
+}
+
+export type SamlAssertion = {
+  issuer: string;
+  assertionId: string;
+  subject: string;
+  email: string | null;
+  name: string | null;
+  attributes: Record<string, string[]>;
+  sessionNotOnOrAfter: Date | null;
+};
+
+export type SamlFailureReason =
+  | "request_not_found"
+  | "connection_unavailable"
+  | "invalid_response"
+  | "response_too_large"
+  | "dtd_not_allowed"
+  | "status_not_success"
+  | "signature_invalid"
+  | "weak_algorithm"
+  | "wrong_audience"
+  | "wrong_destination"
+  | "wrong_recipient"
+  | "wrong_issuer"
+  | "expired"
+  | "not_yet_valid"
+  | "in_response_to_mismatch"
+  | "request_already_used"
+  | "replayed_assertion"
+  | "unstable_subject"
+  | "missing_subject";
+
+export type SamlValidationResult =
+  | { ok: true; assertion: SamlAssertion }
+  | { ok: false; reason: SamlFailureReason };
+
+export type SamlServiceProvider = {
+  buildAuthnRequestUrl(input: {
+    relayState: string;
+  }): Promise<{ url: string; requestId: string }>;
+  validatePostResponse(input: {
+    samlResponse: string;
+    relayState: string;
+    requests: SsoRequestStore;
+    replay: AssertionReplayStore;
+    /** Called after the request is found and before signature validation; false => "connection_unavailable". */
+    checkConnection?: () => Promise<boolean>;
+  }): Promise<SamlValidationResult>;
+  serviceProviderMetadata(): string;
+};
diff --git a/apps/api/src/sso-protocol/url.ts b/apps/api/src/sso-protocol/url.ts
new file mode 100644
index 000000000..1e6476851
--- /dev/null
+++ b/apps/api/src/sso-protocol/url.ts
@@ -0,0 +1,24 @@
+/** An IdP endpoint we will redirect browsers to: absolute https, no credentials. */
+export function isSafeIdpUrl(value: string): boolean {
+  if (typeof value !== "string" || value.length === 0 || value.length > 2048) {
+    return false;
+  }
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code <= 0x20 || code === 0x7f) {
+      return false; // whitespace and control characters
+    }
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return false;
+  }
+  return (
+    parsed.protocol === "https:" &&
+    parsed.hostname.length > 0 &&
+    parsed.username === "" &&
+    parsed.password === ""
+  );
+}
diff --git a/apps/api/src/sso-protocol/xml.ts b/apps/api/src/sso-protocol/xml.ts
new file mode 100644
index 000000000..820474bf0
--- /dev/null
+++ b/apps/api/src/sso-protocol/xml.ts
@@ -0,0 +1,85 @@
+import type { XmlNode } from "./dom.js";
+
+export const ELEMENT_NODE = 1;
+
+export const NS = {
+  protocol: "urn:oasis:names:tc:SAML:2.0:protocol",
+  assertion: "urn:oasis:names:tc:SAML:2.0:assertion",
+  metadata: "urn:oasis:names:tc:SAML:2.0:metadata",
+  dsig: "http://www.w3.org/2000/09/xmldsig#",
+} as const;
+
+/** DTDs and entities are never accepted, in any document this module reads. */
+export function hasDtdOrEntity(xml: string): boolean {
+  return /<!\s*(DOCTYPE|ENTITY)/i.test(xml);
+}
+
+export function childElements(
+  node: XmlNode,
+  localName: string,
+  namespaceURI: string,
+): XmlNode[] {
+  const found: XmlNode[] = [];
+  for (let i = 0; i < node.childNodes.length; i++) {
+    const child = node.childNodes[i];
+    if (
+      child.nodeType === ELEMENT_NODE &&
+      child.localName === localName &&
+      child.namespaceURI === namespaceURI
+    ) {
+      found.push(child);
+    }
+  }
+  return found;
+}
+
+export function descendantElements(
+  node: XmlNode,
+  localName: string,
+  namespaceURI: string,
+): XmlNode[] {
+  const found: XmlNode[] = [];
+  const walk = (current: XmlNode) => {
+    for (let i = 0; i < current.childNodes.length; i++) {
+      const child = current.childNodes[i];
+      if (child.nodeType !== ELEMENT_NODE) {
+        continue;
+      }
+      if (child.localName === localName && child.namespaceURI === namespaceURI) {
+        found.push(child);
+      }
+      walk(child);
+    }
+  };
+  walk(node);
+  return found;
+}
+
+export function attribute(node: XmlNode, name: string): string | null {
+  return node.hasAttribute(name) ? node.getAttribute(name) : null;
+}
+
+export function text(node: XmlNode): string {
+  return (node.textContent ?? "").trim();
+}
+
+const XS_DATE_TIME =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+
+/** Strict xs:dateTime with a time zone; null when missing or malformed. */
+export function parseDateTime(value: string | null): Date | null {
+  if (!value || !XS_DATE_TIME.test(value)) {
+    return null;
+  }
+  const ms = Date.parse(value);
+  return Number.isNaN(ms) ? null : new Date(ms);
+}
+
+export function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
diff --git a/apps/api/src/test-billing-plan.ts b/apps/api/src/test-billing-plan.ts
new file mode 100644
index 000000000..977f3bbf2
--- /dev/null
+++ b/apps/api/src/test-billing-plan.ts
@@ -0,0 +1,116 @@
+// Test helpers that move a school between plans through the real billing
+// engine and the fake provider, so the billing lifecycle hook runs.
+import type { Runtime } from "./runtime.js";
+import type { SeededWorld } from "./seed.js";
+
+type FakeInternals = {
+  subscriptions: Map<string, Record<string, unknown> & { providerSubscriptionId: string }>;
+};
+
+/** Buy a plan for a school as the world's owner; returns the provider subscription id. */
+export async function buyPlan(
+  runtime: Runtime,
+  world: SeededWorld,
+  schoolId: string,
+  offerKey: "pro_month" | "business_month",
+): Promise<string> {
+  const target = { kind: "school", id: schoolId };
+  const issued = await runtime.billing.grants.issue({
+    actorId: world.owner.id,
+    sessionId: `buy-${schoolId}`,
+    sessionCreatedAt: runtime.clock.now(),
+    action: "checkout",
+    target,
+  });
+  if (!issued.ok) throw new Error("grant_failed");
+  const grant = runtime.billing.grants.grant({
+    token: issued.token,
+    actorId: world.owner.id,
+    sessionId: `buy-${schoolId}`,
+    action: "checkout",
+    target,
+  });
+  const checkout = await runtime.billing.billing.startCheckout({
+    grant,
+    entity: target,
+    payer: { id: world.owner.id, email: "owner@example.com", name: "Owner" },
+    offerKey,
+    catalogRevision: 1,
+    returnUrl: "https://app.test/billing",
+  });
+  const paid = await runtime.billing.fake.simulatePayment(checkout.attempt.providerCheckoutSessionId!);
+  await runtime.billing.billing.ingestWebhook({
+    provider: "fake",
+    raw: runtime.billing.fake.signWebhook(
+      JSON.stringify({
+        type: "subscription.active",
+        data: {
+          subscription_id: paid.providerSubscriptionId,
+          metadata: { checkoutAttemptId: checkout.attempt.attemptId },
+        },
+      }),
+    ),
+  });
+  await runtime.billing.billing.runWebhookInboxBatch({ workerId: "test-webhooks" });
+  return paid.providerSubscriptionId;
+}
+
+/** Change the provider's view of a subscription and let billing project it. */
+export async function changeSubscription(
+  runtime: Runtime,
+  subscriptionId: string,
+  patch: Record<string, unknown>,
+): Promise<void> {
+  const internals = runtime.billing.fake as unknown as FakeInternals;
+  const current = internals.subscriptions.get(subscriptionId);
+  if (!current) throw new Error("subscription_not_found");
+  internals.subscriptions.set(subscriptionId, {
+    ...current,
+    ...patch,
+    providerOccurredAt: runtime.clock.now(),
+    providerVersion: String(Number(current.providerVersion ?? "1") + 1),
+  });
+  await runtime.billing.billing.ingestWebhook({
+    provider: "fake",
+    raw: runtime.billing.fake.signWebhook(
+      JSON.stringify({ type: "subscription.updated", data: { subscription_id: subscriptionId } }),
+    ),
+  });
+  await runtime.billing.billing.runWebhookInboxBatch({ workerId: "test-webhooks" });
+}
+
+/** Move a school that already has a plan to another offer, immediately. */
+export async function changePlan(
+  runtime: Runtime,
+  world: SeededWorld,
+  schoolId: string,
+  offerKey: "pro_month" | "business_month",
+): Promise<void> {
+  const target = { kind: "school", id: schoolId };
+  const sessionId = `change-${offerKey}-${schoolId}`;
+  const issued = await runtime.billing.grants.issue({
+    actorId: world.owner.id,
+    sessionId,
+    sessionCreatedAt: runtime.clock.now(),
+    action: "plan_change",
+    target,
+  } as never);
+  if (!issued.ok) throw new Error("grant_failed");
+  const grant = runtime.billing.grants.grant({
+    token: issued.token,
+    actorId: world.owner.id,
+    sessionId,
+    action: "plan_change",
+    target,
+  } as never);
+  await runtime.billing.billing.startPlanChange({
+    grant,
+    entity: target,
+    payer: { id: world.owner.id, email: "owner@example.com", name: "Owner" },
+    offerKey,
+    catalogRevision: 1,
+    effectiveAt: "immediately",
+    prorationMode: "do_not_bill",
+  });
+  await runtime.billing.billing.runWebhookInboxBatch({ workerId: "test-webhooks" });
+}
diff --git a/apps/api/src/test-learner-auth.ts b/apps/api/src/test-learner-auth.ts
index 63b41a78e..3c6ce9e8d 100644
--- a/apps/api/src/test-learner-auth.ts
+++ b/apps/api/src/test-learner-auth.ts
@@ -88,6 +88,7 @@ export async function signUpLearner(
     authenticationMethod: "email",
     clock,
   });
+  if (!issued.ok) return issued;
 
   await db.insert(schema.auditEvents).values({
     id: uuidv7(clock),
@@ -131,7 +132,7 @@ export async function signUpLearner(
     { ensureSubscribed: true, reason: "learner_signup" },
   );
 
-  return { ok: true, value: issued.dto, token: issued.token };
+  return { ok: true, value: issued.value.dto, token: issued.value.token };
 }
 
 /** Signs a learner in without proof of the email address. Tests only. */
@@ -191,6 +192,7 @@ export async function signInLearner(
     authenticationMethod: "email",
     clock,
   });
+  if (!issued.ok) return issued;
 
   const updates: Partial<typeof schema.schoolAccounts.$inferInsert> = {
     lastActiveAt: now,
@@ -216,7 +218,7 @@ export async function signInLearner(
     { reason: "learner_login" },
   );
 
-  return { ok: true, value: issued.dto, token: issued.token };
+  return { ok: true, value: issued.value.dto, token: issued.value.token };
 }
 
 /**
diff --git a/apps/api/src/test-sso-flow.ts b/apps/api/src/test-sso-flow.ts
new file mode 100644
index 000000000..23f9659db
--- /dev/null
+++ b/apps/api/src/test-sso-flow.ts
@@ -0,0 +1,163 @@
+// Test harness for the single sign-on flow: a runtime, the Express app on a
+// real port, a seeded SAML connection pinned to the fixture IdP's certificate,
+// and helpers to start a sign-in and answer it as that IdP.
+import type { AddressInfo } from "node:net";
+import type { Server } from "node:http";
+import { eq } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { dispatch } from "./dispatch.js";
+import { digestToken } from "./learners.js";
+import { createExpressApp } from "./express-app.js";
+import { createPgliteRuntime, freezeRuntimeClock, type Runtime } from "./runtime.js";
+import { seedWorld, type SeededWorld } from "./seed.js";
+import { ssoServiceProviderUrls } from "./sso-config.js";
+import { seedSsoConnection } from "./test-sso.js";
+import {
+  type AssertionOptions,
+  idpKeys,
+  type ResponseOptions,
+  signedResponse,
+  type SigningOptions,
+} from "./sso-protocol/test-idp.js";
+
+export const SCHOOL_A_HOST = "school-a.localhost:3001";
+export const NONCE = "n".repeat(43);
+export const bareCertificate = (pem: string) =>
+  pem.replace(/-----[A-Z ]+-----/g, "").replace(/\s+/g, "");
+
+export async function ssoSetup(
+  options: {
+    billingMode?: "cloud" | "oss";
+    status?: "draft" | "active" | "suspended" | "disabled";
+    enforcement?: "optional" | "required_for_domains";
+    maxSessionMinutes?: number | null;
+    tested?: boolean;
+    domains?: string[];
+    /** Don't create a connection at all. */
+    noConnection?: boolean;
+  } = {},
+) {
+  // Better Auth stamps sessions with real time, and the SAML library judges
+  // assertions against it, so the frozen clock starts at real time.
+  const clock = freezeRuntimeClock(new Date());
+  const runtime = await createPgliteRuntime({
+    clock,
+    billingMode: options.billingMode ?? "oss",
+  });
+  const world = await seedWorld(runtime, clock);
+  const app = createExpressApp(runtime);
+  const server = await new Promise<Server>((resolve) => {
+    const listening = app.listen(0, () => resolve(listening));
+  });
+  const appBase = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+  const connection = options.noConnection
+    ? null
+    : await seedSsoConnection(runtime.db, clock, {
+        schoolId: world.schoolA.id,
+        status: options.status ?? "active",
+        enforcement: options.enforcement,
+        entityId: "https://idp.example/entity",
+        idpSsoUrl: "https://idp.example/sso",
+        idpCertificates: [bareCertificate(idpKeys.cert)],
+        tested: options.tested ?? true,
+        maxSessionMinutes: options.maxSessionMinutes,
+        domains: options.domains ?? ["acme.com"],
+      });
+  const urls = connection
+    ? ssoServiceProviderUrls(runtime.auth.publicApiUrl, connection.publicId)
+    : null;
+  const connectionPath = connection
+    ? `/learner-login/sso/${connection.publicId}`
+    : "/learner-login/sso/sso_missing";
+
+  const startSignIn = async (next?: string) => {
+    const started = await dispatch(runtime, {
+      method: "POST",
+      path: "/v1/learner/auth/sso",
+      headers: { "x-school-id": world.schoolA.publicId },
+      body: { host: SCHOOL_A_HOST, nonce: NONCE, ...(next ? { next } : {}) },
+    });
+    if (started.status !== 200) return { started, token: null, requestId: null, redirect: null };
+    const url = new URL((started.body as { url: string }).url);
+    const token = url.searchParams.get("request")!;
+    const redirect = await fetch(`${appBase}${url.pathname}${url.search}`, { redirect: "manual" });
+    const [row] = await runtime.db
+      .select()
+      .from(schema.schoolSsoRequests)
+      .where(eq(schema.schoolSsoRequests.requestDigest, digestToken(token)));
+    return { started, token, requestId: row?.protocolRequestId ?? null, redirect };
+  };
+
+  const response = (
+    requestId: string,
+    assertion: AssertionOptions = {},
+    responseOptions: Partial<ResponseOptions> = {},
+    signing: SigningOptions = { keys: idpKeys },
+  ) =>
+    signedResponse(
+      requestId,
+      {
+        audience: urls!.entityId,
+        recipient: urls!.acsUrl,
+        nameId: "subject-1",
+        attributes: { email: ["alice@acme.com"], displayName: ["Alice"] },
+        ...assertion,
+      },
+      { destination: urls!.acsUrl, ...responseOptions },
+      signing,
+    );
+
+  const acs = (samlResponse: string, relayState: string, path = connectionPath) =>
+    fetch(`${appBase}${path}/acs`, {
+      method: "POST",
+      redirect: "manual",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ SAMLResponse: samlResponse, RelayState: relayState }),
+    });
+
+  const redeem = (ticket: string, nonce = NONCE) =>
+    dispatch(runtime, {
+      method: "POST",
+      path: "/v1/auth/tickets/consume",
+      headers: {
+        "x-school-id": world.schoolA.publicId,
+        cookie: `courselit.login.nonce=${nonce}`,
+      },
+      body: { ticket },
+    });
+
+  return {
+    clock,
+    runtime,
+    world,
+    connection: connection!,
+    urls: urls!,
+    appBase,
+    connectionPath,
+    startSignIn,
+    response,
+    acs,
+    redeem,
+    async close() {
+      server.close();
+      await runtime.close();
+    },
+  };
+}
+
+export type SsoSetup = Awaited<ReturnType<typeof ssoSetup>>;
+
+export function ticketFrom(location: string | null): string | null {
+  if (!location) return null;
+  return new URLSearchParams(new URL(location).hash.slice(1)).get("ticket");
+}
+
+export function ownerHeaders(world: SeededWorld, extra: Record<string, string> = {}) {
+  return {
+    cookie: world.owner.sessionCookie,
+    "x-school-id": world.schoolA.publicId,
+    ...extra,
+  };
+}
+
+export type { Runtime };
diff --git a/apps/api/src/test-sso.ts b/apps/api/src/test-sso.ts
new file mode 100644
index 000000000..64d06de6f
--- /dev/null
+++ b/apps/api/src/test-sso.ts
@@ -0,0 +1,93 @@
+import { createPublicId, uuidv7, type Clock } from "@codelitdev/platform";
+import { eq } from "drizzle-orm";
+import * as schema from "./db/schema/index.js";
+import { connectionConfigDigest } from "./sso-config.js";
+import { signInLearnerWithIdentity } from "./learners.js";
+import { findOrCreateVerifiedUser } from "./learners.js";
+import type { AppDb } from "./types.js";
+
+/** An SSO connection for tests, with its verified domains. */
+export async function seedSsoConnection(
+  db: AppDb,
+  clock: Clock,
+  input: {
+    schoolId: string;
+    status?: "draft" | "active" | "suspended" | "disabled";
+    enforcement?: "optional" | "required_for_domains";
+    entityId?: string;
+    domains?: string[];
+    unverifiedDomains?: string[];
+    idpCertificates?: string[];
+    idpSsoUrl?: string;
+    /** Record a successful test against the current settings, so it can be activated. */
+    tested?: boolean;
+    maxSessionMinutes?: number | null;
+    displayName?: string;
+  },
+) {
+  const now = clock.now();
+  const id = uuidv7(clock);
+  const entityId = input.entityId ?? "https://idp.example.test/entity";
+  const [connection] = await db
+    .insert(schema.schoolSsoConnections)
+    .values({
+      id,
+      publicId: createPublicId("sso", clock),
+      schoolId: input.schoolId,
+      protocol: "saml",
+      status: input.status ?? "active",
+      displayName: input.displayName ?? "Acme employees",
+      maxSessionMinutes: input.maxSessionMinutes ?? null,
+      enforcement: input.enforcement ?? "optional",
+      idpEntityId: entityId,
+      idpSsoUrl: input.idpSsoUrl ?? "https://idp.example.test/sso",
+      idpCertificates: input.idpCertificates ?? [],
+      createdAt: now,
+      updatedAt: now,
+    })
+    .returning();
+  if (input.tested) {
+    await db
+      .update(schema.schoolSsoConnections)
+      .set({ testedAt: now, testedConfigDigest: connectionConfigDigest(connection!) })
+      .where(eq(schema.schoolSsoConnections.id, id));
+  }
+  const rows = [
+    ...(input.domains ?? ["acme.com"]).map((domain) => ({ domain, verified: true })),
+    ...(input.unverifiedDomains ?? []).map((domain) => ({ domain, verified: false })),
+  ];
+  for (const row of rows) {
+    await db.insert(schema.schoolSsoDomains).values({
+      id: uuidv7(clock),
+      connectionId: id,
+      schoolId: input.schoolId,
+      domain: row.domain,
+      verificationToken: "t".repeat(32),
+      verifiedAt: row.verified ? now : null,
+      createdAt: now,
+    });
+  }
+  return connection!;
+}
+
+/** A learner who signed in with an email code, so a real platform user backs the account. */
+export async function seedRealLearner(
+  db: AppDb,
+  clock: Clock,
+  schoolPublicId: string,
+  email: string,
+  name = "Real Person",
+) {
+  const user = await findOrCreateVerifiedUser(db, email, clock, name);
+  const signedIn = await signInLearnerWithIdentity(
+    db,
+    { userId: user.id, email, name, schoolPublicId, authenticationMethod: "email" },
+    clock,
+  );
+  if (!signedIn.ok) throw new Error("seed_real_learner_failed");
+  return { user, session: signedIn.session, token: signedIn.token };
+}
+
+export const learnerCookie = (token: string) => ({
+  cookie: `courselit.learner.session=${token}`,
+});
diff --git a/apps/api/src/ui-surface.test.ts b/apps/api/src/ui-surface.test.ts
index 76e4d6d92..9d60005dd 100644
--- a/apps/api/src/ui-surface.test.ts
+++ b/apps/api/src/ui-surface.test.ts
@@ -181,7 +181,7 @@ describe("admin and learner surfaces", () => {
     expect(brandingSettings).toContain('"/api/v1/school/website/branding"');
     expect(codeInjectionSettings).toContain('"/api/v1/school/code-injection"');
     expect(settings).toContain('"branding",');
-    expect(settings).toContain('"payment", "team", "notifications", "api-keys", "ai-assistants"] as const');
+    expect(settings).toContain('"payment", "team", "notifications", "login-providers", "api-keys", "ai-assistants"] as const');
     expect(settings).toContain('value="notifications"');
     expect(settings).toContain('"ai-assistants"] as const');
     expect(settings).toContain('value="team"');
diff --git a/apps/api/src/worker.ts b/apps/api/src/worker.ts
index 4067799b2..1f385597b 100644
--- a/apps/api/src/worker.ts
+++ b/apps/api/src/worker.ts
@@ -3,6 +3,7 @@ import { startBillingWorkers } from "@codelitdev/platform/billing";
 import { processDripEmails } from "./drip-emails.js";
 import { startIntegrationWorker } from "./integration-provisioning.js";
 import { TELEMETRY_PROPERTY_ALLOWLIST } from "./permissions.js";
+import { startSsoJobs } from "./sso-jobs.js";
 import { createPostgresRuntime } from "./runtime.js";
 
 const databaseUrl = process.env.DATABASE_URL;
@@ -78,6 +79,16 @@ try {
     runtime.clock,
     observability.logger,
   );
+  // Plan-feature syncs queued by the billing hook, the daily plan sync, the
+  // weekly SSO domain re-check and cleanup of expired SSO requests.
+  const stopSsoJobs = startSsoJobs({
+    db: runtime.db,
+    billing: runtime.billing.billing,
+    clock: runtime.clock,
+    logger: observability.logger,
+    onError: (task, error) =>
+      observability.captureException({ error, source: "worker.sso", context: { task } }),
+  });
   let dripRunning = false;
   const dripTimer = setInterval(async () => {
     if (dripRunning) return;
@@ -96,6 +107,7 @@ try {
     const stop = () => {
       clearInterval(dripTimer);
       stopIntegrationWorker();
+      stopSsoJobs();
       void (billingWorkers?.stop() ?? Promise.resolve()).finally(resolve);
     };
     process.once("SIGTERM", stop);
diff --git a/apps/storefront/app/schools/[schoolId]/auth/sso/route.test.ts b/apps/storefront/app/schools/[schoolId]/auth/sso/route.test.ts
new file mode 100644
index 000000000..46da26b86
--- /dev/null
+++ b/apps/storefront/app/schools/[schoolId]/auth/sso/route.test.ts
@@ -0,0 +1,82 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { NextRequest } from "next/server";
+import { GET } from "./route";
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+type Sent = { url: string; headers: Headers; body: Record<string, string> };
+
+function start(
+  query: string,
+  upstream: () => Response | Promise<Response>,
+  headers: Record<string, string> = { host: "school.example", "x-forwarded-proto": "https" },
+) {
+  const sent: Sent[] = [];
+  globalThis.fetch = (async (input, init) => {
+    sent.push({
+      url: String(input),
+      headers: new Headers(init?.headers),
+      body: JSON.parse(String(init?.body)),
+    });
+    return upstream();
+  }) as typeof fetch;
+  const request = new NextRequest(`https://school.example/auth/sso${query}`, { headers });
+  return GET(request, { params: Promise.resolve({ schoolId: "sch_school" }) }).then(
+    (response) => ({ response, sent }),
+  );
+}
+
+describe("SSO start route", () => {
+  it("posts host, nonce and next to the API and sets the nonce cookie", async () => {
+    const { response, sent } = await start("?next=%2Fcourses%2Fx", () =>
+      Response.json({ url: "https://idp.example/sso?req=1" }),
+    );
+    expect(sent).toHaveLength(1);
+    expect(sent[0].url).toEndWith("/v1/learner/auth/sso");
+    expect(sent[0].headers.get("x-school-id")).toBe("sch_school");
+    expect(sent[0].body.host).toBe("school.example");
+    expect(sent[0].body.next).toBe("/courses/x");
+    expect(response.status).toBe(303);
+    expect(response.headers.get("location")).toBe("https://idp.example/sso?req=1");
+    expect(response.headers.get("cache-control")).toBe("no-store");
+    const cookie = response.cookies.get("courselit.login.nonce");
+    expect(cookie?.value).toBe(sent[0].body.nonce);
+    expect(cookie?.httpOnly).toBe(true);
+    expect(cookie?.secure).toBe(true);
+    expect(cookie?.sameSite).toBe("lax");
+    expect(cookie?.maxAge).toBe(600);
+  });
+
+  it("defaults next to /dashboard", async () => {
+    const { sent } = await start("", () => Response.json({ url: "https://idp.example/" }));
+    expect(sent[0].body.next).toBe("/dashboard");
+  });
+
+  it("leaves next for the API to sanitise and never trusts it for the redirect", async () => {
+    const { response } = await start("?next=https%3A%2F%2Fevil.example", () =>
+      Response.json({ url: "https://idp.example/" }),
+    );
+    // The browser is only ever sent to the URL the API returned.
+    expect(response.headers.get("location")).toBe("https://idp.example/");
+  });
+
+  it("redirects to /login?error=sso without a cookie when the API refuses", async () => {
+    const { response } = await start("", () => new Response("{}", { status: 403 }));
+    expect(response.status).toBe(303);
+    expect(response.headers.get("location")).toBe("https://school.example/login?error=sso");
+    expect(response.cookies.get("courselit.login.nonce")).toBeUndefined();
+  });
+
+  it("fails the same way when the API is unreachable or returns no url", async () => {
+    const down = await start("", () => {
+      throw new Error("down");
+    });
+    expect(down.response.headers.get("location")).toBe("https://school.example/login?error=sso");
+    const empty = await start("", () => Response.json({}));
+    expect(empty.response.headers.get("location")).toBe("https://school.example/login?error=sso");
+  });
+});
diff --git a/apps/storefront/app/schools/[schoolId]/auth/sso/route.ts b/apps/storefront/app/schools/[schoolId]/auth/sso/route.ts
new file mode 100644
index 000000000..88e420ed3
--- /dev/null
+++ b/apps/storefront/app/schools/[schoolId]/auth/sso/route.ts
@@ -0,0 +1,52 @@
+import { randomBytes } from "node:crypto";
+import { type NextRequest, NextResponse } from "next/server";
+
+const API_URL = (process.env.API_URL ?? "http://127.0.0.1:4000").replace(/\/$/, "");
+const LOGIN_NONCE_COOKIE = "courselit.login.nonce";
+
+/**
+ * Start single sign-on. This site keeps a random nonce in a cookie and
+ * sends the learner to the API host, where the school's identity provider sign-in runs. They come back
+ * to /auth/complete with a ticket that only works alongside this cookie.
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ schoolId: string }> },
+) {
+  const { schoolId } = await params;
+  const host =
+    request.headers.get("host") || request.headers.get("x-forwarded-host") || "";
+  const next = request.nextUrl.searchParams.get("next") ?? "/dashboard";
+  const nonce = randomBytes(32).toString("base64url");
+  const secure =
+    request.headers.get("x-forwarded-proto") === "https" ||
+    request.nextUrl.protocol === "https:";
+  const failure = new URL(
+    "/login",
+    host ? `${secure ? "https" : "http"}://${host}` : request.nextUrl.origin,
+  );
+  failure.searchParams.set("error", "sso");
+
+  const response = await fetch(`${API_URL}/v1/learner/auth/sso`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-school-id": schoolId },
+    body: JSON.stringify({ host, nonce, next }),
+    cache: "no-store",
+  }).catch(() => null);
+  const body = response?.ok
+    ? ((await response.json().catch(() => null)) as { url?: string } | null)
+    : null;
+  if (!body?.url) {
+    return NextResponse.redirect(failure, 303);
+  }
+  const redirect = NextResponse.redirect(body.url, 303);
+  redirect.cookies.set(LOGIN_NONCE_COOKIE, nonce, {
+    httpOnly: true,
+    secure,
+    sameSite: "lax",
+    path: "/",
+    maxAge: 10 * 60,
+  });
+  redirect.headers.set("Cache-Control", "no-store");
+  return redirect;
+}
diff --git a/apps/storefront/components/auth/external-login-button.tsx b/apps/storefront/components/auth/external-login-button.tsx
index 2f817186b..bfc4ed876 100644
--- a/apps/storefront/components/auth/external-login-button.tsx
+++ b/apps/storefront/components/auth/external-login-button.tsx
@@ -34,7 +34,7 @@ export function ExternalLoginButton({
   onClick,
   disabled,
 }: {
-  provider?: "google";
+  provider?: "google" | "sso";
   label?: string;
   onClick: () => Promise<void> | void;
   disabled?: boolean;
@@ -47,9 +47,9 @@ export function ExternalLoginButton({
       disabled={disabled}
       className="w-full flex items-center justify-center gap-2"
     >
-      <GoogleLogo />
+      {provider === "google" ? <GoogleLogo /> : null}
       <LearnerText2 component="span">
-        {label ?? "Continue with Google"}
+        {label ?? (provider === "google" ? "Continue with Google" : "Sign in with SSO")}
       </LearnerText2>
     </Button>
   );
diff --git a/apps/storefront/components/checkout-login-form.tsx b/apps/storefront/components/checkout-login-form.tsx
index e293d6787..8ba4464e7 100644
--- a/apps/storefront/components/checkout-login-form.tsx
+++ b/apps/storefront/components/checkout-login-form.tsx
@@ -13,8 +13,10 @@ import {
 import {
   requestEmailCode,
   signInWithGoogle as startGoogleSignIn,
+  signInWithSso as startSsoSignIn,
   verifyEmailCode,
 } from "@/lib/learner-sign-in";
+import { isSsoRequired, resolveLoginOptions } from "@/lib/login-methods";
 import { learnerHeaders } from "@/lib/school";
 type Learner = {
   id: string;
@@ -26,12 +28,13 @@ type Learner = {
 export function CheckoutLoginForm({
   checkoutPath,
   loginMethods,
+  ssoDisplayName,
   onComplete,
 }: {
   checkoutPath: string;
   loginMethods: string[];
+  ssoDisplayName?: string | null;
   googleProviderId?: string | null;
-  ssoProviderId?: string | null;
   onComplete: (learner: Learner) => void;
 }) {
   const [otpStep, setOtpStep] = useState<"email" | "otp" | "name">("email");
@@ -40,9 +43,13 @@ export function CheckoutLoginForm({
   const [error, setError] = useState<string | null>(null);
   const [loading, setLoading] = useState(false);
 
-  const showEmail = loginMethods.includes("email");
-  const showGoogle = loginMethods.includes("google");
-  const hasExternal = showGoogle;
+  const [ssoRequired, setSsoRequired] = useState(false);
+  const options = resolveLoginOptions({ loginMethods, ssoDisplayName });
+  // When the email's domain requires SSO, the email form gives way to the SSO button.
+  const showEmail = options.showEmail && !ssoRequired;
+  const showGoogle = options.showGoogle && !ssoRequired;
+  const showSso = options.showSso;
+  const hasExternal = showGoogle || showSso;
 
   async function completeFromSession() {
     const response = await fetch("/api/v1/learner/me", {
@@ -62,6 +69,7 @@ export function CheckoutLoginForm({
       await requestEmailCode(email);
       setOtpStep("otp");
     } catch (caught) {
+      if (isSsoRequired(caught)) setSsoRequired(true);
       setError(
         caught instanceof Error ? caught.message : "Unable to send a sign-in code.",
       );
@@ -97,6 +105,12 @@ export function CheckoutLoginForm({
     startGoogleSignIn(checkoutPath);
   }
 
+  function signInWithSso() {
+    setError(null);
+    setLoading(true);
+    startSsoSignIn(checkoutPath);
+  }
+
   return (
     <div className="flex flex-col gap-4">
       {otpStep === "name" ? (
@@ -190,6 +204,14 @@ export function CheckoutLoginForm({
               onClick={signInWithGoogle}
             />
           ) : null}
+          {showSso ? (
+            <ExternalLoginButton
+              provider="sso"
+              label={options.ssoLabel}
+              disabled={loading}
+              onClick={signInWithSso}
+            />
+          ) : null}
         </div>
       ) : null}
 
diff --git a/apps/storefront/components/public-checkout-session.tsx b/apps/storefront/components/public-checkout-session.tsx
index 9303d614e..5f367a621 100644
--- a/apps/storefront/components/public-checkout-session.tsx
+++ b/apps/storefront/components/public-checkout-session.tsx
@@ -254,6 +254,7 @@ export function PublicCheckoutSession({ sessionId }: { sessionId: string }) {
   const [plansLoaded, setPlansLoaded] = useState(false);
   const [learner, setLearner] = useState<Learner | null>(null);
   const [loginMethods, setLoginMethods] = useState<string[]>(["email"]);
+  const [ssoDisplayName, setSsoDisplayName] = useState<string | null>(null);
   const [googleProviderId, setGoogleProviderId] = useState<string | null>("google");
   const [loading, setLoading] = useState(true);
   const [busy, setBusy] = useState(false);
@@ -299,9 +300,11 @@ export function PublicCheckoutSession({ sessionId }: { sessionId: string }) {
         const body = (await response.json()) as {
           loginMethods?: string[];
           googleProviderId?: string | null;
+          ssoDisplayName?: string | null;
         };
         if (Array.isArray(body.loginMethods)) setLoginMethods(body.loginMethods);
         setGoogleProviderId(body.googleProviderId ?? null);
+        setSsoDisplayName(body.ssoDisplayName ?? null);
       }),
     ])
       .catch((caught) => {
@@ -628,6 +631,7 @@ export function PublicCheckoutSession({ sessionId }: { sessionId: string }) {
             <CheckoutLoginForm
               checkoutPath={loginPath}
               loginMethods={loginMethods}
+              ssoDisplayName={ssoDisplayName}
               googleProviderId={googleProviderId}
               onComplete={setLearner}
             />
diff --git a/apps/storefront/components/public-login-block.tsx b/apps/storefront/components/public-login-block.tsx
index f919d607b..61f953011 100644
--- a/apps/storefront/components/public-login-block.tsx
+++ b/apps/storefront/components/public-login-block.tsx
@@ -16,8 +16,15 @@ import {
 import {
   requestEmailCode,
   signInWithGoogle,
+  signInWithSso,
   verifyEmailCode,
 } from "@/lib/learner-sign-in";
+import {
+  DEFAULT_LOGIN_OPTIONS,
+  isSsoRequired,
+  loginErrorFromQuery,
+  resolveLoginOptions,
+} from "@/lib/login-methods";
 import {
   clearLearnerIdentityLink,
   learnerHeaders,
@@ -53,12 +60,11 @@ export function PublicLoginBlock() {
   });
   const [error, setError] = useState<string | null>(() => {
     if (typeof window === "undefined") return null;
-    return new URLSearchParams(window.location.search).get("error") === "google"
-      ? "Google sign-in didn't finish. Please try again."
-      : null;
+    return loginErrorFromQuery(new URLSearchParams(window.location.search).get("error"));
   });
   const [loading, setLoading] = useState(false);
-  const [loginMethods, setLoginMethods] = useState<string[]>(["email"]);
+  const [loginMethods, setLoginMethods] = useState(DEFAULT_LOGIN_OPTIONS);
+  const [ssoRequired, setSsoRequired] = useState(false);
 
   // A learner who is already signed in (Back after signing in, a bookmark, a
   // page restored from the back/forward cache) goes straight on. Only browsers
@@ -92,10 +98,8 @@ export function PublicLoginBlock() {
   useEffect(() => {
     void fetch(publicApiPath(schoolId, "/login-methods"))
       .then((res) => (res.ok ? res.json() : null))
-      .then((data: { loginMethods?: string[] } | null) => {
-        if (data?.loginMethods && Array.isArray(data.loginMethods)) {
-          setLoginMethods(data.loginMethods);
-        }
+      .then((data) => {
+        if (data) setLoginMethods(resolveLoginOptions(data));
       })
       .catch(() => {});
   }, [schoolId]);
@@ -108,6 +112,7 @@ export function PublicLoginBlock() {
       await requestEmailCode(email);
       setOtpStep("otp");
     } catch (caught) {
+      if (isSsoRequired(caught)) setSsoRequired(true);
       setError(
         caught instanceof Error ? caught.message : "Unable to send a sign-in code.",
       );
@@ -166,9 +171,18 @@ export function PublicLoginBlock() {
     signInWithGoogle(destinationAfterLogin());
   }
 
-  const showEmail = loginMethods.includes("email");
-  const showGoogle = loginMethods.includes("google");
-  const hasExternal = showGoogle;
+  function handleSsoSignIn() {
+    setError(null);
+    setLoading(true);
+    if (identityLinkToken) writeLearnerIdentityLink(identityLinkToken);
+    signInWithSso(destinationAfterLogin());
+  }
+
+  // When the email's domain requires SSO, the email form gives way to the SSO button.
+  const showEmail = loginMethods.showEmail && !ssoRequired;
+  const showGoogle = loginMethods.showGoogle && !ssoRequired;
+  const showSso = loginMethods.showSso;
+  const hasExternal = showGoogle || showSso;
 
   return (
     <div className="mx-auto flex w-full max-w-md flex-col gap-4 py-12">
@@ -276,6 +290,14 @@ export function PublicLoginBlock() {
               onClick={handleGoogleSignIn}
             />
           ) : null}
+          {showSso ? (
+            <ExternalLoginButton
+              provider="sso"
+              label={loginMethods.ssoLabel}
+              disabled={loading}
+              onClick={handleSsoSignIn}
+            />
+          ) : null}
         </div>
       ) : null}
 
diff --git a/apps/storefront/lib/learner-sign-in.ts b/apps/storefront/lib/learner-sign-in.ts
index 940b00902..170af5e8b 100644
--- a/apps/storefront/lib/learner-sign-in.ts
+++ b/apps/storefront/lib/learner-sign-in.ts
@@ -1,4 +1,5 @@
 import { CAPTCHA_ERROR_MESSAGE, captchaHeaders } from "@courselit/page-blocks/captcha";
+import { SignInRefusedError, SSO_REQUIRED_MESSAGE } from "@/lib/login-methods";
 import { writeSignedInHint } from "@/lib/header-account";
 import { learnerHeaders } from "@/lib/school";
 
@@ -15,6 +16,15 @@ async function errorMessage(response: Response, fallback: string): Promise<strin
   if (reason === "captcha_required" || reason === "captcha_failed") {
     return CAPTCHA_ERROR_MESSAGE;
   }
+  if (reason === "sso_required") {
+    throw new SignInRefusedError(reason, SSO_REQUIRED_MESSAGE);
+  }
+  if (reason === "sign_in_method_disabled") {
+    throw new SignInRefusedError(
+      reason,
+      "Email sign-in isn't available for this school.",
+    );
+  }
   if (body?.code === "rate_limited") {
     return "Please wait a moment before asking for another code.";
   }
@@ -73,6 +83,11 @@ export function signInWithGoogle(next: string) {
   window.location.assign(`/auth/google?next=${encodeURIComponent(next)}`);
 }
 
+/** Leave for single sign-on; the learner comes back to `next` on this site. */
+export function signInWithSso(next: string) {
+  window.location.assign(`/auth/sso?next=${encodeURIComponent(next)}`);
+}
+
 /** End the school session on this site. */
 export async function signOutLearner() {
   writeSignedInHint(false);
diff --git a/apps/storefront/lib/login-methods.test.ts b/apps/storefront/lib/login-methods.test.ts
new file mode 100644
index 000000000..d75108815
--- /dev/null
+++ b/apps/storefront/lib/login-methods.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from "bun:test";
+import {
+  DEFAULT_LOGIN_OPTIONS,
+  SignInRefusedError,
+  isSsoRequired,
+  loginErrorFromQuery,
+  resolveLoginOptions,
+  ssoButtonLabel,
+} from "./login-methods";
+
+describe("resolveLoginOptions", () => {
+  it("falls back to email only for a missing or malformed response", () => {
+    for (const data of [null, undefined, {}, { loginMethods: "email" }]) {
+      const options = resolveLoginOptions(data);
+      expect(options.showEmail).toBe(true);
+      expect(options.showGoogle).toBe(false);
+      expect(options.showSso).toBe(false);
+    }
+    expect(DEFAULT_LOGIN_OPTIONS.showEmail).toBe(true);
+  });
+
+  it("shows only the listed methods", () => {
+    const sso = resolveLoginOptions({ loginMethods: ["sso"], ssoDisplayName: "Acme" });
+    expect([sso.showEmail, sso.showGoogle, sso.showSso]).toEqual([false, false, true]);
+    const all = resolveLoginOptions({ loginMethods: ["email", "google", "sso"] });
+    expect([all.showEmail, all.showGoogle, all.showSso]).toEqual([true, true, true]);
+    const google = resolveLoginOptions({ loginMethods: ["google"] });
+    expect([google.showEmail, google.showGoogle, google.showSso]).toEqual([false, true, false]);
+  });
+
+  it("ignores unknown methods", () => {
+    expect(resolveLoginOptions({ loginMethods: ["email", "magic"] }).loginMethods).toEqual([
+      "email",
+    ]);
+  });
+
+  it("labels the SSO button", () => {
+    expect(ssoButtonLabel("Acme Corp")).toBe("Sign in with Acme Corp");
+    expect(ssoButtonLabel("  ")).toBe("Sign in with SSO");
+    expect(ssoButtonLabel(null)).toBe("Sign in with SSO");
+    expect(resolveLoginOptions({ loginMethods: ["sso"], ssoDisplayName: "Okta" }).ssoLabel).toBe(
+      "Sign in with Okta",
+    );
+  });
+});
+
+describe("login errors", () => {
+  it("maps the error query value", () => {
+    expect(loginErrorFromQuery("google")).toContain("Google");
+    expect(loginErrorFromQuery("sso")).toContain("Single sign-on");
+    expect(loginErrorFromQuery("other")).toBeNull();
+    expect(loginErrorFromQuery(null)).toBeNull();
+  });
+
+  it("recognises an SSO-required refusal", () => {
+    expect(isSsoRequired(new SignInRefusedError("sso_required", "x"))).toBe(true);
+    expect(isSsoRequired(new SignInRefusedError("sign_in_method_disabled", "x"))).toBe(false);
+    expect(isSsoRequired(new Error("x"))).toBe(false);
+  });
+});
diff --git a/apps/storefront/lib/login-methods.ts b/apps/storefront/lib/login-methods.ts
new file mode 100644
index 000000000..5b1d57009
--- /dev/null
+++ b/apps/storefront/lib/login-methods.ts
@@ -0,0 +1,67 @@
+// Which sign-in options a school offers, decided from the public
+// login-methods response. Kept free of React so it can be tested.
+
+export type LoginMethod = "email" | "google" | "sso";
+
+export type LoginOptions = {
+  loginMethods: LoginMethod[];
+  showEmail: boolean;
+  showGoogle: boolean;
+  showSso: boolean;
+  ssoLabel: string;
+};
+
+export const DEFAULT_LOGIN_OPTIONS: LoginOptions = resolveLoginOptions(null);
+
+const KNOWN: LoginMethod[] = ["email", "google", "sso"];
+
+/** Label of the SSO button: "Sign in with <name>", or "Sign in with SSO". */
+export function ssoButtonLabel(displayName?: string | null): string {
+  const name = displayName?.trim();
+  return `Sign in with ${name ? name : "SSO"}`;
+}
+
+/** Turn the login-methods response into what the sign-in forms show. A
+ * missing or malformed response falls back to email only. */
+export function resolveLoginOptions(
+  data: { loginMethods?: unknown; ssoDisplayName?: unknown } | null | undefined,
+): LoginOptions {
+  const listed = Array.isArray(data?.loginMethods) ? data.loginMethods : null;
+  const loginMethods = listed
+    ? KNOWN.filter((method) => listed.includes(method))
+    : (["email"] as LoginMethod[]);
+  return {
+    loginMethods,
+    showEmail: loginMethods.includes("email"),
+    showGoogle: loginMethods.includes("google"),
+    showSso: loginMethods.includes("sso"),
+    ssoLabel: ssoButtonLabel(
+      typeof data?.ssoDisplayName === "string" ? data.ssoDisplayName : null,
+    ),
+  };
+}
+
+/** The message for the `?error=` value a failed provider start redirects with. */
+export function loginErrorFromQuery(value: string | null): string | null {
+  if (value === "google") return "Google sign-in didn't finish. Please try again.";
+  if (value === "sso") return "Single sign-on didn't finish. Please try again.";
+  return null;
+}
+
+export const SSO_REQUIRED_MESSAGE =
+  "Your school requires single sign-on for this email address. Use the button below to continue.";
+
+/** Raised when the email-code endpoint refuses because of the school's sign-in rules. */
+export class SignInRefusedError extends Error {
+  constructor(
+    readonly reason: "sso_required" | "sign_in_method_disabled",
+    message: string,
+  ) {
+    super(message);
+    this.name = "SignInRefusedError";
+  }
+}
+
+export function isSsoRequired(error: unknown): boolean {
+  return error instanceof SignInRefusedError && error.reason === "sso_required";
+}
diff --git a/bun.lock b/bun.lock
index f3bf82d0a..e7513802e 100644
--- a/bun.lock
+++ b/bun.lock
@@ -60,18 +60,20 @@
         "@better-auth/oauth-provider": "1.7.22",
         "@better-auth/utils": "0.5.1",
         "@better-fetch/fetch": "1.3.3",
-        "@codelitdev/billing": "0.9.0",
+        "@codelitdev/billing": "0.11.0",
         "@codelitdev/mcp-server-kit": "0.5.0",
         "@codelitdev/oauth-server-kit": "0.10.0",
         "@codelitdev/observability": "0.5.0",
-        "@codelitdev/platform": "0.9.0",
+        "@codelitdev/platform": "0.11.0",
         "@codelitdev/platform-conformance": "0.9.0",
         "@courselit/api-contract": "workspace:*",
         "@frontlit/text-editor": "0.1.0-alpha.3",
+        "@node-saml/node-saml": "5.2.0",
         "@ts-rest/express": "3.52.1",
         "@ts-rest/open-api": "3.52.1",
         "@types/nodemailer": "^8.0.1",
         "@types/pg": "8.23.1",
+        "@xmldom/xmldom": "0.8.15",
         "better-auth": "1.7.22",
         "better-call": "1.4.5",
         "dodopayments": "^2.61.1",
@@ -93,6 +95,7 @@
         "@types/swagger-ui-express": "4.1.8",
         "drizzle-kit": "0.31.10",
         "typescript": "5.9.3",
+        "xml-crypto": "6.4.0",
       },
     },
     "apps/storefront": {
@@ -178,10 +181,12 @@
     "@anatine/zod-openapi@1.14.2": "patches/@anatine__zod-openapi@1.14.2.patch",
   },
   "overrides": {
+    "@xmldom/xmldom": "0.8.15",
     "esbuild": "0.28.2",
     "postcss": "8.5.28",
     "qs": "6.16.1",
     "ts-deepmerge": "8.0.0",
+    "xml-crypto": "6.4.0",
   },
   "packages": {
     "@alloc/quick-lru": ["@alloc/quick-lru@5.3.0", "", {}, "sha512-U4+70Pc5ZS9osnCBCE5Jha/ciHM+Yp+CNMNC/7HvYbNRk1Ldd+f7qO65W5qfhu/TCv+/ozljlXXe9Nj8419DMA=="],
@@ -284,7 +289,7 @@
 
     "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.12", "", { "os": "win32", "cpu": "x64" }, "sha512-B1R/l+CwEpKFSuqiwePzPNRk1EiJN8kc0UhdafNz6MZN9v5OFP9HYP1irptvWzHrwVI4blVNGMbxc5zt70m3IA=="],
 
-    "@codelitdev/billing": ["@codelitdev/billing@0.9.0", "", { "dependencies": { "drizzle-orm": "^0.45.2", "nanoid": "^5.1.6", "zod": "^3.25.76" }, "peerDependencies": { "dodopayments": "^2.48.0" }, "optionalPeers": ["dodopayments"], "bin": { "codelit-billing": "bin/codelit-billing.js" } }, "sha512-DvNczT1/JAauGr/GoTOQVqfLXTdh+eieLujoFFbfAt3NggOx+kRjNuPJm/DK/G7XVOl1Mx6HPx4KtkOKbfrhYA=="],
+    "@codelitdev/billing": ["@codelitdev/billing@0.11.0", "", { "dependencies": { "drizzle-orm": "^0.45.2", "nanoid": "^5.1.6", "zod": "^3.25.76" }, "peerDependencies": { "dodopayments": "^2.48.0" }, "optionalPeers": ["dodopayments"], "bin": { "codelit-billing": "bin/codelit-billing.js" } }, "sha512-eqX7WPmqlVKSDK10x/IkasQws+EKomnqPR68VrBto4hLzH2pMkF6NWAAg4vgyyOXqMykG85flth1GlDU72noFA=="],
 
     "@codelitdev/design-system": ["@codelitdev/design-system@0.5.0", "", { "peerDependencies": { "react": ">=18", "react-dom": ">=18" } }, "sha512-jcfS2X6HKc4wbDM3mIetOWyockNq0pEphlj5HXCXUrNnl0UPru1X9g4hPrX7KI2gsIyUsQwCm4rFVv8tLpY4Iw=="],
 
@@ -294,7 +299,7 @@
 
     "@codelitdev/observability": ["@codelitdev/observability@0.5.0", "", { "dependencies": { "pino": "^9.6.0" }, "peerDependencies": { "express": "^4.21.2", "posthog-js": "^1.200.0", "posthog-node": "^4.0.0" }, "optionalPeers": ["express", "posthog-js", "posthog-node"] }, "sha512-rQcB9fkaustBImNc3u7MSE4eCufD+DyLA02u2jLqoWcrq2cjrmTjbWrJ4AV4gdhtMGuiLjM0R6vdF9PWsTB7aQ=="],
 
-    "@codelitdev/platform": ["@codelitdev/platform@0.9.0", "", { "peerDependencies": { "@codelitdev/billing": ">=0.9.0", "drizzle-orm": "^0.45.2" }, "optionalPeers": ["@codelitdev/billing", "drizzle-orm"] }, "sha512-WblUIC8KDw9JKbJxikSlOfrlPnzsLv2Dux2zr8VS63qOkVKbfMEv0qQMKVYmK3cEFXVtgJ4XaHOOKMrIWJsLrQ=="],
+    "@codelitdev/platform": ["@codelitdev/platform@0.11.0", "", { "dependencies": { "tldts": "7.4.19" }, "peerDependencies": { "@codelitdev/billing": ">=0.11.0", "drizzle-orm": "^0.45.2" }, "optionalPeers": ["@codelitdev/billing", "drizzle-orm"] }, "sha512-4Q8HbLNyZodiWVEICEltrWTK8yjqAFCXb38yonZdSXr9eALxrCtfChf5xb9844N0hPVVmYSH+jcZpDtUtqhixg=="],
 
     "@codelitdev/platform-conformance": ["@codelitdev/platform-conformance@0.9.0", "", { "peerDependencies": { "@codelitdev/platform": ">=0.9.0" } }, "sha512-zP4u1MomIfiE3MVCYvUfO0M0zgqmyvUc6cDxbWw+x+rwErw3NJIoDKVmOl+h2gECWngA6IONIf4k5dmdqAKxfg=="],
 
@@ -522,6 +527,8 @@
 
     "@noble/hashes": ["@noble/hashes@2.4.0", "", {}, "sha512-X5XaVWZIBCT7HHZGm5I7ZQXDwLG+bGXuSrMQAW+7Zvl87h1kmc1ZB1VSRJcpUfoUrGQp4Fkoxm5kZ+Ms+aW+eA=="],
 
+    "@node-saml/node-saml": ["@node-saml/node-saml@5.2.0", "", { "dependencies": { "@types/qs": "^6.15.1", "@types/xml-encryption": "^1.2.4", "@types/xml2js": "^0.4.14", "@xmldom/is-dom-node": "^1.0.1", "@xmldom/xmldom": "^0.8.15", "xml-crypto": "^6.4.0", "xml-encryption": "^3.1.0", "xml2js": "^0.6.2", "xmlbuilder": "^15.1.1", "xpath": "^0.0.35" } }, "sha512-bWjGrSZmenN+SiFcDxQ7Di2C108nK2jofJ0NT56C/NC/ELmjZS+6QOpf6YByM6f+eLTgfisrYVdwsNRV+XZsxg=="],
+
     "@nodelib/fs.scandir": ["@nodelib/fs.scandir@2.1.5", "", { "dependencies": { "@nodelib/fs.stat": "2.0.5", "run-parallel": "^1.1.9" } }, "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g=="],
 
     "@nodelib/fs.stat": ["@nodelib/fs.stat@2.0.5", "", {}, "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A=="],
@@ -898,6 +905,14 @@
 
     "@types/validate-npm-package-name": ["@types/validate-npm-package-name@4.0.2", "", {}, "sha512-lrpDziQipxCEeK5kWxvljWYhUvOiB2A9izZd9B2AFarYAkqZshb4lPbRs7zKEic6eGtH8V/2qJW+dPp9OtF6bw=="],
 
+    "@types/xml-encryption": ["@types/xml-encryption@1.2.4", "", { "dependencies": { "@types/node": "*" } }, "sha512-I69K/WW1Dv7j6O3jh13z0X8sLWJRXbu5xnHDl9yHzUNDUBtUoBY058eb5s+x/WG6yZC1h8aKdI2EoyEPjyEh+Q=="],
+
+    "@types/xml2js": ["@types/xml2js@0.4.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4YnrRemBShWRO2QjvUin8ESA41rH+9nQGLUGZV/1IDhi3SL9OhdpNC/MrulTWuptXKwhx/aDxE7toV0f/ypIXQ=="],
+
+    "@xmldom/is-dom-node": ["@xmldom/is-dom-node@1.0.1", "", {}, "sha512-CJDxIgE5I0FH+ttq/Fxy6nRpxP70+e2O048EPe85J2use3XKdatVM7dDVvFNjQudd9B49NPoZ+8PG49zj4Er8Q=="],
+
+    "@xmldom/xmldom": ["@xmldom/xmldom@0.8.15", "", {}, "sha512-/5NV/vDALVFDXgLmfsy9TRCBlKwO2LNBFzpzvb9iIj+jR+eSc6DLYYvVOdivT/jm7MtU6TebYuRmzEOI7w40UA=="],
+
     "accepts": ["accepts@1.3.8", "", { "dependencies": { "mime-types": "~2.1.34", "negotiator": "0.6.3" } }, "sha512-PYAthTa2m2VKxuvSD3DPC/Gy+U+sOA1LAuT8mkmRuvw+NACSaeXEQ+NHcVF7rONl6qcaxV3Uuemwawk+7+SJLw=="],
 
     "ajv": ["ajv@8.20.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA=="],
@@ -1734,6 +1749,8 @@
 
     "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
 
+    "sax": ["sax@1.6.1", "", {}, "sha512-42tBVwLWnaQvW5zc4HbZrTuWccECCZfBi92FDuwtqxasH+JbPB3/FOKb1m222K42R4WxuxzzMsTswfzgtSu64Q=="],
+
     "scheduler": ["scheduler@0.27.0", "", {}, "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q=="],
 
     "selderee": ["selderee@0.11.0", "", { "dependencies": { "parseley": "^0.12.0" } }, "sha512-5TF+l7p4+OsnP8BCCvSyZiSPc4x4//p5uPwK8TCnVPJYRmU2aYKMpOXvw8zM5a5JvuuCGN1jmsMwuU2W02ukfA=="],
@@ -1820,6 +1837,10 @@
 
     "tinyexec": ["tinyexec@1.3.1", "", {}, "sha512-GCvB3aoys96IuDFBMcTB46JOR6mdMtAToqwiW8JlWhsoh1mhHi/xn9ss/Dg7N555GiJyEt2qzoG/NHCwM6h1EA=="],
 
+    "tldts": ["tldts@7.4.19", "", { "dependencies": { "tldts-core": "^7.4.19" }, "bin": { "tldts": "bin/cli.js" } }, "sha512-48dH6aSpQnpbzDUc4vIQZ1VjB8tkK+e8c1yx05/SZK+rkssgjEOlxDd/yU8/a4vGYQ9vRgJr9dwMq9TJ0b3X2Q=="],
+
+    "tldts-core": ["tldts-core@7.5.2", "", {}, "sha512-8W1topazDwhMKbm2I83IPa57Ow5VUxFgLbXv42+vSILnv8FY5OHvdEY/tS6WoWeMbxkHZQhra5cmeFHriKptSQ=="],
+
     "to-regex-range": ["to-regex-range@5.0.1", "", { "dependencies": { "is-number": "^7.0.0" } }, "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ=="],
 
     "toidentifier": ["toidentifier@1.0.1", "", {}, "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA=="],
@@ -1912,6 +1933,16 @@
 
     "wsl-utils": ["wsl-utils@1.0.0", "", { "dependencies": { "is-wsl": "^3.1.0", "powershell-utils": "^0.1.0" } }, "sha512-Hl0ZOAs672vg+06kfujwRhoS6/jehvULrlFkuF2dRu6pHgA8U06h3xqNIqNNU1LTXPcedxByAR4GS6pwQK0mgA=="],
 
+    "xml-crypto": ["xml-crypto@6.4.0", "", { "dependencies": { "@xmldom/is-dom-node": "^1.0.1", "@xmldom/xmldom": "^0.8.15", "xpath": "^0.0.33" } }, "sha512-d21ModhBO/+QWWAmOjyDeQJuHNmsR/HtOxyBchiTbKfGNKuHYwQNd+SlLhwyyrwoAGLp4Qc6BQ7nAtnM47dHSQ=="],
+
+    "xml-encryption": ["xml-encryption@3.1.0", "", { "dependencies": { "@xmldom/xmldom": "^0.8.5", "escape-html": "^1.0.3", "xpath": "0.0.32" } }, "sha512-PV7qnYpoAMXbf1kvQkqMScLeQpjCMixddAKq9PtqVrho8HnYbBOWNfG0kA4R7zxQDo7w9kiYAyzS/ullAyO55Q=="],
+
+    "xml2js": ["xml2js@0.6.2", "", { "dependencies": { "sax": ">=0.6.0", "xmlbuilder": "~11.0.0" } }, "sha512-T4rieHaC1EXcES0Kxxj4JWgaUQHDk+qwHcYOCFHfiwKz7tOVPLq7Hjq9dM1WCMhylqMEfP7hMcOIChvotiZegA=="],
+
+    "xmlbuilder": ["xmlbuilder@15.1.1", "", {}, "sha512-yMqGBqtXyeN1e3TGYvgNgDVZ3j84W4cwkOXQswghol6APgZWaff9lnbvN7MHYJOiXsvGPXtjTYJEiC9J2wv9Eg=="],
+
+    "xpath": ["xpath@0.0.33", "", {}, "sha512-NNXnzrkDrAzalLhIUc01jO2mOzXGXh1JwPgkihcLLzw98c0WgYDmmjSh1Kl3wzaxSVWMuA+fe0WTWOBDWCBmNA=="],
+
     "xtend": ["xtend@4.0.2", "", {}, "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ=="],
 
     "y18n": ["y18n@5.0.8", "", {}, "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA=="],
@@ -1964,6 +1995,8 @@
 
     "@modelcontextprotocol/server/zod": ["zod@4.6.6", "", {}, "sha512-4UmzQUF5fxvfcYHlbjBmejU+w+hbDnWFx4aS8kBx7nPBHcO2SqPbpAG8snbdg+Xse4pRefR98hgjFgIMCI/UhA=="],
 
+    "@node-saml/node-saml/xpath": ["xpath@0.0.35", "", {}, "sha512-8O+m2N04SwLpGw/1Grz2HD8ejnWDV7M1dMPgKKuOjhYh5W9H4pel/+06kInohIdpS2FeSbL4i8ID8c4tpxwq9Q=="],
+
     "@radix-ui/react-alert-dialog/@radix-ui/primitive": ["@radix-ui/primitive@1.1.7", "", {}, "sha512-rqWnm76nYT8HoNNqEjpgJ7Pw/DrBj5iBTrmEPo6HTX5+VJyBNOqTdv4g89G63HuR5g0AaENoAcH7Is5fF2kZ8Q=="],
 
     "@radix-ui/react-alert-dialog/@radix-ui/react-context": ["@radix-ui/react-context@1.2.2", "", { "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-RHCUGwKHDr0hDGg4X7ma4JG4/+12qxw8rkh5QKdDldlCvtja6nUx1Ef/8HVrJze81lEsgLQlqjzjGNHantgnQA=="],
@@ -2212,6 +2245,10 @@
 
     "@types/serve-static/@types/send": ["@types/send@0.17.6", "", { "dependencies": { "@types/mime": "^1", "@types/node": "*" } }, "sha512-Uqt8rPBE8SY0RK8JB1EzVOIZ32uqy8HwdxCnoCOsYrvnswqmFZ/k+9Ikidlk/ImhsdvBsloHbAlewb2IEBV/Og=="],
 
+    "@types/xml-encryption/@types/node": ["@types/node@26.4.1", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-k97ENvZWtvA6yqz5/FS6a7duDgOPEeOQOc2iKS/nY6mX6qJUKtLnWzQS+Xj6tXweyj6ZcTAK2Qecetnvi9nCLA=="],
+
+    "@types/xml2js/@types/node": ["@types/node@26.4.1", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-k97ENvZWtvA6yqz5/FS6a7duDgOPEeOQOc2iKS/nY6mX6qJUKtLnWzQS+Xj6tXweyj6ZcTAK2Qecetnvi9nCLA=="],
+
     "better-auth/zod": ["zod@4.6.6", "", {}, "sha512-4UmzQUF5fxvfcYHlbjBmejU+w+hbDnWFx4aS8kBx7nPBHcO2SqPbpAG8snbdg+Xse4pRefR98hgjFgIMCI/UhA=="],
 
     "body-parser/raw-body": ["raw-body@2.5.3", "", { "dependencies": { "bytes": "~3.1.2", "http-errors": "~2.0.1", "iconv-lite": "~0.4.24", "unpipe": "~1.0.0" } }, "sha512-s4VSOf6yN0rvbRZGxs8Om5CWj6seneMwK3oDb4lWDH0UPhWcxwOWw5+qk24bxq87szX1ydrwylIOp2uG1ojUpA=="],
@@ -2320,6 +2357,10 @@
 
     "wsl-utils/powershell-utils": ["powershell-utils@0.1.0", "", {}, "sha512-dM0jVuXJPsDN6DvRpea484tCUaMiXWjuCn++HGTqUWzGDjv5tZkEZldAJ/UMlqRYGFrD/etByo4/xOuC/snX2A=="],
 
+    "xml-encryption/xpath": ["xpath@0.0.32", "", {}, "sha512-rxMJhSIoiO8vXcWvSifKqhvV96GjiD5wYb8/QHdoRyQvraTpp4IEv944nhGausZZ3u7dhQXteZuZbaqfpB7uYw=="],
+
+    "xml2js/xmlbuilder": ["xmlbuilder@11.0.1", "", {}, "sha512-fDlsI/kFEx7gLvbecc0/ohLG50fugQp8ryHzMTuW9vSa1GJ0XYWKnhsUx7oie3G98+r56aTQIUB4kht42R3JvA=="],
+
     "@babel/core/debug/ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
 
     "@babel/traverse/debug/ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
@@ -2434,6 +2475,10 @@
 
     "@types/serve-static/@types/node/undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
 
+    "@types/xml-encryption/@types/node/undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
+
+    "@types/xml2js/@types/node/undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
+
     "cross-spawn/which/isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
 
     "enquirer/strip-ansi/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
diff --git a/docs/user-deletion.md b/docs/user-deletion.md
index f05f17a8c..6ca0522a0 100644
--- a/docs/user-deletion.md
+++ b/docs/user-deletion.md
@@ -206,3 +206,12 @@ deleteUser
 | Courses                      | Migrate   | `CourseModel.updateMany()`                                                                                                                               | [x] Preserved |
 | Templates                    | Migrate   | `EmailTemplateModel.updateMany()`                                                                                                                        | [x] Preserved |
 | Sequences                    | Migrate   | `SequenceModel.updateMany()`                                                                                                                             | [x] Preserved |
+
+## SSO shadow users (rewrite)
+
+Learners who only ever sign in through a school's SSO connection are owned by a
+shadow user (`sso_shadow_users`), because `school_accounts.user_id` must point at
+a `user`. Deleting a school account (the `erase_sendlit_contact` purge) also
+deletes its shadow user once it owns no school account, so no personal data is
+left behind. Shadow users are never touched by platform user deletion flows: they
+have no password, no Better Auth session and an unreachable `.invalid` address.
diff --git a/docs/wip/rewrite-sso-implementation.md b/docs/wip/rewrite-sso-implementation.md
new file mode 100644
index 000000000..b090ac1fc
--- /dev/null
+++ b/docs/wip/rewrite-sso-implementation.md
@@ -0,0 +1,706 @@
+# Learner SSO for school websites: implementation plan
+
+Status: SAML (Phases 1–5) implemented on branch `feat/learner-sso`; OIDC (Phase 6) not started. Tracker #33. Built before the rest of tiered billing; see "Order of work, alongside tiered billing".
+
+### Implementation notes
+
+What changed from the plan while building it:
+- **Tested against Keycloak 26.4** in a browser, end to end (admin setup from pasted metadata, test sign-in, activation, learner sign-in, enforcement, turning off). This found the disabled-connection deadlock above, and that Keycloak's default client signs only the Response, which we refuse. The admin test result now explains what to change for the fixable failure reasons.
+- **Package versions:** the `@codelitdev/platform` and `@codelitdev/billing` additions are in platform PR #37. Until it's released, `apps/api/package.json` points at locally packed builds, and that must change to the published version before this branch merges.
+- **Shadow user marker:** shadow users are marked by the `sso_shadow_users` table, not a `user.kind` column.
+- **Ticket columns:** `school_auth_tickets` also carries `sso_connection_id` and `session_expires_at`, so the connection and the IdP's session end reach the session.
+- **Plan sync on a "no":** `hasFeature` answers false when billing can't be read. So before suspending anything, the plan sync confirms a false answer with `commercialState()`, which throws on a read error, and the job then retries.
+- **Billing hook jobs:** the hook queues `sync_plan_features` rows in `integration_outbox_jobs` (provider `platform`). The worker drains them every few seconds and runs an hourly sweep: cleanup, domain re-checks and a daily plan sync.
+- **MCP parity:** the SSO write operations are session-only, so MCP credentials can't reach them. They are exempt in `mcp-parity.ts` and don't appear in `REACHABLE_BUT_EXEMPT`.
+- **Follow-up:** there is no operation that lists the identities linked to a connection, so the admin has no unlink button yet (`unlinkSsoIdentity` exists).
+- **Follow-up:** CODEOWNERS for `apps/api/src/sso-protocol/` waits on a decision about who owns it.
+
+## Scope
+
+- SSO lets **learners** sign in to **one school's website** through that school's own identity provider (IdP): Okta, Entra ID, OneLogin, Google Workspace and similar.
+- It is configured per school. Google sign-in is different: the platform provides it, and a school can only turn it on or off.
+- SSO never signs anyone in to the admin, never creates a CourseLit-wide (Better Auth) session, and never creates, verifies or changes a platform `user` by email.
+
+## The trust problem
+
+Google proves a person owns an email address. A school's IdP proves nothing: a school admin can make their IdP say `anyone@anycompany.com`. So whatever an SSO response says can only create or change things inside the school that owns the connection.
+
+These parts of the current learner sign-in code must never see an SSO response:
+
+| Code | Why it is unsafe for SSO |
+| --- | --- |
+| `findOrCreateVerifiedUser` (`apps/api/src/learners.ts`) | If the platform user with that email is unverified, it marks them verified and deletes their password and sessions. Any school could take over and lock out platform users. |
+| `ensureSchoolAccount`, which matches by school + email | The IdP would be given any existing learner account in the school, including a team member's. |
+| `admitLearner`, which updates name and image | It would change details of a platform user who isn't the IdP's to change. |
+
+## Decisions
+
+Decisions 1–3 and 6 were confirmed on 2026-11-13.
+
+1. **SSO-only learners get a shadow platform user that can't sign in.** Accepted on the condition that it stays safe. The guarantees it depends on, each with a test, are under "Shadow users" and in risks 14–16 of the security review. `school_accounts.user_id` (and the `user_id` on `school_sessions` and `school_auth_tickets`) has to point at a `user`, and `communities.ts` and `team.ts` depend on that. Making `user_id` nullable means a bigger refactor; leave it for later.
+2. **One connection model covers SAML and OIDC. SAML ships first** (tracker #33 and main both use SAML). OIDC follows once there's a guard on outbound requests to internal addresses (see Phase 6).
+3. **On courselit.app, SSO comes with the Business plan.** The rewrite has two paid tiers, `pro` and `business`; Pro doesn't include SSO.
+   - Schools with no paid plan can't use SSO either.
+   - When there's no hosted billing (`billingMode = "oss"`, self-hosted), SSO is always available. See Phase 5.
+4. **No IdP-initiated sign-in in v1.** Every sign-in starts from the school's website.
+5. **Don't reuse main's `@better-auth/sso` plugin.** It is built around Better Auth sessions and platform users.
+6. **The SAML/OIDC protocol layer stays in CourseLit, as a self-contained module `apps/api/src/sso-protocol/`. It doesn't go into `@codelitdev/oauth-server-kit`.**
+   - The kit handles how people sign in to each CodeLit product's own apps. No CodeLit product lets an admin sign in with SSO, and learner SSO on school websites is CourseLit-only. The AGENTS.md rule moves code into a package only when other apps would benefit, and none would.
+   - The module is still built like package code: no imports from the rest of CourseLit, a small interface (`createSamlServiceProvider`, `parseSamlIdpMetadata`, the store interfaces), and its own tests with a fixture IdP. If another product ever needs it, it moves into the kit unchanged.
+   - Without the kit maintainers' security rota, CourseLit owns updates to the XML libraries. Pin exact versions and add the module to CODEOWNERS so changes to it always get an auth review.
+7. **Sign-in methods per school, as on main.** A "Login providers" area turns email codes, Google and SSO on or off for each school. It ships with SSO; see Phase 4.
+
+## CodeLit packages
+
+Use the `@codelitdev/*` packages wherever they already do the job. Where something is missing and isn't specific to CourseLit, add it to the package rather than writing a CourseLit-only copy. Versions in use: `platform` 0.9.0, `oauth-server-kit` 0.10.0, `billing` 0.9.0, `mcp-server-kit` 0.5.0, `observability` 0.5.0, `platform-conformance` 0.9.0, `design-system` 0.5.0.
+
+### Existing exports to use
+
+| Need | Package export | Notes |
+| --- | --- | --- |
+| Public IDs for connections | `@codelitdev/platform` `createPublicId` / `parsePublicId` | Prefix `sso`, like every other public id in the API |
+| IDs and time | `@codelitdev/platform` `uuidv7`, `Clock` | As in `learner-sign-in.ts` |
+| Errors | `@codelitdev/platform` `createPlatformError` (with `safeDetails.reason`), `captureAndMapException` | Reason codes stay in `safeDetails` or the audit log; the browser gets one generic message |
+| Encrypting the OIDC client secret | `@codelitdev/platform` `createAesGcmSensitiveValues` | Use this instead of `utils/integration-secrets.ts`. It supports `previousKeys`, so the key can be rotated. Uses its own `SSO_ENCRYPTION_KEY` / `SSO_ENCRYPTION_PREVIOUS_KEYS`. |
+| Audit log | `@codelitdev/platform` `AuditPort<Context, Event>` | `school_sso_events` is written by a CourseLit implementation of this interface |
+| Recent sign-in for owner-only writes | `@codelitdev/oauth-server-kit/better-auth` `isRecentlyAuthenticated` | Already wrapped in `auth/recent-authentication.ts`; `schoolOwnerOp(["session"], true)` uses it |
+| Client IP for rate limits | `@codelitdev/oauth-server-kit/express` `createClientIpMiddleware` | Already in `express-app.ts`. Rate-limit the SSO start and ACS by the IP it resolves, never by raw `X-Forwarded-For`. |
+| Platform sessions never created for shadow users | `@codelitdev/oauth-server-kit/better-auth` `resolveBetterAuthSession` | Besides the Better Auth `databaseHooks` guard, reject users listed in `sso_shadow_users` where the kit resolves a session, as a second layer |
+| Plan check and plan-change signal | `@codelitdev/billing` `hasFeature` (new, below), `hooks.lifecycle.afterProjection` | See Phase 5 |
+| MCP parity and the exemptions | `@codelitdev/mcp-server-kit` `validateParityManifest`, `McpToolRisk` | The exemptions for the SSO write operations go through the existing manifest and `mcp-api.test.ts` |
+| Contract conformance | `@codelitdev/platform-conformance` `runPlatformConformance` | The new operations go through the existing conformance adapter, the same as every other operation |
+| Logging and error tracking | `@codelitdev/observability` `opaqueSubjectId`, `redactText`, `isSensitiveKey` | SSO failures are logged with a hashed subject and email domain only. Never send assertion XML, attributes or emails to logs or PostHog. |
+| Admin UI | `@codelitdev/design-system` | Login providers page and connection editor |
+
+Other CodeLit products:
+
+- **Storefront UI:** `@frontlit/page-builder` primitives only (AGENTS.md).
+- **Owner emails** (config changed, domain verification lapsed, SSO suspended): use the existing school/system email path (`queueSchoolEmail` / `system-mail.ts`) and admin notifications. Don't build new email rendering; anything missing comes from SendLit's packages (`@sendlit/email-blocks`), not a CourseLit copy.
+- **Marketing email off for SSO-created contacts:** use the existing `setContactMarketingSubscription` / SendLit contact sync, not new logic.
+
+### Additions to CodeLit packages
+
+**`@codelitdev/platform` → `createOutboundFetch(options)`.** Needed for Phase 6 (OIDC discovery and JWKS). Webhooks and anything else that fetches admin-supplied URLs can use it later. It allows https only, resolves DNS and refuses private, loopback and link-local addresses, checks again after each redirect, and caps time and response size.
+
+**`@codelitdev/platform` → `createDomainVerification(options)`.** Needed by Phase 2 (`normalizeDomain` when matching email domains) and Phase 4 (the domain verification endpoints).
+
+FrontLit (`apps/api/src/domains/queries.ts`) and CourseLit (`apps/api/src/school-hosts.ts`, `school-host.ts`) each have a near-identical copy of custom-domain verification:
+- an ownership TXT token at `<label>.<host>`
+- a routing check: the CNAME chain reaches the target, or for an apex, CNAME flattening or matching A records
+
+So the package covers all of that, not just the TXT part SSO needs, and both apps replace their copies with it.
+
+- `normalizeHostname(input)`: lowercase, IDN to punycode, no trailing dot, no port, path or credentials, valid labels, at least one dot. Options reject IP literals and public suffixes (`com`, `co.uk`). This replaces CourseLit's `normalizeCustomHostname`. FrontLit's `normalizeHost` reads `Host` headers, which is a different job; it stays.
+- `issueOwnershipToken()`: random token, 16 bytes hex, the format both apps use today.
+- `ownershipRecord(hostname, { label })` → `{ type: "TXT", name, value }`. The label is set by the product (`_courselit-verification`, `_frontlit-verify`). The record value stays the bare token, so TXT records customers have already published keep working.
+- `verifyOwnership(hostname, token, { label })`: TXT lookup that matches the token after joining TXT chunks.
+- `verifyRouting(hostname, { cnameTarget, aRecords })`: follows CNAME chains (with loop protection), with the apex fallback both apps use.
+- `isApexHostname(hostname)`: public-suffix aware.
+- The resolver can be pointed at trusted recursive DNS servers rather than whatever the container is configured with. A spoofed answer to an ownership check would grant SSO linking, so ownership checks shouldn't depend on a resolver tenants might influence.
+- Every lookup goes through an injectable resolver, as CourseLit's `DnsResolver` already does. This gives FrontLit testable DNS, which it lacks today. Lookups also get a timeout (default 5 s), which neither app has today.
+- No storage, no environment reads and no product rules. These stay in each app:
+  - CourseLit: one custom domain per school; SSO domains unlocking identity linking.
+  - FrontLit: the apex/www pair sharing one TXT record on the apex, redirect domains, opening the site to search on first verification.
+
+**Who adopts it:**
+- CourseLit SSO uses `normalizeHostname`, `issueOwnershipToken`, `ownershipRecord` and `verifyOwnership`, with the same `_courselit-verification` label as custom domains. A school using `acme.com` for both a custom domain and SSO publishes two TXT records under the same name, with different tokens. Each check only accepts its own token, so one can never count as proof for the other.
+- CourseLit custom domains (`school-hosts.ts`) and FrontLit custom and redirect domains switch to the package in their own refactor PRs after the release. They aren't part of SSO.
+- SendLit's sending-domain checks (`settings/esp/domain-auth.ts`: DKIM, SPF, DMARC, MX) check records the email provider issues, not an ownership token, so they don't swap. They can still use the resolver and timeout later.
+
+**`@codelitdev/billing` → features on offers.** Needed for the Phase 5 plan check.
+- An offer, or the plan an offer belongs to, declares the feature keys it includes. CourseLit's would be `business: ["learner_sso"]`.
+- The engine exposes `hasFeature(billableEntityId, feature)`. It answers from `commercialState()`: the active paid plan and a subscription status that counts as entitled (active, trialing, or past due within the grace period). It fails closed when billing can't be reached, and in `oss` mode it reports every feature as available.
+- Every app on the billing package then gates features the same way, instead of each keeping its own plan-to-feature map.
+
+**Not added to any package:**
+- **The SAML/OIDC protocol layer** (decision 6). It lives in `apps/api/src/sso-protocol/`:
+  - `createSamlServiceProvider(config)`:
+    - Wraps `@node-saml/node-saml` with the settings from Phase 3 fixed in place: signed assertions, SHA-256, a 2-minute clock skew, `InResponseTo` always checked, `KeyInfo` certificates never trusted, checks on `Destination`, `Recipient`, `bearer` and `StatusCode`.
+    - Returns `{ buildAuthnRequestUrl, validatePostResponse, serviceProviderMetadata }`.
+  - `parseSamlIdpMetadata(xml)`: DTDs off and a size limit. Returns the entity ID, SSO URL and signing certificates.
+  - Store interfaces, implemented with `school_sso_requests` and `school_sso_assertion_ids`:
+    - `SsoRequestStore` (save, find, use up)
+    - `AssertionReplayStore` (insert, failing if the ID was seen before)
+  - Phase 6: `createOidcRelyingParty(config)`, wrapping `openid-client` (PKCE, `state`, `nonce`, allowed algorithms, `email_verified`), with the same store interfaces.
+  - It imports nothing else from CourseLit. Its tests use a fixture IdP and cover every response the Phase 3 list rejects.
+- **Linking identities, shadow users, school sessions, enforcement, sign-in methods and plan suspension.** These map identities to users and schools, which are CourseLit's own.
+
+Following AGENTS.md, each addition is built and released in the platform repo first; CourseLit then upgrades to that version and uses it. There's no temporary CourseLit-only copy. If a package release blocks a phase, that phase waits.
+
+## Order of work, alongside tiered billing
+
+SSO is built before the rest of tiered billing (prices, upgrades and downgrades, the upgrade prompt). Its only link to billing is the plan check in Phase 5: "does this school have Business?" and "tell me when that changes". The rest of SSO (data, linking identities, SAML, UI, security) doesn't depend on billing at all, and it's the larger and riskier part.
+
+0. **Platform package releases**, built at the same time as each other:
+   - `@codelitdev/platform` `createDomainVerification`, needed by Phases 2 and 4
+   - `@codelitdev/billing` features on offers, needed by step 1
+
+   CourseLit's Phase 1 (tables) doesn't need any of them and can start straight away.
+1. **The plan check (Phase 5).** Release features on offers in `@codelitdev/billing` (see "CodeLit packages"), upgrade CourseLit to it, declare `learner_sso` on Business and add the thin `schoolHasFeature` helper. Tiered billing needs this anyway.
+2. **SSO Phases 1–4, checked against that helper from the start.** The `sso-protocol` module (Phase 3) can be built at the same time as Phases 1–2.
+   - Self-hosted (`oss`): SSO works fully, so it can be tested end to end on the local stack.
+   - courselit.app (`cloud`): the helper says no unless the school is on Business. If tiers aren't live there yet, SSO is simply off; because it says no by default, it can't reach free or Pro schools by accident.
+3. **The rest of tiered billing.** Write the SSO suspension and restore sync and its daily job (Phase 5) here. They hook into `@codelitdev/billing`'s existing `afterProjection` lifecycle hook, so no new billing event is needed; but upgrades and downgrades have to work end to end before that can be tested.
+4. **SSO goes live on courselit.app once Business can be bought.** No SSO code changes are needed; the helper starts saying yes.
+
+Exception: if a customer is upgrading to Business specifically for SSO and needs it on day one, steps 3 and 4 have to ship together, and billing sets the deadline.
+
+## Overall flow
+
+It works like learner Google sign-in (`apps/api/src/learner-google-routes.ts`, `apps/api/src/learner-sign-in.ts`):
+
+```
+School website                    API host                           School's IdP
+---------------------------------------------------------------------------------------
+GET /auth/sso?next=…
+  sets nonce cookie (10 min)
+  POST /v1/learner/auth/sso/start ─▶ resolve school by host,
+     {host, nonce, next}             check that an active connection exists,
+                                     insert school_sso_requests row
+  ◀─ { url }                         (stores digests of the request token and nonce)
+302 ─────────────────────────────▶ GET /learner-login/sso/:conn/start
+                                     build AuthnRequest (ID kept on the request row)
+                                     302 ─────────────────────────────▶ sign-in
+                                   POST /learner-login/sso/:conn/acs  ◀─ SAMLResponse
+                                     + RelayState (= request token)
+                                     check response, use up request, link identity,
+                                     createSchoolAuthTicket(method 'sso')
+◀── 302 https://<school-host>/auth/complete?next=…#ticket=…
+existing ticket exchange → school_sessions row, school cookie
+```
+
+- The ticket only works on that school's host, only within 60 seconds, and only alongside the nonce cookie. That check already exists (`consumeSchoolAuthTicket`) and is what ties the sign-in to the browser that started it.
+- The SAML ACS receives a cross-site POST, so an API-host cookie set with `SameSite=Lax` wouldn't arrive. Don't add one; the nonce check above does that job.
+- RelayState and OIDC `state` only ever carry the opaque request token, never a URL.
+- The ACS URL and SP entity ID live on the API host and are unique per connection:
+  - `https://<api>/learner-login/sso/<connPublicId>/acs`
+  - `https://<api>/learner-login/sso/<connPublicId>/metadata`
+
+  A school changing its custom domain then doesn't break its IdP setup, and a response meant for one school fails the audience check of every other school.
+
+---
+
+## Phase 1: Data model
+
+Rewrite the original migrations; no ALTERs. Then reset the database and apply them again. Add a schema file `apps/api/src/db/schema/school-sso.ts` and export it from `index.ts`.
+
+### `school_sso_connections`
+
+| column | notes |
+| --- | --- |
+| `id` uuid PK, `public_id` text unique | prefix `sso` |
+| `school_id` → `schools.id` cascade | |
+| `protocol` | `'saml' \| 'oidc'` (check constraint) |
+| `status` | `'draft' \| 'active' \| 'suspended' \| 'disabled'`. `suspended` means the school lost the Business plan. The system sets and clears it, never the admin; see Phase 5. |
+| `display_name` | button label, e.g. "Acme employees" |
+| `enforcement` | `'optional' \| 'required_for_domains'` |
+| `max_session_minutes` int null | null means the school session default |
+| `idp_entity_id`, `idp_sso_url` | SAML. `idp_sso_url` must be an absolute `https:` URL with no credentials. Check this when saving and again when building the redirect, so the 302 can never point to `http:`, `javascript:` or `data:`. |
+| `idp_certificates` text[] | SAML; PEM; more than one allowed so certificates can be rotated |
+| `subject_attribute` text null | SAML; the attribute to use as the subject when NameID isn't `persistent` |
+| `oidc_issuer`, `oidc_client_id`, `oidc_client_secret` | OIDC; secret encrypted with `@codelitdev/platform`'s `createAesGcmSensitiveValues` (see "CodeLit packages") |
+| `tested_at`, `tested_config_digest` | set by a successful test sign-in. `tested_config_digest` is a hash of the settings the test ran against (entity ID, SSO URL, certificates, subject attribute). Activation requires it to match the current settings, so a draft can't be tested with one certificate and activated with another. |
+| `created_at`, `updated_at` | |
+
+- Partial unique index: at most one `active` connection per school in v1.
+
+### `school_sso_domains`
+
+| column | notes |
+| --- | --- |
+| `id`, `connection_id` → cascade, `school_id` | |
+| `domain` | lowercased, no leading `@` |
+| `verification_token` | from `issueOwnershipToken()`; published as a TXT record at `_courselit-verification.<domain>` whose value is the token, the same format as custom domains (see "CodeLit packages") |
+| `verified_at` | |
+
+- Unique `(school_id, domain)`. Don't make domains unique across schools:
+  - Proving DNS control already stops a school from claiming a domain it doesn't own.
+  - Two schools run by the same company may both use `acme.com`.
+  - A global lock would let whoever verifies first block the real owner.
+- The token is random for each (school, domain) pair and is never reused.
+- Store domains as lowercase ASCII (IDN converted to punycode) with no trailing dot. An email's domain has to match exactly; subdomains don't count.
+- Check the TXT record again on a schedule (weekly) and before activation.
+  - Clear `verified_at` only after three checks in a row find the record missing, not after one DNS error. Until then, show a warning in the admin.
+  - Once `verified_at` is cleared, the domain can't link new identities and its enforcement stops. Email the owner.
+- Tokens are issued separately for each purpose (custom domain, SSO domain) and are never derived from each other. Each check compares against its own row's token only.
+
+### `school_sso_identities`
+
+| column | notes |
+| --- | --- |
+| `id`, `school_id`, `connection_id` → cascade | |
+| `issuer` | IdP entity ID / OIDC issuer at the time of linking; must equal the connection's current one |
+| `subject` | SAML persistent NameID, or the immutable attribute set on the connection (e.g. Entra `objectidentifier`); OIDC `sub`. Never a transient NameID, and never an email-format NameID: email addresses get reassigned to new people. |
+| `school_account_id` → `school_accounts.id` cascade | |
+| `last_email`, `last_signed_in_at` | |
+
+- Unique `(connection_id, subject)` and unique `(connection_id, school_account_id)`.
+
+### `school_sso_requests`
+
+Shaped like `school_login_requests`, plus:
+
+- `connection_id`
+- `protocol_request_id`: the SAML AuthnRequest ID or OIDC state digest
+- `oidc_nonce`, `pkce_verifier`: OIDC
+- `purpose`: `'sign_in' | 'test'`
+- `started_by_school_account_id`: only for `test`. The test result can be read only by the admin who started it.
+
+### `school_sso_assertion_ids`
+
+Replay cache:
+
+- `(connection_id, assertion_id)` primary key, plus `expires_at`.
+- Delete expired rows in the existing queue cleanup.
+
+### Changes to existing tables
+
+- `school_sessions.authentication_method` and `school_auth_tickets.authentication_method` accept `'sso'`; update the TS unions in `learners.ts` and `learner-sign-in.ts`.
+- Add `school_sessions.sso_connection_id` (nullable, cascade), so disabling a connection deletes its sessions.
+- Add `sso_shadow_users (user_id PK → user cascade, school_id → schools cascade, created_at)` to mark shadow users. It's a separate table, not a `kind` column on Better Auth's `user`, so Better Auth's schema and sign-up input stay untouched and nothing a user submits can set it.
+- Add `school_sso_events` as an audit log: config changes, activations, domain verifications, sign-in failures (reason code only).
+
+## Phase 2: Linking identities (`apps/api/src/learner-sso.ts`)
+
+These are pure functions with unit tests. They don't depend on SAML or OIDC; the input is an assertion that has already been checked: `{ connection, subject, email, name }`.
+
+```
+linkSsoIdentity(db, input, clock) → Result<schoolAccount>
+```
+
+0. **Parse the email strictly.**
+   - Plain `local@domain` only: no quoted local part, no comments, no second `@`, no whitespace or control characters.
+   - Convert the domain to lowercase punycode.
+   - Reject anything else with `sso_invalid_email`.
+1. **Look for the identity by `(connection_id, subject)`.** It must also match on `issuer`. If found, load its school account.
+   - Refuse unless the account is `active`.
+   - Update `last_email` and `last_signed_in_at`.
+   - Change `school_accounts.email` / `display_name` only when all of these hold:
+     - the account's user is a shadow user
+     - the new email's domain is a verified domain of this connection
+     - the new email is unique within the school
+   - Never look up by email here, because emails change at the IdP.
+2. **Otherwise, check the domain.** Reject with `sso_domain_not_verified` unless the email's domain is a verified domain of this connection.
+3. **Look for a school account with that email in this school.**
+   - If one exists, link to it. Its `user_id` can be a real platform user; that's fine, because the user row is never touched.
+   - If none exists, create a shadow user, a school account and the identity row in one transaction.
+   - **Never call `ensureSchoolAccount` from SSO.** When it finds an account with the same email, it changes that account's `user_id` to the user it was called with.
+     - Suppose an email-code sign-in creates the real user's account between SSO's lookup and its insert. `ensureSchoolAccount(shadowUser)` would then move the real user's account onto the shadow user.
+     - So SSO inserts with `ON CONFLICT (school_id, email) DO NOTHING`. If the insert conflicts, it rolls back the shadow user, looks the account up again and links to it. It never changes the `user_id` of an account it didn't just create.
+   - **The other direction is allowed.** When someone later signs in with an email code or Google for that address, `ensureSchoolAccount` moves the shadow-backed account to their real user. They have proved they own the email.
+     - The SSO identity row stays linked to the account.
+     - The shadow user that's left over is deleted in the same transaction.
+     - Add a test for this.
+4. **Team check, on every SSO sign-in, not only the first.** If the school account has a `memberships` (team) row, reject with `sso_account_is_team_member`. Team members sign in to the school website with email or Google.
+   - This matters because team permissions carry into the school website session. `space-access.ts:staffSpaceIds` and community moderation give staff extra access there, and an IdP must never get it.
+   - The request-time check in "Session checks" below covers accounts that join the team after signing in.
+5. Record a `learner_signed_in` activity with method `sso`, the same way `admitLearner` does.
+
+The browser only ever sees one generic error, "We couldn't sign you in with <displayName>". Reason codes go to the audit log, never to the IdP-signed user, so the response can't be used to probe for team membership or existing accounts.
+
+### Session checks (`authenticateLearner`)
+
+- `authenticateLearner` checks a method allowlist on every request; add `'sso'` there.
+- An `sso` session is accepted only while its `sso_connection_id` is still `active`. Join this in the same query.
+  - Disabling a connection then works immediately, even if deleting sessions fails.
+  - Losing the Business plan works the same way, because it sets the connection to `suspended` (Phase 5).
+  - Don't call billing on every request.
+- **Nothing in a school website session uses `LearnerSession.userId` outside that school.** A linked account's `userId` can be a real platform user, so code that used it for something CourseLit-wide would carry the IdP's sign-in beyond the school.
+  - Today the learner paths only use it inside school-scoped queries.
+  - Add a test that fails if `LearnerSession.userId` is passed to a query on platform-wide tables (`user`, `session`, `account`, `selected_schools`, `memberships`), or keep a list of allowed uses in a comment and check it in review.
+  - Any future "delete my account" for learners deletes the school account only, never the platform user.
+- An `sso` session never gets team powers. `staffSpaceIds`, community moderation and every other storefront check that reads `memberships` must ignore team permissions when `authenticationMethod = 'sso'`. Pass the session, not just the `schoolAccountId`.
+
+### Team guards
+
+- Team invitations, accepting an invitation and membership grants in `team.ts` and `invitations.ts` refuse a school account that:
+  - has a `school_sso_identities` row, or
+  - belongs to a shadow user (`sso_shadow_users`).
+
+  Otherwise an IdP could reach an account that later becomes staff.
+- Removing the SSO link (an admin "unlink" action that deletes the identity row and that account's `sso` sessions) is the only way to make such an account eligible.
+
+### Shadow users
+
+- `createShadowUser(db, clock)` creates a user with:
+  - `email = sso-<uuidv7>@users.invalid`
+  - `emailVerified = false`
+  - a row in `sso_shadow_users`
+  - the name taken from the assertion
+  - no `account` rows
+- Guards, each with a test:
+  - The Better Auth `databaseHooks.session.create.before` rejects users in `sso_shadow_users`, so no platform session can ever be created for one.
+  - Team invitations and membership grants in `team.ts` and `invitations.ts` refuse school accounts whose user is `school_sso`.
+  - Platform-level user search and lookup skips shadow users.
+  - `findOrCreateVerifiedUser` never matches them. Their `.invalid` email can't be anyone's real email; add a test for it anyway.
+  - Nothing sends platform email to a shadow user's address.
+  - When a shadow user's last school account is deleted, the shadow user is deleted too. Add this to the user-deletion flow (`docs/user-deletion.md`) so personal data isn't left behind.
+- SSO-created school accounts start with marketing email off. The school can't use a fake IdP to add mailing-list contacts it has no consent for. The verified-domain rule already limits it to its own domains.
+
+### Enforcement
+
+When `enforcement = 'required_for_domains'`:
+
+- `requestLearnerEmailCode` and `startLearnerGoogleSignIn` check the email's domain. If it's a verified SSO domain of an active connection, they fail with `sso_required`.
+- For Google, also check in `finishLearnerGoogleSignIn` before admitting, because the email isn't known until Google returns.
+- The storefront then sends the learner to SSO.
+- So that no path is missed, put the same policy check in `issueSchoolSession`, which today is the only place a school session is created (called from `consumeSchoolAuthTicket` and `signInLearnerWithIdentity`): `sessionMethodAllowed(school, schoolAccount.email, method)`.
+- Turning enforcement on deletes the existing non-`sso` sessions of accounts in enforced domains. Otherwise people removed from the IdP keep their access until their sessions expire.
+
+## Phase 3: SAML (`apps/api/src/learner-sso-saml.ts`, `learner-sso-routes.ts`)
+
+Use `createSamlServiceProvider` from `apps/api/src/sso-protocol/`, which wraps `@node-saml/node-saml`; see "CodeLit packages". Never write our own XML signature checks. The settings below are fixed in the module; the routes only pass the per-connection values.
+
+### Configuration
+
+Build a `SAML` instance per connection with:
+
+- `callbackUrl` = the ACS URL
+- `issuer` = the per-connection SP entity ID
+- `entryPoint` = `idp_sso_url`
+- `idpCert` = `idp_certificates`
+- `idpIssuer` = `idp_entity_id`
+- `audience` = the SP entity ID
+- `wantAssertionsSigned: true`
+- `wantAuthnResponseSigned: false` (also accept it when signed)
+- `signatureAlgorithm: 'sha256'`, `digestAlgorithm: 'sha256'`
+- `acceptedClockSkewMs: 120_000`
+- `validateInResponseTo: 'always'`, with our own cache provider backed by `school_sso_requests`
+- `disableRequestedAuthnContext: true`
+- `identifierFormat`: `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`. If the IdP can only send an `emailAddress` or `unspecified` NameID, the connection must set `subject_attribute`, and the NameID is ignored. A transient or email NameID is never used as the subject (see `school_sso_identities`).
+
+### Routes, registered next to `registerLearnerGoogleRoutes` in `express-app.ts`
+
+- **`GET /learner-login/sso/:conn/start?request=…`**
+  - Find the open request.
+  - Check the connection is active, or draft when `purpose = 'test'`.
+  - Build the redirect URL with `RelayState` = the request token.
+  - Save the AuthnRequest ID on the request row, then 302.
+- **`POST /learner-login/sso/:conn/acs`**
+  - urlencoded body with a 256 KB limit, mounted before any global body parser so a larger global limit can't apply first.
+  - The module's `validatePostResponse` runs steps 1 and 3–6 in this order, through the store implementations. The route doesn't put the steps in its own order. Step 2 is a callback the route passes in, and step 7 is the route's.
+  - Steps:
+    1. Read `RelayState` and find the open request without using it up. It must be unused, unexpired and for the same connection.
+    2. Check the connection's status again here: `active` for `sign_in`, `draft` or `active` for `test`. The connection may have changed since the request started.
+    3. `validatePostResponseAsync` against that connection's config.
+    4. Check the top-level `StatusCode` is `Success`.
+    5. Only then use up the request, with one conditional update matching the RelayState digest, `InResponseTo`, the connection and "unused". Validating the signature first means a forged POST can't use up a real learner's request.
+    6. Insert the assertion ID into the replay cache. If the insert conflicts, reject.
+    7. Pull out the subject (persistent NameID or `subject_attribute`) and the email from the `email`/`mail` attribute. Reject when either is missing.
+  - Then branch on `purpose`:
+    - `sign_in`: `linkSsoIdentity`, then a ticket with method `'sso'`, then a 302 to `/auth/complete#ticket`.
+    - `test`: set `tested_at` and save the attributes received on the request row (kept for 15 minutes), then redirect to the admin connection page with only the request id. No account, no identity, no ticket. Never put attributes in a URL, where they would end up in logs and browser history.
+  - On failure, 302 to `<school>/login?error=sso`, or to the admin page for a test. Write a reason code to the audit log; never log assertion XML or attributes, and never send them back to the browser.
+
+### Checking the library's behaviour
+
+The module confirms each of these in `@node-saml/node-saml`, with a test for each. Wherever the library doesn't check something, the module adds its own check:
+
+- `Destination` and `SubjectConfirmationData/@Recipient` must equal the ACS URL.
+- `SubjectConfirmation` method `bearer`, with an unexpired `NotOnOrAfter`.
+- Certificates sent inside the response (`KeyInfo`) are never trusted; only the pinned ones are.
+- Only the signed assertion is used. Attributes from outside the signed element are ignored.
+
+Pin the exact version of the library and of `xml-crypto` / `@xmldom/xmldom` that comes with it. The XML libraries have had signature-bypass vulnerabilities (CVE-2024-32962, CVE-2025-29774/29775), so dependency update PRs for them get reviewed and merged quickly.
+- **`GET /learner-login/sso/:conn/metadata`**: SP metadata XML (the module's `serviceProviderMetadata`).
+- For `disabled` or `suspended` connections, every `/learner-login/sso/:conn/*` route answers the same way it answers an unknown connection. Admins get the SP values from the admin UI, not from the public route.
+
+### What gets rejected (each case gets a test using a fixture IdP key)
+
+- an unsigned assertion
+- an assertion signed by the wrong certificate
+- a SHA-1 signature
+- an assertion wrapped inside a signed element (XSW)
+- the wrong audience (another connection's entity ID)
+- the wrong `Destination`
+- an expired assertion
+- `NotBefore` in the future
+- an unknown or already used `InResponseTo`
+- a missing `InResponseTo` (IdP-initiated)
+- a replayed assertion ID
+- a DTD or external entity in the XML
+- a body over the size limit
+
+### Session lifetime
+
+`school_sessions.expires_at` is the earliest of:
+
+- the default
+- `max_session_minutes`
+- `SessionNotOnOrAfter`, when the IdP sends it
+
+`issueSchoolSession` gets an optional `expiresAt` and `ssoConnectionId`.
+
+## Phase 4: API contract, admin and MCP
+
+### Contract operations (`packages/api-contract`)
+
+School-scoped. Reads need the settings-read permission; writes are owner-only (see "Who can change SSO settings"):
+
+- `listSsoConnections`, `getSsoConnection`. Reads never return the OIDC client secret (it can be written but never read back; responses only say whether it is set), and never return test-sign-in attributes. Those come from a separate owner-only read for the admin who started the test.
+- `createSsoConnection`, `updateSsoConnection` (draft fields, metadata XML paste)
+- `addSsoDomain`, `verifySsoDomain` (via `@codelitdev/platform` `createDomainVerification`, 5 s timeout), `deleteSsoDomain`
+- `startSsoConnectionTest`: returns the URL that starts the test flow
+- `activateSsoConnection`, `disableSsoConnection`, `deleteSsoConnection`
+
+### Parsing metadata
+
+- Parse the pasted IdP metadata XML on the server with the module's `parseSamlIdpMetadata` (DTDs off, size limit).
+- Pull out the entity ID, the SSO URL (HTTP-Redirect binding) and the signing certificates.
+- v1 doesn't fetch metadata URLs.
+
+### Activation rules
+
+A connection can only be activated when:
+
+- it has at least one verified domain
+- `tested_at` is set
+- `schoolHasFeature(..., "learner_sso")` is true (Phase 5)
+
+Plan rules for the other actions:
+
+- Creating, editing, verifying domains and testing a draft connection are allowed on any plan. A school can prepare SSO before upgrading, and the admin UI shows a "Business plan" upgrade prompt on the Activate button.
+
+### Who can change SSO settings
+
+Whoever controls a connection's IdP settings can sign in as every learner linked to it. Changing the certificate or the entity ID is an account takeover of every SSO learner. So:
+
+- **Writes are owner-only and need a signed-in admin.** This covers create, update, domain changes, test, activate, disable, delete and unlink.
+  - Use `schoolOwnerOp(["session"], true)`: owner only, signed-in admin session only, recent sign-in required.
+  - API keys and OAuth clients can't make these changes.
+  - Reads (`list`/`get`) stay at the settings-read permission and are open to every credential.
+- **Changing what the connection trusts sends it back to draft.**
+  - Changing `idp_certificates`, `idp_sso_url` or `subject_attribute` on an active, suspended or turned-off connection sets it to `draft` and clears `tested_at`. It has to be tested again before activation, and its `sso` sessions are deleted.
+  - Turned-off (`disabled`) connections are included because only draft and active connections can be tested. Left disabled after a settings change, a connection could never be tested or turned back on.
+  - Adding a certificate for rotation follows the same rule.
+- **`idp_entity_id` / `oidc_issuer` can't be changed.** Pointing at a different IdP means creating a new connection, which starts with no identities. Identities are tied to their `issuer`, so they can never be inherited by a new IdP.
+- **Every change is audited and emailed.** Each write goes to `school_sso_events`, and the owner gets an email listing what changed.
+
+### MCP
+
+- REST/MCP parity: the write operations are only available with a signed-in admin session. Add them to `mcp-parity.ts` as exemptions with the reason "changes who can sign in as every SSO learner; owner session with recent sign-in only". Add them to `REACHABLE_BUT_EXEMPT` in `mcp-api.test.ts`.
+- `listSsoConnections` / `getSsoConnection` become MCP tools as usual, with descriptions in `apps/api/src/mcp-tools/operation-descriptions.ts`.
+- The browser routes (`/learner-login/sso/*`) aren't contract operations, just like the Google routes.
+
+### Rate limits
+
+- `POST /v1/learner/auth/sso/start`: limit per IP and per school, using the existing rate-limit table.
+- The ACS: limit per IP.
+- `verifySsoDomain`: limit per school.
+- Delete expired request, test-result and replay-cache rows in the queue's cleanup job.
+
+### Sign-in methods
+
+Same behaviour as main (`apps/web/graphql/settings/logic.ts` `toggleLoginProvider`, `apps/web/lib/login-providers.ts`), with one difference: Google is provided by the platform, so a school only turns it on or off and never enters Google credentials.
+
+- **Data:** `schools.login_methods text[]`, default `{email}`, check constraint `<@ {email, google}`. SSO isn't in the list: it is on exactly when the school has an `active` connection, so a second switch can't disagree with the connection's status.
+- **Rules:**
+  - At least one method stays on. Turning off the last of email, Google and an active SSO connection is refused, the same as main refusing to turn off email when it's the only one.
+  - Google can be turned on only when the platform has Google keys.
+  - If every method a school has turned on becomes unusable (for example SSO suspended by a plan change while email is off, or the platform's Google keys removed), email codes are used. Learners are never locked out of a school by something the school didn't choose.
+- **Where it's enforced:** in the same policy check as enforcement, `sessionMethodAllowed(school, email, method)` in `issueSchoolSession`, and early in `requestLearnerEmailCode` / `startLearnerGoogleSignIn` / SSO start. The storefront hiding a button isn't enforcement.
+  - Turning a method off deletes that school's existing sessions created with it (`school_sessions.authentication_method`). Otherwise turning off email codes wouldn't take effect until sessions expire.
+- **Operations:**
+  - `getSchoolLoginMethods` reads at the settings-read permission.
+  - `updateSchoolLoginMethods` needs settings-manage. It is in `MCP_HIGH_IMPACT_OPERATIONS` because it changes access settings, so it is `destructive` with `confirm: true`.
+  - It stays reachable over MCP. Unlike SSO connection settings, it can't hand anyone's account to someone else; the worst it can do is turn methods off, and the fallback above stops a lockout.
+- **Storefront:**
+  - Public sign-in settings return the methods that are on, plus SSO's `displayName`.
+  - `public-login-block.tsx` and `checkout-login-form.tsx` show only those.
+  - Checkout with email codes off offers the methods that are on.
+
+### Storefront API
+
+- `POST /v1/learner/auth/sso/start` with `{ host, nonce, next }`.
+- Public sign-in settings return `{ methods: ("email" | "google" | "sso")[], sso: { displayName } | null }` so the login block shows only the methods that are on.
+
+### Admin UI (`apps/admin`)
+
+Settings → Login providers. Base the layout and wording on main's `apps/web/components/admin/settings/sso.tsx`.
+
+- The Login providers area (see "Sign-in methods" below).
+- The SSO connection page:
+  1. Values to give to the IdP: ACS URL and entity ID, with copy buttons, and a link to download SP metadata.
+  2. The IdP metadata XML paste field, or manual entity ID, SSO URL and certificate fields.
+  3. Domains, showing the TXT record and verify status.
+  4. A "Test connection" button that shows the attributes the IdP sent.
+  5. Enforcement and session length.
+  6. Activate / Disable.
+
+### Storefront UI
+
+- `apps/storefront/app/schools/[schoolId]/auth/sso/route.ts`, copied from the Google route.
+- `signInWithSso(next)` in `lib/learner-sign-in.ts`.
+- A "Sign in with <displayName>" button in `public-login-block.tsx` and `checkout-login-form.tsx`, using page-builder primitives only.
+- An `sso_required` error from the email-code step switches the form to the SSO button.
+
+## Phase 5: Plan gating and docs
+
+### Checking the plan
+
+`school-billing.ts` already has the tier names (`"pro" | "business"`) and `billingMode` (`"cloud" | "oss"`).
+
+- Upgrade to the `@codelitdev/billing` release that adds features on offers (see "CodeLit packages"). Declare `learner_sso` on the Business offers next to `COURSELIT_OFFER_KEYS` in `apps/api/src/billing.ts`.
+- Add a thin helper, `schoolHasFeature(deps, schoolInternalId, feature)`, that calls the engine's `hasFeature`. The rules live in the package:
+  - every feature is available in `oss` mode
+  - only an entitled subscription status counts
+  - fail closed when billing can't be reached; never fall back to allowing SSO
+- `oss` mode turns on every feature, so the mode itself must not default to it by accident. Today `runtime.ts` uses `oss` only when `BILLING_MODE=oss` is set explicitly and otherwise uses `cloud`, which fails closed. Keep that, and add a test for it.
+- The helper exists only so CourseLit code has one place to name features. Its tests cover CourseLit's wiring; the rules themselves are tested in the package.
+- This is a CourseLit platform plan check, so `@codelitdev/billing` is the right package. That fits the billing segregation rule: it has nothing to do with learner payments, which never call this helper.
+
+### Where it's checked
+
+- `activateSsoConnection`.
+- `POST /v1/learner/auth/sso/start`. When the check fails, return a not-available error, and hide the button through the public sign-in settings.
+- The ACS, before a ticket is created. This catches a downgrade that happens during the 10 minutes a sign-in request is open.
+- Not in `authenticateLearner`. Existing sessions end through suspension instead, below.
+
+### Suspension when the plan changes
+
+When the school's plan stops including `learner_sso` (downgrade to Pro, cancellation taking effect, the subscription ending):
+
+- Set every `active` connection to `suspended`, in the queued `sync_plan_features` job. The job is committed with the plan change (see below).
+- Delete their `sso` sessions.
+- Turn enforcement off for the suspension, so learners in those domains can sign in with email codes or Google again instead of being locked out.
+- Email the owner.
+
+The plan-change signal already exists. `@codelitdev/billing` calls the `hooks.lifecycle.afterProjection({ material, previous, next, planState })` lifecycle hook whenever it saves a new subscription state, and `apps/api/src/billing.ts` currently registers it as an empty function.
+
+- Fill in that hook so it inserts a `sync_plan_features` queue job for the billable school, inside the billing transaction via `store.getTransaction()` (as the audit hook does). The job commits only if the plan change commits.
+  - Don't do the SSO work inside the hook. In Postgres, a failed statement aborts the whole transaction even if JS catches the error, so a bug in the SSO sync would roll back the billing write.
+  - Queue the job on every projection, not only when `material` is true. `syncPlanFeatures` reads the current plan itself and is safe to run any number of times, so correctness never depends on how billing classifies a change.
+- The daily job remains the backstop for anything missed.
+
+Also run a daily job in the queue that calls `syncPlanFeatures` for every school with an `active` or `suspended` connection. It catches a missed event and grace periods that have run out.
+
+When the school moves back to Business, `syncPlanFeatures` sets `suspended` connections back to `active`.
+- It runs the activation rules again first: a verified domain, and `tested_config_digest` matching the current settings. A domain may have lapsed while suspended. If the rules fail, the connection goes to `draft` and the owner is emailed.
+- Settings and identities are unchanged, so no new test is needed.
+- A connection whose settings changed while suspended went back to `draft` under the rules in Phase 4, so it isn't restored.
+- If enforcement was on, turning it back on follows the same rule as turning it on in the first place: existing non-`sso` sessions in enforced domains are deleted.
+
+### Admin UI
+
+- Show the plan requirement on the Login providers page, using the existing plan DTO (`readSchoolPlan`).
+- In `oss` mode, show no upgrade prompts.
+
+### Docs
+
+- a new page for the rewrite's docs, covering setup for Okta, Entra ID and Google Workspace. Main's docs apps stay untouched.
+
+## Phase 6: OIDC (after SAML ships)
+
+- Use `createOidcRelyingParty` from `apps/api/src/sso-protocol/`, which wraps `openid-client`. Authorization code flow with PKCE (S256), plus `state` and `nonce`.
+- Check that the ID token's `iss` matches the configured issuer exactly, and check `aud`, `azp`, `exp`, `iat` and `nonce`. Allow only RS256/ES256.
+- Use `email` only when `email_verified` is true, and still require the domain to be verified.
+- Discovery and JWKS fetches go through `@codelitdev/platform`'s new `createOutboundFetch`:
+  - https only
+  - resolve DNS and reject private, loopback and link-local addresses
+  - no redirects to internal hosts
+  - size and time limits
+- Callback: `GET /learner-login/sso/:conn/callback`. Same request and ticket handling as SAML.
+
+## Out of scope for v1
+
+- IdP-initiated sign-in
+- SCIM provisioning
+- single logout
+- encrypted assertions and signed AuthnRequests
+- more than one active connection per school
+- making `school_accounts.user_id` nullable
+
+## Security review
+
+These risks were found while reviewing this plan; the phases above already include the fixes.
+
+| # | Risk | Fix (where) |
+| --- | --- | --- |
+| 1 | Team permissions carry into the school website session (`space-access.ts:staffSpaceIds`, community moderation). An IdP could sign in as a staff account and get staff access on the website. The team check ran only on the first link. | Team check on every SSO sign-in; `sso` sessions never get team powers; team grants refuse SSO-linked accounts (Phase 2) |
+| 2 | Changing the IdP settings takes over every linked learner. Anyone with the settings permission, an API key or an MCP agent could swap in their own certificate. | Owner-only with a signed-in admin session and recent sign-in; no MCP or API key access; changes send the connection back to draft; entity ID can't be changed; audit log and owner email (Phase 4) |
+| 3 | Unstable subjects: transient NameIDs make a new account at every sign-in, and email-format NameIDs move with reassigned addresses, so a new employee would get a former employee's account. | Persistent NameID or an immutable attribute only; identities tied to their issuer (Phase 1) |
+| 4 | Changing the email on a later sign-in skipped the domain check. | Domain check on every email change (Phase 2) |
+| 5 | Using up the request before checking the signature let a forged POST cancel a real sign-in. | Check signature and status first, then use up the request in one conditional update (Phase 3) |
+| 6 | Turning off a connection or losing the Business plan didn't end SSO sessions straight away. | Check the connection status on every request; a plan change suspends connections and deletes their sessions (Phases 2 and 5) |
+| 7 | Domains unique across schools would let whoever verifies first lock the real owner out. | Unique per school; check the TXT record again on a schedule (Phase 1) |
+| 8 | Tricky email formats (quoted local parts, Unicode look-alikes, a second `@`) could get past the domain match. | Strict parsing, punycode, exact match (Phase 2) |
+| 9 | Enforcement could be bypassed through another sign-in path, or through sessions created before it was turned on. | Policy check inside `issueSchoolSession`; delete existing non-`sso` sessions when it's turned on (Phase 2) |
+| 10 | Test results in redirect URLs leak personal data into logs and history. | Save results on the server, readable only by the admin who started the test (Phase 3) |
+| 11 | Detailed errors let someone probe for team membership or existing accounts. | One generic browser error; reason codes in the audit log only (Phase 2) |
+| 12 | A fake IdP could add mailing-list contacts without consent. | Verified domains only; marketing email off by default (Phase 2) |
+| 13 | Signature-bypass bugs in the XML libraries. | Pin versions, CODEOWNERS on `sso-protocol/`, merge security updates quickly, test the library's checks one by one (Phase 3) |
+| 14 | Deleted SSO learners leave shadow users behind. | Delete the shadow user with its last school account (Phase 2) |
+| 15 | `ensureSchoolAccount` moves an existing account with the same email onto whichever user it's called with. If SSO called it during a race, a real learner's account would be moved onto a shadow user. | SSO never calls it; it inserts with `ON CONFLICT DO NOTHING` and links on conflict. An email-proven sign-in may move a shadow-backed account to the real user, and the leftover shadow user is deleted (Phase 2) |
+| 16 | A linked account's session carries a real platform `userId`. Any code using it outside the school would carry the IdP's sign-in further. | Rule plus a test: `LearnerSession.userId` is never used on platform-wide tables; learner deletion is school-scoped only (Phase 2) |
+| 17 | `afterProjection` work running inside the billing transaction: in Postgres a failed statement aborts the whole transaction, so an SSO bug would roll back the billing write. Relying on `material` could also miss changes. | The hook only queues a job in the same transaction, on every projection; the job is safe to run any number of times (Phase 5) |
+| 18 | A test passing with one certificate let the connection be activated after the certificate was swapped on a draft. | `tested_config_digest` must match the current settings to activate (Phase 1) |
+| 19 | A restored connection could come back with a domain that lapsed while suspended, or turn enforcement back on without ending other sessions. | Restoring runs the activation rules again and applies the enforcement session cleanup (Phase 5) |
+| 20 | An `idp_sso_url` that isn't https, or uses a scheme such as `javascript:`, ends up in a 302 `Location`. | Absolute `https:` only, checked when saving and when redirecting (Phase 1) |
+| 21 | Reads (open to API keys and MCP) returning the OIDC client secret or test attributes. | The secret can't be read back; test attributes go only to the admin who started the test (Phase 4) |
+| 22 | A spoofed DNS answer, or one failed lookup, deciding domain verification. | Configurable trusted resolvers in the package; clear verification only after three failed checks in a row (Phase 1, package) |
+| 23 | `oss` mode turns on every feature, so a cloud deployment that fell back to it by accident would give SSO to every school. | `BILLING_MODE` falls back to `cloud`; `oss` only when set explicitly, with a test (Phase 5) |
+| 24 | Turning off a sign-in method only hides its button, so the method still works through the API and existing sessions stay. | Enforced in `issueSchoolSession` and the start endpoints; turning a method off deletes its sessions; email is the fallback when nothing else works (Phase 4) |
+
+What we accept:
+
+- A school's IdP can sign in as any learner in that school whose email is in a domain the school verified. This includes accounts first created with email codes or Google.
+- The school controls those addresses and already sees those learners' data in that school. Nothing reaches other schools, the admin, or the platform user.
+
+## Test checklist
+
+Every behaviour change gets tests on each side it touches.
+
+- `linkSsoIdentity`:
+  - a found identity wins over email
+  - an unverified domain is rejected and nothing is created
+  - links to an existing learner account in a verified domain
+  - refuses an account with a team membership on every sign-in, including after the first one
+  - creates a shadow user only when needed
+  - never changes a platform user's `email`, `emailVerified`, `name` or `image`
+  - a changed email outside a verified domain doesn't change `school_accounts.email`
+  - strict email parsing: quoted local parts, a second `@`, IDN domains
+  - an identity from another issuer is never matched
+- Sessions:
+  - an `sso` session gets no staff spaces and can't moderate
+  - an `sso` session stops working the moment its connection is disabled or suspended
+- Who can change settings:
+  - API key and OAuth credentials are refused on writes
+  - a non-owner is refused
+  - changing the certificate sends the connection back to draft and deletes its sessions
+  - the entity ID can't be changed
+- ACS:
+  - a forged POST with a valid RelayState doesn't use up the request
+  - a test request never issues a ticket
+- Enforcement: turning it on deletes the existing non-`sso` sessions in enforced domains.
+- Plan:
+  - `schoolHasFeature("learner_sso")` is true for Business and false for Pro and unpaid schools in `cloud` mode (the package tests the general rules: `oss` mode, statuses, failing closed)
+  - activation is refused without Business; drafts can be prepared on any plan
+  - losing Business suspends connections, deletes `sso` sessions and turns enforcement off
+  - moving back to Business restores connections whose settings didn't change
+  - the ACS refuses to create a ticket after a downgrade mid-sign-in
+- Account races:
+  - SSO first sign-in racing an email-code sign-in never moves the real user's account onto a shadow user
+  - a later email-code or Google sign-in moves a shadow-backed account to the real user and deletes the shadow user
+- Billing hook: a failing `syncPlanFeatures` job never rolls back a billing write; the hook queues a job on every projection
+- Activation is refused when `tested_config_digest` doesn't match the current settings
+- `idp_sso_url` values that aren't `https:` are refused when saving
+- Reads never include the OIDC client secret
+- Shadow users:
+  - Better Auth refuses to create a session for one
+  - team invitations and grants refuse one
+  - `findOrCreateVerifiedUser` never matches one
+- SAML: every case in the Phase 3 list of rejected responses.
+- Flow:
+  - a ticket from school A can't be redeemed on school B
+  - a ticket can't be redeemed without the nonce cookie
+  - a request token works once
+  - a test sign-in issues no ticket
+- Enforcement: email codes and Google sign-in are refused for enforced domains.
+- Disabling a connection deletes its sessions; session expiry honours `SessionNotOnOrAfter`.
+- Sign-in methods:
+  - a method that's off is refused at its start endpoint and in `issueSchoolSession`
+  - turning a method off deletes its sessions
+  - the last method on can't be turned off
+  - when every method that's on becomes unusable, email codes still work
+  - Google can't be turned on without platform keys
+- Contract and MCP parity tests pass (descriptions, high-impact list).
diff --git a/frontlit/docs/learners/sign-in.md b/frontlit/docs/learners/sign-in.md
index 1dfa4abb6..809214abb 100644
--- a/frontlit/docs/learners/sign-in.md
+++ b/frontlit/docs/learners/sign-in.md
@@ -50,9 +50,13 @@ If the learner arrived from a page that needs sign-in, for example a course or a
 
 When Google sign-in is available for your school, a Google button appears below the email form, separated by **or**. Learners who use it come back to the same destination as the email flow. If Google does not complete, the page shows "Google sign-in didn't finish. Please try again."
 
+## Sign in with your organization's account (SSO)
+
+When your school has turned on single sign-on, a button labelled **Sign in with** followed by the name you chose appears on the sign-in page. Learners sign in at your identity provider and come back to the same destination as the email flow. If you require SSO for an email domain, learners with an address on that domain can only use this button. Setting it up is described in [Single sign-on (SSO)](/docs/self-hosting/single-sign-on).
+
 ## How long a sign-in lasts
 
-A session lasts 7 days on a device. A learner can end it earlier with **Log out** in the dashboard menu.
+A session lasts 7 days on a device. A learner can end it earlier with **Log out** in the dashboard menu. An SSO sign-in can end sooner, when your identity provider or the connection's **Longest session** setting sets a shorter limit.
 
 ## Learners who cannot sign in
 
diff --git a/frontlit/docs/self-hosting/configuration.md b/frontlit/docs/self-hosting/configuration.md
index 508dbaa0f..b6edfd315 100644
--- a/frontlit/docs/self-hosting/configuration.md
+++ b/frontlit/docs/self-hosting/configuration.md
@@ -24,7 +24,7 @@ The worker is the API image started with `bun apps/api/src/worker.ts`. Give it t
 | `PORT` | Optional | `4000` | The port the API listens on |
 | `NODE_ENV` | Optional | `production` in the image | Set to `production` for deployments. In other modes, system mail is printed to the log instead of sent. |
 | `INTEGRATIONS_ENCRYPTION_KEY` | Recommended | `AUTH_SECRET` | Key that encrypts credentials that schools save, such as payment provider keys. Use a dedicated random value. |
-| `BILLING_MODE` | Recommended | `cloud` | Use `oss` for a self-hosted deployment. `cloud` is for CourseLit's hosted service and requires its billing provider settings. |
+| `BILLING_MODE` | Recommended | `cloud` | Use `oss` for a self-hosted deployment. It makes every plan feature available to every school, including [single sign-on](/docs/self-hosting/single-sign-on). `cloud` is for CourseLit's hosted service and requires its billing provider settings. |
 | `SEED` | Do not set | unset | Seeds sample data for development. Leave it unset. |
 
 ### Domains
diff --git a/frontlit/docs/self-hosting/index.md b/frontlit/docs/self-hosting/index.md
index 306afcc8c..22d85cfdc 100644
--- a/frontlit/docs/self-hosting/index.md
+++ b/frontlit/docs/self-hosting/index.md
@@ -63,6 +63,12 @@ How hostnames reach the right service, and how custom domains work.
 
 </Card>
 
+<Card title="Single sign-on (SSO)" href="/docs/self-hosting/single-sign-on" icon="KeyRound">
+
+Let learners sign in with a school's identity provider over SAML.
+
+</Card>
+
 </Cards>
 
 If you only need to use CourseLit and not operate it, create a school on the hosted service instead, see [Getting started](/docs/getting-started).
diff --git a/frontlit/docs/self-hosting/single-sign-on.md b/frontlit/docs/self-hosting/single-sign-on.md
new file mode 100644
index 000000000..5ccb5f9dd
--- /dev/null
+++ b/frontlit/docs/self-hosting/single-sign-on.md
@@ -0,0 +1,186 @@
+---
+title: Single sign-on (SSO)
+description: Prepare a self-hosted deployment for SAML single sign-on, then connect a school to an identity provider such as Okta, Entra ID, Google Workspace or Keycloak so its learners sign in with their work accounts.
+nav_order: 50
+---
+
+Single sign-on (SSO) lets the learners of a school sign in to the school's website with an account from the school's own identity provider (IdP), such as Okta, Microsoft Entra ID, Google Workspace or Keycloak. Each school sets up its own connection. CourseLit uses SAML 2.0.
+
+SSO is for learners only. Team members always sign in to the admin with an email code or Google, and an account that signs in with SSO never gets team access.
+
+This page covers what the deployment needs, then the setup a school owner does in the admin.
+
+## Prepare the deployment
+
+### Turn on the self-hosted plan mode
+
+Set `BILLING_MODE` to `oss` on the API and the worker. In this mode every school can use SSO. With `cloud`, SSO needs a paid plan that includes it.
+
+### Use a stable, public API address
+
+The addresses that a school gives its identity provider are built from `PUBLIC_API_URL`:
+
+| Address | Value |
+| --- | --- |
+| ACS URL | `PUBLIC_API_URL` followed by `/learner-login/sso/` and the connection ID, then `/acs` |
+| Entity ID and metadata URL | `PUBLIC_API_URL` followed by `/learner-login/sso/` and the connection ID, then `/metadata` |
+
+The learner's browser carries the sign-in from the identity provider to the ACS URL, so the API hostname must be reachable from the learners' browsers over `https`. See [Domains and reverse proxy](/docs/self-hosting/domains-and-proxy).
+
+<Callout type="warning" title="Changing PUBLIC_API_URL breaks existing connections">
+
+Every identity provider stores the old addresses. If you change `PUBLIC_API_URL`, each school has to update the ACS URL and entity ID in its identity provider before its learners can sign in again.
+
+</Callout>
+
+### Let the proxy pass sign-in responses
+
+Route `/learner-login/sso/` on the API hostname to the API like any other API path. The identity provider posts a signed form to the ACS URL. The API accepts form bodies of up to 256 KB there, so make sure your proxy allows a body of at least that size.
+
+### Run the worker
+
+The worker runs the SSO background tasks:
+
+- It cleans up expired sign-in requests.
+- It checks each verified domain's DNS record about once a week.
+- It applies plan changes to connections.
+
+Without it, domain checks never run.
+
+### Keep the clocks right
+
+Sign-in responses are valid only for a short time. Run NTP or another time sync on the API hosts, and make sure the identity provider's clock is right too. A wrong clock makes every sign-in fail with `expired` or `not_yet_valid`.
+
+### Allow DNS lookups
+
+To verify that a school owns an email domain, the API looks up a DNS TXT record. The API host needs to be able to resolve public DNS names.
+
+## Set up a connection for a school
+
+The school's owner does this in the admin. It can't be done with an API key or an AI assistant. The admin asks the owner to sign in again before saving changes if their last sign-in wasn't recent.
+
+<Steps>
+
+<Step>
+
+### Create the connection
+
+In the admin, open **Settings**, then **Login providers**. Under **Single sign-on (SSO)**, select **Set up**.
+
+Enter a **Button label**, which learners see as "Sign in with" followed by the label. Paste the identity provider's metadata XML, or enter its entity ID, then select **Create**.
+
+The provider's entity ID can't be changed later. To move to a different provider, create a new connection.
+
+</Step>
+
+<Step>
+
+### Register CourseLit in the identity provider
+
+Section **1. Give these to your identity provider** shows the ACS URL, the entity ID and the metadata URL. Create a SAML app in the identity provider and enter them. The fields have different names in each product:
+
+| CourseLit | Okta | Microsoft Entra ID | Google Workspace | Keycloak |
+| --- | --- | --- | --- | --- |
+| ACS URL | Single sign-on URL | Reply URL | ACS URL | Assertion Consumer Service POST Binding URL, and a valid redirect URI |
+| Entity ID | Audience URI (SP Entity ID) | Identifier (Entity ID) | Entity ID | Client ID |
+
+If you didn't paste the metadata in the first step, fill in **2. Your identity provider's settings**: the provider's sign-in URL (it must start with `https://`) and its signing certificate.
+
+To rotate a certificate, add the new one next to the old one. Saving puts the connection back to draft, like any change to these settings (see [Change or turn off a connection](#change-or-turn-off-a-connection)). Run a test sign-in and turn it on again. Remove the old certificate after the provider has switched to the new one.
+
+</Step>
+
+<Step>
+
+### Configure what the identity provider sends
+
+CourseLit accepts a sign-in only when the identity provider:
+
+- **Signs the assertion.** A signature on the outer response alone is refused. In Keycloak, turn on **Sign assertions**.
+- **Signs with RSA-SHA256 or stronger.** SHA-1 signatures are refused.
+- **Sends a persistent NameID.** It identifies the person and must never change or be reused. If the provider can't send one, put the name of an attribute with such a value in **Subject attribute (optional)**. Don't use the email address for this.
+- **Sends the email address** in an attribute named `email`, `mail` or `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`.
+
+The name is optional. CourseLit reads `displayName` or `name`, or combines `givenName` (or `firstName`) with `surname` (or `sn`, `lastName`).
+
+Sign-in always starts from the school's website. Sign-ins started from the identity provider's own app dashboard are refused.
+
+</Step>
+
+<Step>
+
+### Verify the email domains
+
+Only learners whose email address is on a verified domain can sign in with SSO. Under **3. Domains**, add each domain, such as `example.com`. Add the TXT record that the admin shows, then select **Verify**.
+
+| Type | Name | Value |
+| --- | --- | --- |
+| TXT | `_courselit-verification.` followed by the domain | The token shown in the admin |
+
+This record name is fixed. `CUSTOM_DOMAIN_TXT_RECORD_NAME` applies only to custom website domains.
+
+DNS changes can take a while to show up. Keep the record in place: the worker checks it about once a week. After three failed checks in a row the domain is no longer verified, and the owner gets an email. Until the domain is verified again, new learners from it can't sign in with SSO, and SSO isn't required for it.
+
+</Step>
+
+<Step>
+
+### Run a test sign-in
+
+Under **4. Test the connection**, select **Test connection**, and sign in at the identity provider with an account on a verified domain. A test signs nobody in to the school. The admin then shows what the provider sent: the provider, the subject, the email, the name and whether the email is on a verified domain.
+
+If the test fails, the admin shows a reason code and what to change. See [Fix sign-in failures](#fix-sign-in-failures).
+
+</Step>
+
+<Step>
+
+### Choose who has to use SSO
+
+Under **5. Who has to use SSO**:
+
+- **Require SSO for these domains**: learners with an email address on a verified domain can then only sign in with SSO. Learners from those domains who are signed in another way are signed out. Learners with other email addresses keep using email codes or Google.
+- **Longest session (minutes)**: how long an SSO sign-in lasts before the learner has to sign in again. Leave it empty to use the school default. A shorter session limit from the identity provider also applies.
+
+</Step>
+
+<Step>
+
+### Turn it on
+
+Under **6. Turn it on**, select **Turn on**. The admin lists anything still missing, such as a verified domain or a test with the current settings. Learners then see the SSO button on the school's sign-in page, next to the other sign-in methods that are turned on under **Login providers**.
+
+</Step>
+
+</Steps>
+
+## How learners sign in with SSO
+
+On the school's sign-in page, a learner selects **Sign in with** followed by the button label. After they sign in at the identity provider, they return to the page they came from.
+
+The first time a learner signs in, CourseLit links their identity provider account to the school's learner record for that email address, or creates one. Later sign-ins use that link, even if the email address changes at the identity provider.
+
+When SSO is required for a learner's domain and the learner asks for an email code, the sign-in page tells them to use the SSO button instead.
+
+## Change or turn off a connection
+
+- **Changing the sign-in URL, the certificates or the subject attribute** puts the connection back to draft and signs out every learner who signed in with SSO. Test it again, then turn it on.
+- **Turning a connection off** signs out every learner who signed in with SSO, at once. It can be turned on again without a new test as long as its settings haven't changed.
+- **Deleting a connection** removes its domains and the links between learners and their identity provider accounts. The learners themselves stay in the school, and can sign in with the other methods.
+
+## Fix sign-in failures
+
+Learners see one general message when SSO fails. The reason code appears in the result of a test sign-in in the admin.
+
+| Reason | What to check |
+| --- | --- |
+| `status_not_success` | The identity provider refused the sign-in. Usually the person isn't assigned to the app in the identity provider. |
+| `signature_invalid` | The identity provider must sign the assertion, not only the response, with one of the certificates saved in the connection. After a certificate rotation, add the new certificate. |
+| `weak_algorithm` | Set the identity provider's signature algorithm to RSA-SHA256. |
+| `wrong_audience` | The identity provider's entity ID or audience must be the connection's entity ID. |
+| `wrong_recipient`, `wrong_destination` | The identity provider's ACS URL must be the connection's ACS URL. Check `PUBLIC_API_URL`. |
+| `wrong_issuer` | The response came from a different identity provider than the one the connection was created for. |
+| `missing_subject` | The identity provider sent no NameID, or the subject attribute is missing. |
+| `unstable_subject` | The NameID isn't in the persistent format. Set the NameID format to persistent, or set a subject attribute. |
+| `expired`, `not_yet_valid` | The clock of the API host or the identity provider is wrong. |
+| `request_not_found`, `request_already_used`, `replayed_assertion` | The sign-in was started too long ago, or was already completed. Start again from the school's website. |
diff --git a/package.json b/package.json
index b370de5c2..faa4e778a 100644
--- a/package.json
+++ b/package.json
@@ -15,10 +15,12 @@
     "esbuild"
   ],
   "overrides": {
+    "@xmldom/xmldom": "0.8.15",
     "esbuild": "0.28.2",
     "postcss": "8.5.28",
     "qs": "6.16.1",
-    "ts-deepmerge": "8.0.0"
+    "ts-deepmerge": "8.0.0",
+    "xml-crypto": "6.4.0"
   },
   "patchedDependencies": {
     "@anatine/zod-openapi@1.14.2": "patches/@anatine__zod-openapi@1.14.2.patch"
diff --git a/packages/api-contract/src/index.ts b/packages/api-contract/src/index.ts
index a3be6f5e8..60ddc4a48 100644
--- a/packages/api-contract/src/index.ts
+++ b/packages/api-contract/src/index.ts
@@ -920,6 +920,103 @@ export const updateMediaBodySchema = z.object({
   caption: z.string().max(2_000).optional(),
   accessPolicy: z.enum(["public", "private"]).optional(),
 });
+const ssoConnectionPathParams = z.object({ connectionId: z.string().min(1).max(64) });
+
+export const ssoConnectionStatusSchema = z.enum(["draft", "active", "suspended", "disabled"]);
+export const ssoEnforcementSchema = z.enum(["optional", "required_for_domains"]);
+export const ssoDomainSchema = z.object({
+  domain: z.string(),
+  verified: z.boolean(),
+  verifiedAt: z.string().nullable(),
+  /** The TXT record to publish; the value is the bare token. */
+  verificationRecord: z.object({
+    type: z.literal("TXT"),
+    name: z.string(),
+    value: z.string(),
+  }),
+  /** Weekly re-checks in a row that found no record. Three clear the verification. */
+  consecutiveCheckFailures: z.number().int(),
+  lastCheckedAt: z.string().nullable(),
+});
+/** An SSO connection. Never includes OIDC secrets or test-sign-in attributes. */
+export const ssoConnectionSchema = z.object({
+  id: z.string(),
+  protocol: z.enum(["saml", "oidc"]),
+  status: ssoConnectionStatusSchema,
+  displayName: z.string(),
+  enforcement: ssoEnforcementSchema,
+  maxSessionMinutes: z.number().int().nullable(),
+  idpEntityId: z.string().nullable(),
+  idpSsoUrl: z.string().nullable(),
+  idpCertificates: z.array(z.string()),
+  subjectAttribute: z.string().nullable(),
+  /** Values to enter at the identity provider. */
+  serviceProvider: z.object({
+    entityId: z.string(),
+    acsUrl: z.string(),
+    metadataUrl: z.string(),
+  }),
+  domains: z.array(ssoDomainSchema),
+  testedAt: z.string().nullable(),
+  /** True when the last successful test ran against the current settings. */
+  testedCurrentConfiguration: z.boolean(),
+  /** Whether the school's plan lets it activate the connection. */
+  planAvailable: z.boolean(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+const ssoSettingsFields = {
+  displayName: z.string().trim().min(1).max(100),
+  /** IdP metadata XML, pasted; fills the entity ID, SSO URL and certificates. */
+  metadataXml: z.string().max(524_288),
+  idpEntityId: z.string().trim().min(1).max(2048),
+  idpSsoUrl: z.string().trim().min(1).max(2048),
+  idpCertificates: z.array(z.string().min(1).max(16_384)).max(5),
+  subjectAttribute: z.string().trim().min(1).max(512).nullable(),
+  enforcement: ssoEnforcementSchema,
+  maxSessionMinutes: z.number().int().min(5).max(525_600).nullable(),
+};
+export const createSsoConnectionBodySchema = z
+  .object({
+    ...ssoSettingsFields,
+    protocol: z.literal("saml").optional(),
+  })
+  .partial()
+  .required({ displayName: true })
+  .strict();
+export const updateSsoConnectionBodySchema = z.object(ssoSettingsFields).partial().strict();
+export const addSsoDomainBodySchema = z.object({ domain: z.string().trim().min(3).max(253) }).strict();
+export const startSsoConnectionTestBodySchema = z
+  .object({ returnUrl: z.string().url().max(1000) })
+  .strict();
+export const ssoConnectionTestResultSchema = z.object({
+  ok: z.boolean(),
+  /** A reason code when the test sign-in failed. */
+  reason: z.string().nullable(),
+  issuer: z.string().nullable(),
+  subject: z.string().nullable(),
+  email: z.string().nullable(),
+  name: z.string().nullable(),
+  emailDomainVerified: z.boolean().nullable(),
+  attributes: z.record(z.array(z.string())),
+  expiresAt: z.string(),
+});
+export const schoolLoginMethodSchema = z.enum(["email", "google"]);
+export const schoolLoginMethodsSchema = z.object({
+  /** The methods the school turned on. SSO is on exactly when it has an active connection. */
+  loginMethods: z.array(schoolLoginMethodSchema),
+  googleAvailable: z.boolean(),
+  sso: z.object({
+    active: z.boolean(),
+    displayName: z.string().nullable(),
+    planAvailable: z.boolean(),
+  }),
+  /** What learners can use right now. */
+  usable: z.array(z.enum(["email", "google", "sso"])),
+});
+export const updateSchoolLoginMethodsBodySchema = z
+  .object({ loginMethods: z.array(schoolLoginMethodSchema).max(2) })
+  .strict();
 export const mediaReferenceSchema = z.object({
   resourceType: mediaResourceTypeSchema,
   resourceId: z.string().trim().min(1).max(255),
@@ -1898,6 +1995,7 @@ export const learnerStartGoogleBodySchema = z.object({
   nonce: z.string().min(32).max(200),
   next: z.string().max(1000).optional(),
 });
+export const learnerStartSsoBodySchema = learnerStartGoogleBodySchema;
 export const consumeSchoolAuthTicketBodySchema = z.object({
   ticket: z.string().min(1).max(200),
 });
@@ -3654,8 +3752,10 @@ export const contract = c.router({
     responses: {
       200: z.object({
         schoolId: z.string(),
-        loginMethods: z.array(z.enum(["email", "google"])),
+        loginMethods: z.array(z.enum(["email", "google", "sso"])),
         hasGoogle: z.boolean(),
+        hasSso: z.boolean(),
+        ssoDisplayName: z.string().nullable(),
       }),
       404: platformErrorSchema,
     },
@@ -4150,6 +4250,19 @@ export const contract = c.router({
       404: platformErrorSchema,
     },
   },
+  learnerStartSsoSignIn: {
+    method: "POST",
+    path: "/v1/learner/auth/sso",
+    summary: "Start single sign-on for a school website",
+    body: learnerStartSsoBodySchema,
+    responses: {
+      200: z.object({ url: z.string().url() }),
+      400: platformErrorSchema,
+      403: platformErrorSchema,
+      404: platformErrorSchema,
+      429: platformErrorSchema,
+    },
+  },
   consumeSchoolAuthTicket: {
     method: "POST",
     path: "/v1/auth/tickets/consume",
@@ -4886,6 +4999,197 @@ export const contract = c.router({
       409: platformErrorSchema,
     },
   },
+  listSsoConnections: {
+    method: "GET",
+    path: "/v1/sso/connections",
+    summary: "List the school's single sign-on connections",
+    responses: {
+      200: z.object({ items: z.array(ssoConnectionSchema) }),
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+    },
+  },
+  createSsoConnection: {
+    method: "POST",
+    path: "/v1/sso/connections",
+    summary: "Create a draft single sign-on connection",
+    body: createSsoConnectionBodySchema,
+    responses: {
+      201: ssoConnectionSchema,
+      400: platformErrorSchema,
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+      409: platformErrorSchema,
+    },
+  },
+  getSsoConnection: {
+    method: "GET",
+    path: "/v1/sso/connections/:connectionId",
+    pathParams: ssoConnectionPathParams,
+    summary: "Read a single sign-on connection",
+    responses: {
+      200: ssoConnectionSchema,
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+      404: platformErrorSchema,
+    },
+  },
+  updateSsoConnection: {
+    method: "PATCH",
+    path: "/v1/sso/connections/:connectionId",
+    pathParams: ssoConnectionPathParams,
+    summary: "Change a single sign-on connection",
+    body: updateSsoConnectionBodySchema,
+    responses: {
+      200: ssoConnectionSchema,
+      400: platformErrorSchema,
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+      404: platformErrorSchema,
+    },
+  },
+  deleteSsoConnection: {
+    method: "DELETE",
+    path: "/v1/sso/connections/:connectionId",
+    pathParams: ssoConnectionPathParams,
+    summary: "Delete a single sign-on connection",
+    responses: {
+      204: z.undefined(),
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+      404: platformErrorSchema,
+    },
+  },
+  addSsoDomain: {
+    method: "POST",
+    path: "/v1/sso/connections/:connectionId/domains",
+    pathParams: ssoConnectionPathParams,
+    summary: "Add an email domain to a single sign-on connection",
+    body: addSsoDomainBodySchema,
+    responses: {
+      201: ssoDomainSchema,
+      400: platformErrorSchema,
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+      404: platformErrorSchema,
+      409: platformErrorSchema,
+    },
+  },
+  verifySsoDomain: {
+    method: "POST",
+    path: "/v1/sso/connections/:connectionId/domains/:domain/verify",
+    pathParams: ssoConnectionPathParams.extend({ domain: z.string().min(1) }),
+    summary: "Check the DNS record that proves the school owns an email domain",
+    body: z.object({}).strict(),
+    responses: {
+      200: ssoDomainSchema,
+      400: platformErrorSchema,
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+      404: platformErrorSchema,
+      429: platformErrorSchema,
+    },
+  },
+  deleteSsoDomain: {
+    method: "DELETE",
+    path: "/v1/sso/connections/:connectionId/domains/:domain",
+    pathParams: ssoConnectionPathParams.extend({ domain: z.string().min(1) }),
+    summary: "Remove an email domain from a single sign-on connection",
+    responses: {
+      204: z.undefined(),
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+      404: platformErrorSchema,
+    },
+  },
+  startSsoConnectionTest: {
+    method: "POST",
+    path: "/v1/sso/connections/:connectionId/test",
+    pathParams: ssoConnectionPathParams,
+    summary: "Start a test sign-in; returns the URL to open",
+    body: startSsoConnectionTestBodySchema,
+    responses: {
+      200: z.object({ url: z.string().url() }),
+      400: platformErrorSchema,
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+      404: platformErrorSchema,
+    },
+  },
+  getSsoConnectionTestResult: {
+    method: "GET",
+    path: "/v1/sso/connections/:connectionId/test-results/:requestId",
+    pathParams: ssoConnectionPathParams.extend({ requestId: z.string().min(1) }),
+    summary: "Read the result of a test sign-in this admin started",
+    responses: {
+      200: ssoConnectionTestResultSchema,
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+      404: platformErrorSchema,
+    },
+  },
+  activateSsoConnection: {
+    method: "POST",
+    path: "/v1/sso/connections/:connectionId/activate",
+    pathParams: ssoConnectionPathParams,
+    summary: "Turn a tested single sign-on connection on",
+    body: z.object({}).strict(),
+    responses: {
+      200: ssoConnectionSchema,
+      400: platformErrorSchema,
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+      404: platformErrorSchema,
+      409: platformErrorSchema,
+    },
+  },
+  disableSsoConnection: {
+    method: "POST",
+    path: "/v1/sso/connections/:connectionId/disable",
+    pathParams: ssoConnectionPathParams,
+    summary: "Turn a single sign-on connection off and end its sessions",
+    body: z.object({}).strict(),
+    responses: {
+      200: ssoConnectionSchema,
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+      404: platformErrorSchema,
+    },
+  },
+  unlinkSsoIdentity: {
+    method: "DELETE",
+    path: "/v1/sso/identities/:schoolAccountId",
+    pathParams: z.object({ schoolAccountId: z.string().min(1) }),
+    summary: "Remove a learner's single sign-on link and end their SSO sessions",
+    responses: {
+      204: z.undefined(),
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+      404: platformErrorSchema,
+    },
+  },
+  getSchoolLoginMethods: {
+    method: "GET",
+    path: "/v1/school/login-methods",
+    summary: "Read which sign-in methods the school's learners can use",
+    responses: {
+      200: schoolLoginMethodsSchema,
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+    },
+  },
+  updateSchoolLoginMethods: {
+    method: "PATCH",
+    path: "/v1/school/login-methods",
+    summary: "Turn learner sign-in methods on or off",
+    body: updateSchoolLoginMethodsBodySchema,
+    responses: {
+      200: schoolLoginMethodsSchema,
+      400: platformErrorSchema,
+      401: platformErrorSchema,
+      403: platformErrorSchema,
+    },
+  },
   createSchool: {
     method: "POST",
     path: "/v1/schools",
diff --git a/packages/api-contract/src/mcp-parity.ts b/packages/api-contract/src/mcp-parity.ts
index ea375c5a0..a1ee05cd9 100644
--- a/packages/api-contract/src/mcp-parity.ts
+++ b/packages/api-contract/src/mcp-parity.ts
@@ -732,6 +732,137 @@ const mcpParityOverrides = [
       reviewBy: "2027-09-01",
     },
   },
+  {
+    capability: "school.sso.create",
+    rest: { operationId: "createSsoConnection" },
+    parity: "exempt",
+    exemption: {
+      reason:
+        "changes who can sign in as every SSO learner; owner session with recent sign-in only",
+      owner: "courselit",
+      reviewBy: "2027-09-01",
+    },
+  },
+  {
+    capability: "school.sso.update",
+    rest: { operationId: "updateSsoConnection" },
+    parity: "exempt",
+    exemption: {
+      reason:
+        "changes who can sign in as every SSO learner; owner session with recent sign-in only",
+      owner: "courselit",
+      reviewBy: "2027-09-01",
+    },
+  },
+  {
+    capability: "school.sso.delete",
+    rest: { operationId: "deleteSsoConnection" },
+    parity: "exempt",
+    exemption: {
+      reason:
+        "changes who can sign in as every SSO learner; owner session with recent sign-in only",
+      owner: "courselit",
+      reviewBy: "2027-09-01",
+    },
+  },
+  {
+    capability: "school.sso.domain.add",
+    rest: { operationId: "addSsoDomain" },
+    parity: "exempt",
+    exemption: {
+      reason:
+        "changes who can sign in as every SSO learner; owner session with recent sign-in only",
+      owner: "courselit",
+      reviewBy: "2027-09-01",
+    },
+  },
+  {
+    capability: "school.sso.domain.verify",
+    rest: { operationId: "verifySsoDomain" },
+    parity: "exempt",
+    exemption: {
+      reason:
+        "changes who can sign in as every SSO learner; owner session with recent sign-in only",
+      owner: "courselit",
+      reviewBy: "2027-09-01",
+    },
+  },
+  {
+    capability: "school.sso.domain.delete",
+    rest: { operationId: "deleteSsoDomain" },
+    parity: "exempt",
+    exemption: {
+      reason:
+        "changes who can sign in as every SSO learner; owner session with recent sign-in only",
+      owner: "courselit",
+      reviewBy: "2027-09-01",
+    },
+  },
+  {
+    capability: "school.sso.test.start",
+    rest: { operationId: "startSsoConnectionTest" },
+    parity: "exempt",
+    exemption: {
+      reason:
+        "changes who can sign in as every SSO learner; owner session with recent sign-in only",
+      owner: "courselit",
+      reviewBy: "2027-09-01",
+    },
+  },
+  {
+    capability: "school.sso.test.result",
+    rest: { operationId: "getSsoConnectionTestResult" },
+    parity: "exempt",
+    exemption: {
+      reason:
+        "changes who can sign in as every SSO learner; owner session with recent sign-in only",
+      owner: "courselit",
+      reviewBy: "2027-09-01",
+    },
+  },
+  {
+    capability: "school.sso.activate",
+    rest: { operationId: "activateSsoConnection" },
+    parity: "exempt",
+    exemption: {
+      reason:
+        "changes who can sign in as every SSO learner; owner session with recent sign-in only",
+      owner: "courselit",
+      reviewBy: "2027-09-01",
+    },
+  },
+  {
+    capability: "school.sso.disable",
+    rest: { operationId: "disableSsoConnection" },
+    parity: "exempt",
+    exemption: {
+      reason:
+        "changes who can sign in as every SSO learner; owner session with recent sign-in only",
+      owner: "courselit",
+      reviewBy: "2027-09-01",
+    },
+  },
+  {
+    capability: "school.sso.identity.unlink",
+    rest: { operationId: "unlinkSsoIdentity" },
+    parity: "exempt",
+    exemption: {
+      reason:
+        "changes who can sign in as every SSO learner; owner session with recent sign-in only",
+      owner: "courselit",
+      reviewBy: "2027-09-01",
+    },
+  },
+  {
+    capability: "learner.startSsoSignIn",
+    rest: { operationId: "learnerStartSsoSignIn" },
+    parity: "exempt",
+    exemption: {
+      reason: "Learner browser session operations are not MCP tools.",
+      owner: "courselit",
+      reviewBy: "2027-09-01",
+    },
+  },
   {
     capability: "learner.startGoogleSignIn",
     rest: { operationId: "learnerStartGoogleSignIn" },
@@ -938,6 +1069,7 @@ export const MCP_HIGH_IMPACT_OPERATIONS: ReadonlySet<string> = new Set([
   "deleteContactTag",
   "updateSchoolCodeInjection",
   "updateSchoolPaymentSettings",
+  "updateSchoolLoginMethods",
 ]);
 
 /** `listWebsitePages` -> `list_website_pages`: one snake_case tool per operation. */