Single sign-on and SCIM

Single sign-on (OpenID Connect) and SCIM provisioning are included from the Compliance plan. Both are managed in Settings, SSO and SCIM by someone with the team management permission. SAML is available on request.

How sign-in is kept safe

Sessions belong to an email address and work across every workspace that address belongs to. So a workspace may only sign in people whose email domain it has proven to own. Without that proof, an identity provider the workspace controls could claim any address. That is why the first step is always a DNS record.

Set it up

1. Verify your email domains. Add each domain and publish the TXT record shown, for example _werkmail-sso.corp.example.com with a value that starts with werkmail-sso-verify=. Use Check record once DNS has propagated. A domain can be verified by one workspace only.
2. Register the redirect URI shown on the page at your identity provider and create an OpenID Connect web application. Use the authorization code flow. Scopes: openid email profile.
3. Enter issuer, client ID and client secret. The issuer must serve /.well-known/openid-configuration and match exactly. We read it when you save. The secret is stored encrypted and never shown again.
4. Pick the role for new people (not the owner role) and turn single sign-on on.

People then choose Sign in with single sign-on on the sign-in page, or open /api/auth/sso/start?email= with their address.

What happens at sign-in

• The browser is sent to your provider with PKCE and a one-time state that only we can read. Responses must carry the matching nonce and be signed by your provider's keys.
• The provider must return an email address, and it must not be marked unverified. The domain of that address must be one of your verified domains.
• First sign-in creates the account and adds the person with the role for new people. Existing members keep their role. The workspace owner is never changed.
• The session is handed to the dashboard in the URL fragment and removed from the address bar at once.

Your provider's own multi-factor policy applies. Signing in through your provider does not ask for the authenticator code of Second factor.

Require it

Require it for these domains turns off passwords and email codes for addresses on your verified domains. Test the sign-in first. The platform admin address is exempt so a broken provider cannot lock everyone out, and other domains are unaffected. Turning it off restores the other methods at once.

SCIM provisioning

Create a SCIM token under SCIM provisioning and give the base URL and the token to your provider as a bearer credential. The token is shown once.

Details that matter when you configure a provider:

• Deactivating (active: false) or deleting a user removes the membership; the account itself stays because it may belong to other workspaces.
• The workspace owner cannot be changed or removed through SCIM.
• Filtering supports userName eq "value". Display names are only updated for addresses on your verified domains.
• Tokens stop working when the workspace is no longer on a plan that includes SCIM.

curl https://app.example.com/scim/v2/Users \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{"userName": "dana@corp.example.com", "name": {"givenName": "Dana", "familyName": "Scott"}}'

Troubleshooting