SSO & cloud providers

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

Every enabled connection federates its domain. A user at the connection's email domain always signs in through the IdP - web UI and 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 /api prefix). 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 editor
curl -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.

FieldNotes
issuerUrlMust 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.
emailDomainLowercase. Sign-ins at this domain go to your IdP. One organisation can claim a domain.
enforceSsotrue refuses self-service onboarding for the domain. It does not change sign-in.
defaultRoleviewer (default), editor, builder, or admin - granted to users created on their first SSO sign-in.
emailClaimFallbacknone (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.
displayNameOptional 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 email claim unless emailClaimFallback names another. Without one the browser shows SSO authentication failed and the server logs ID token missing email claim.
  • The address must be at emailDomain, or the browser shows Email 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_base applies only to cloud-account linking.

On this page