# SSO and SCIM

## Packaging

**SSO and SCIM are both on every paid tier.** The "SSO tax" — gating single sign-on, or
the directory sync that makes it operable, behind an Enterprise quote — is a documented
churn trigger that comes up in procurement, and there is deliberately no separate
"enterprise SSO" or "enterprise SCIM" flag anywhere in the codebase.

| Feature | Free | Pro | Team | Enterprise |
| --- | --- | --- | --- | --- |
| SSO (SAML + OIDC) | — | ✅ | ✅ | ✅ |
| SCIM directory sync | — | ✅ | ✅ | ✅ |

> **This matches the code, not just the marketing.** `billing/plans.ts` sets both
> `sso: true` and `scim: true` on every paid tier (`PRO`, `TEAM`, `ENTERPRISE`) and both
> false on `FREE` — design §3.1 ("on all paid tiers (Pro and up), never
> enterprise-gated") is the binding commitment there, and the file notes that the §13
> plan sketch listing SCIM under Enterprise-only is superseded by it.

## SSO

One code path serves SAML and OIDC. Both reduce to `(subject, email, name, groups)`,
and everything after that — find-or-create the user, find-or-create the org membership
at the mapped role, mint a session — is protocol-agnostic.

### Attribute mapping

Well-known claim names are used by default: the SAML URNs Entra ID, Okta and Google
Workspace emit, plus the short names OIDC and simpler IdPs emit. A connection can
override any of them.

**An OIDC `email` the provider marks unverified is refused.** When the address a login
resolves to is the id_token's `email` claim and `email_verified` is present and not
`true` (the string `"true"` counts as true), the callback fails with the generic 401 and
`email_unverified` on the `LOGIN_FAILURE` event. Otherwise anyone who can hold a member's
address at the IdP — self sign-up, a user-editable email, a guest account — would be
signed in as that member. A connection whose email mapping names an admin-controlled
claim such as `upn` is unaffected, because `email_verified` qualifies only `email`.

### Two provisioning rules that matter

**A JIT-provisioned user gets no password.** `passwordHash` stays null, so a federated
account cannot be taken over through a password-reset flow against an address the IdP
controls.

**An existing member's role follows the IdP only where the connection gives the IdP
roles to decide.** A connection with at least one usable `roleMapping` entry (a
non-`OWNER` role) is authoritative in **both** directions: the resolved role is applied
at every sign-in, promoting or demoting. That role is the highest one any asserted group
maps to (case-insensitive), or `defaultRole` when no asserted group is mapped. Without
this, in the usual one-admin-group setup (`{ "platform-admins": "ADMIN" }`), someone
removed from the admin group asserts no mapped group and would stay ADMIN indefinitely.
A connection with no usable mapping has only `defaultRole`, which is an assumption about
nobody in particular, so there roles only ever move *up*. The cost of the first rule: a
mapping whose group names are mistyped demotes, at their next sign-in, every admin it
fails to match. Every role move is recorded on the `sso.login` audit row with
`previousRole`, and an `OWNER` is never changed by the IdP, which cannot assign
ownership and so cannot take it away. That leaves the org with someone who can fix the
mapping.

### Enforcing SSO

An org can require SSO. It is enforced **per organization, at access**: every
authorization check against an enforcing org refuses a non-owner member whose session
cannot have come from its identity provider with "This organization requires single
sign-on…" (`ssoBlocked` in `resolveAccessContext`), and nothing else is affected.
Password sign-in itself still succeeds, and that session keeps working in every other
org the person belongs to. An earlier version refused the
password at `/auth/login` whenever *any* of the account's orgs enforced SSO; since the
SSO path refuses accounts that have a password, that locked such a member out of every
organization, including ones they own.

A member reaches an enforcing org only when all three hold:

- **the account has no password.** A password account can never hold a federated
  session — the SSO path refuses it, and the reset that gives a federated account a
  password revokes its sessions — so every credential it holds came from the password.
  A password account is blocked from the enforcing org even if it once signed in through
  the IdP. Nothing in the product converts it to a password-less account yet; the SSO
  refusal it gets points the org's owner at Bucker support, for whom converting it is an
  operator step.
- **the account has no GitHub or Google sign-in connected** (SG-125). A social link can
  mint the account a session exactly as a password can, so it disqualifies the same way:
  a GitHub session reaches every org that does not require SSO and is refused by one that
  does, and the SSO path refuses to federate an account holding one. See
  [sign-in-and-mfa.md](sign-in-and-mfa.md).
- **the account has signed in through this org's IdP at least once** (an `SsoIdentity`
  row for the org).

Turning enforcement on also revokes the live sessions of every non-owner member and
their personal access tokens pinned to that org, so nothing issued before the switch
survives it. Agents and service accounts are never blocked; an agent acting for a
blocked member is blocked as that member is.

**Owners are exempt, deliberately.** An org whose IdP configuration breaks — expired
certificate, rotated key, deleted app registration — must retain a way back in.
Exempting owners is the standard break-glass; exempting nobody means one bad
certificate rotation locks a customer out of their own account permanently.

## SCIM 2.0

RFC 7644, at `/scim/v2`:

```
GET  /scim/v2/ServiceProviderConfig
GET  /scim/v2/ResourceTypes
     /scim/v2/Users    GET POST · /:id GET PUT PATCH DELETE
     /scim/v2/Groups   GET POST · /:id GET PUT PATCH DELETE
     /scim/v2/Agents   GET POST · /:id GET PUT PATCH DELETE
```

`/scim/v2/Agents` is the interesting one: **non-human identities are provisioned through
the same directory as humans.** Agents are principals on the same spine (see
[agent-governance.md](agent-governance.md)), so an org that offboards a person through
its IdP can offboard an agent the same way.

### Tenancy and errors

The `/scim/v2` tree lives in an encapsulated scope so it can do two things it must do:

- **authenticate with a SCIM bearer token instead of a JWT.** The token *is* the org
  binding — `/scim/v2/Users` has no org in its path, because IdP connectors will not put
  one there — so the credential carries the tenant.
- **render errors in SCIM's own envelope** without changing the API-wide error shape.
  IdP connectors parse the SCIM error body and will not follow a bespoke one.

Only the sha256 hash of a SCIM token is stored; a leaked database yields nothing
replayable, and the raw value is shown exactly once, like every other opaque token here.

Token administration is a normal JWT-authenticated admin surface:

```
GET/POST/DELETE /orgs/:orgSlug/scim/tokens[/:tokenId]
```

## Custom roles, network allowlist and security alerts

These are org settings under **Settings → Security**. Every write needs `org:admin`, which
only owners hold, and each one writes an audit row.

### Custom roles

A custom role refines one built-in role: Member, Billing or Viewer. It can remove scopes
from that role. It can also add scopes from a short fixed list: `org:read`,
`project:read`, `event:read`, `issue:read`, `issue:triage`, `issue:resolve`,
`alerts:write`, `release:write` and `billing:read`. It can never grant `org:admin`,
`fix:approve`, `billing:write` or any other scope the base role lacks. It never applies
to owners or admins. An added scope applies only to projects the member can already
reach through their teams.

```
GET/POST           /orgs/:orgSlug/custom-roles
PATCH/DELETE       /orgs/:orgSlug/custom-roles/:roleId
PUT                /orgs/:orgSlug/members/:memberId/custom-role   { "customRoleId": "…" | null }
```

Creating, editing and assigning need the Team or Enterprise plan. Removing never does,
and a downgrade does not remove an assigned role: losing the plan never widens anybody.
A role that members still hold cannot be deleted. Changing a member's built-in role
removes their custom role.

### Network allowlist

`ipAllowlist` on `PATCH /orgs/:orgSlug/security-policy` takes CIDR blocks or bare
addresses, IPv4 or IPv6, up to 100. An empty list means no restriction. When the list is
set, every dashboard, API, personal-access-token, org-token and agent request to this
organization must come from inside it. Owners are included. Event ingestion through a
DSN is never checked, and neither is SCIM.

- The address checked is the one the API resolves under `TRUST_PROXY`. The API never
  reads `X-Forwarded-For` itself.
- The API refuses to save a list that does not include the address you are saving from.
  The policy response shows owners that address as `requestIp`.
- The MCP server cannot resolve a caller's address yet, so an organization with an
  allowlist refuses MCP traffic.
- If every owner is locked out, a deployment operator can clear the list. That is the
  disruptive console action `org.ip_allowlist.clear`, and it writes an
  `org.ip_allowlist.cleared` row in your audit log.

### Security alerts

`auditAlertActions` on the same route chooses which audit actions notify the
organization's owners. See [Personal notifications](personal-notifications.md).

## Not built

- No SCIM `/Me` endpoint.
- No IdP-initiated deprovisioning webhooks beyond the SCIM DELETE path.
- No per-connection audit export; SSO and SCIM events land in the normal audit log.
