Set up SSO (OIDC)

1. Register the app at your IdP

• Application type: Web, authorization code flow.
• Redirect URI: {web_protocol}://{web_hostname}/api/v2/auth/oidc/callback
• Scopes: openid email profile.

2. Configure CamelMailer

oidc:
  enabled: true
  name: Okta                 # the label on the login button
  issuer: https://acme.okta.com
  identifier: client-id
  secret: client-secret
  scopes: [openid, email, profile]
  auto_provision: true       # create users on first login
  allowed_email_domains: [acme.com]

Restart the web role. The login page now shows “Sign in with Okta”; the flow starts at GET /api/v2/auth/oidc/start and hands the session back to auth.frontend_url.

3. Decide provisioning

• auto_provision: true means anyone from allowed_email_domains gets an account on first login. Organization membership still comes from invitations.
• auto_provision: false means SSO signs in existing accounts only; create them via invitations first.

Testing tips

• Test in a private window, because IdP session reuse hides half the flow.
• The auth audit log (GET /api/v2/admin/auth_events) shows every attempt with its outcome, your first stop when a login loops.
• Clock skew breaks token validation: make sure the host runs NTP.