# 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](/two-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.

| Resource | What it does |
| --- | --- |
| `Users` | Create a member with the role for new people, change the display name, deactivate, delete. `userName` is the email address. |
| `Groups` | Workspace roles appear as groups. Adding a member to a group assigns that role; removing them returns them to the default role. Roles themselves are created in the dashboard. |

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.

```bash
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

| Message | Cause |
| --- | --- |
| Could not read the identity provider's configuration | The issuer is wrong, not public https, or does not serve its discovery document. |
| Verify at least one email domain first | Single sign-on can only be turned on with a verified domain. |
| The TXT record was not found yet | DNS has not propagated or the value differs. Publish it exactly as shown. |
| Not verified for single sign-on | The provider returned an address outside your verified domains. |