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.tssets bothsso: trueandscim: trueon every paid tier (PRO,TEAM,ENTERPRISE) and both false onFREE— 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.
- the account has signed in through this org's IdP at least once (an
SsoIdentityrow 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), 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/Usershas 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 readsX-Forwarded-Foritself. - 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 anorg.ip_allowlist.clearedrow in your audit log.
Security alerts
auditAlertActions on the same route chooses which audit actions notify the
organization's owners. See Personal notifications.
Not built
- No SCIM
/Meendpoint. - 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.