Skip to content

SSO per organization (OIDC and SAML)

Edition: commercial (extractit-ee, FSL-1.1-ALv2). Without it /v1/org/sso answers 404 and the SSO page does not exist.

An organization logs in with its own identity provider at GET /auth/login?org=<slug>. Two kinds of IdP are supported, both through the same OIDC code flow with PKCE S256 of the web login (see Web identity):

  • OIDC directly against the customer's IdP (Entra ID, Okta, Google Workspace, Keycloak...);
  • SAML through a Keycloak broker: a Keycloak realm federates the customer's SAML IdP and exposes an OIDC client to ExtractIt. ExtractIt contains no SAML code (a test fails if python3-saml, pysaml2, signxml or xmlsec enter the lockfile or any import).

Configure

PUT /v1/org/sso (Owner, org:manage):

{
  "issuer": "https://login.example.com/realms/acme",
  "client_id": "extractit",
  "client_secret": "…",
  "scopes": ["openid", "email", "profile"],
  "groups_claim": "groups",
  "role_mappings": {"dx-reviewers": "reviewer", "dx-builders": "builder"},
  "default_role": null,
  "enforce_sso": false
}
  • On save the discovery document (<issuer>/.well-known/openid-configuration) is fetched: its issuer must match exactly and jwks_uri must use HTTPS (http only for localhost), or the request is 422. POST /v1/org/sso:test runs the same check without saving.
  • client_secret is write-only: it is sealed with the tenant data key (T11) and never returned (has_client_secret). Omit it to keep the stored one; "" removes it (public client).
  • The IdP's redirect URI is <DX_PUBLIC_URL>/auth/callback.

Roles

The role is never taken literally from the token:

  1. the groups of groups_claim (Keycloak full paths such as /dx-reviewers are accepted) are looked up in role_mappings; with several mapped groups the most privileged role wins (admin > builder > reviewer > auditor > viewer);
  2. otherwise default_role;
  3. otherwise the login is 403 no-role.

Mappings cannot grant Owner, and an Owner keeps the Owner role. There is no JIT provisioning: a person who logs in without a membership (an invitation, or SCIM) gets 403. A token signed for another organization's issuer fails the iss check: 401 invalid-token.

A member provisioned by SCIM logs in for the first time: the membership moves to the user the IdP authenticates, matched by its verified email or preferred_username.

SAML through Keycloak

ee/deploy/keycloak/ holds the template: realm-acme-broker.json (the broker realm: identity provider acme-saml, attribute importers for email and names, group mappers, OIDC client extractit with a groups claim) and compose.keycloak.yaml (profile keycloak). For tests a second realm, realm-acme-saml-idp.json, plays the customer's SAML IdP:

docker compose -f ee/deploy/keycloak/compose.keycloak.yaml -p dx-sso --profile keycloak up -d --wait

In production: change the hostnames, set validateSignature: true with the customer's signing certificate on the identity provider, require signed assertions and replace the client secret.

Pending

  • enforce_sso is stored and shown; refusing other issuers' logins for that organization's members is not enforced yet.