SSO with OIDC
Connect Okta, Entra ID, Auth0, Keycloak, or any standards-compliant OIDC provider for sign-in.
Sign users in through any standards-compliant OIDC provider. Each organisation
has one SSO connection, for one email domain. The sso feature is on by default.
Heads up
eddytor login alike - and never gets a magic link, whatever enforceSso says.
If the IdP breaks, delete the connection from inside the server container
(eddytoradm list-sso, then eddytoradm delete-sso --id <id>); the domain falls
back to magic links.Before you start
- You are an org admin.
- An OIDC app at your IdP with redirect URI
${server.public_url}/v1/oauth/sso/callback(no/apiprefix). Capture the client ID, client secret, and issuer URL.- Entra ID: follow SSO with Microsoft Entra ID.
- Okta: Applications → Create App Integration → OIDC / Web Application.
The issuer is e.g.
https://your-tenant.okta.com. - Keycloak, Auth0, Authentik, others: same pattern.
Create the connection
eddytor create sso \
--issuer-url https://your-tenant.okta.com \
--client-id 0oa… \
--client-secret … \
--email-domain example.com \
--default-role editorcurl -fsS -X POST "http://localhost:8080/api/v1/organisations/$ORG_ID/sso" \
-H "Authorization: Bearer $EDDYTOR_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"displayName": "Okta",
"issuerUrl": "https://your-tenant.okta.com",
"clientId": "0oa…",
"clientSecret": "…",
"emailDomain": "example.com",
"enforceSso": false,
"defaultRole": "editor"
}'$ORG_ID comes from GET /api/v1/organisations.
| Field | Notes |
|---|---|
issuerUrl | Must be https://. Eddytor fetches ${issuer}/.well-known/openid-configuration at create time and rejects the connection if that fails or the document's issuer differs. |
emailDomain | Lowercase. Sign-ins at this domain go to your IdP. One organisation can claim a domain. |
enforceSso | true refuses self-service onboarding for the domain. It does not change sign-in. |
defaultRole | viewer (default), editor, builder, or admin - granted to users created on their first SSO sign-in. |
emailClaimFallback | none (default) or preferred_username: the claim to use when the ID token has no email claim. preferred_username is Entra ID only - see SSO with Microsoft Entra ID. |
displayName | Optional label (default SSO). |
Change or remove it with eddytor set sso … / eddytor delete sso, or PATCH
(any subset of the fields) / DELETE on /api/v1/organisations/$ORG_ID/sso.
There is no connection id in the path.
Verify
Sign out, run eddytor login (or open the web UI), and enter
alice@example.com. The browser goes to your IdP, then back through
/v1/oauth/sso/callback, and you are signed in.
Don't test with a bare /v1/oauth/authorize?login_hint=… URL: that endpoint
needs a full OAuth request and answers missing response_type without one.
Gotchas
- The ID token must carry an
emailclaim unlessemailClaimFallbacknames another. Without one the browser showsSSO authentication failedand the server logsID token missing email claim. - The address must be at
emailDomain, or the browser showsEmail domain does not match SSO configuration. - An existing user who isn't a member of the organisation is refused. A domain match doesn't add an account to an organisation - invite them first.
- The callback always uses
server.public_url.oauth_redirect_baseapplies only to cloud-account linking.