SSO & SCIM troubleshooting #
A single reference for the errors you'll actually see. Provider-specific tables live in each setup guide (Okta · Entra ID · Google).
Login (OIDC) errors #
All login failures redirect back with an sso_error=<reason> query parameter.
sso_error= |
Meaning | Fix |
|---|---|---|
domain_mismatch |
The token's email claim is missing, or on a domain other than the one you registered. |
Ensure the IdP emits an email claim on your registered domain. Entra: add the email optional claim and confirm the user's mail attribute is populated. |
invalid_issuer |
The discovery document's issuer doesn't match. | Entra: use the tenant-specific v2.0 discovery URL (not /common, not v1.0). |
invalid_audience |
Token audience ≠ your client_id. | Check the IdP app's audience/client-id settings. |
invalid_signature |
JWKS clock-skew or key rotation. | ECW caches JWKS ~15 min. Wait, or click Test Connection to refresh. |
replay_detected |
A token was replayed (e.g. browser Back after a successful login). | Open a new tab and sign in again. |
missing_params |
Callback missing/oversized state/code. |
Retry from a clean login start; don't bookmark mid-flow callback URLs. |
Things ECW requires of the token:
- Signed RS256 (RS384/PS256/ES*/EdDSA are rejected — "Unsupported JWT algorithm").
- A non-empty
suband anemailon the registered domain. - If
email_verifiedis present it must betrue; if the IdP omits it (e.g. Entra), that's fine.
"SSO login isn't offered / falls back to password" #
- Domain not verified. SSO login only activates after the DNS-TXT domain check passes. Check SSO Settings shows the domain Verified; if a DNS change removed the record, re-verify.
- Email domain mismatch. The email you typed isn't on the configured domain — that's expected; only registered-domain emails get the SSO path.
Provisioning (SCIM) errors #
| Symptom | Meaning | Fix |
|---|---|---|
| Test connection "Invalid user ID" | Okta base URL has a /Users suffix. |
Use the base URL for Okta; it appends /Users itself. |
| Entra/Google connection fails | Wrong endpoint form. | Use the Users Endpoint URL (…/scim/v2/Users). |
401 on every request |
Token revoked (regenerated / SCIM disabled) or malformed. Tokens do not expire on their own. | Regenerate SCIM Token and re-paste; mind the 48h grace on the old one. |
413 |
Body > 10 MB or bulk > 1000 ops. | Split into smaller batches. |
422 "email cannot be changed" |
Editing a SCIM-managed member's email in ECW. | Change it at the IdP. |
403 "does not match sync filter" |
User excluded by your sync filter. | Expected — adjust the filter if the user should sync. |
| Attribute not applied | Mapping gap or bad value. | Attribute Mappings → discovered attributes shows what the IdP sent; check mapping errors. |
Token & secret expiry #
- IdP client secret (Okta/Entra/Google): managed by the IdP, and it does expire. When it lapses, logins stop with a token/exchange error. Create a new secret in the IdP and paste it into ECW. (This is the one credential you must renew on a schedule.)
- ECW SCIM token: does not expire — sync won't break on its own. The dashboard shows the token's last-used time so you can spot a stale one, and sends a single optional reminder once it's ~12 months old. Rotate any time with Regenerate SCIM Token; the old token keeps working for a 48-hour grace window so you can update the IdP without downtime.
Enforce-SSO lockout #
Enabling Require SSO disables password login for your domain. It always requires a fresh admin OTP and warns you first. If SSO later becomes unavailable, the account owner retains a recovery path to restore password access — you won't be permanently locked out.
Still stuck? #
Check the SSO Settings → activity view for a record of recent SSO/SCIM requests (headers and bodies are captured with secrets redacted), which shows exactly what your IdP sent to ECW.