Sign-in & SSO

A new install has no sign-in: it’s just you. When you turn on team sign-in in Collaborate, OKR.ai supports email one-time codes and magic links, Google, and any OIDC identity provider. SSO is included; there is no enterprise tier.

Set them up in Collaborate → Sign-in methods. They’re stored encrypted in your team database, so every teammate’s copy offers the same ones. The environment variables below still work and win over the app’s settings.

#Email code and magic link

People enter their email and receive a six-digit code and a magic link. Pick SMTP, Resend, Postmark or SendGrid in Collaborate and send yourself a test email, or set SMTP_URL, RESEND_API_KEY, POSTMARK_TOKEN or SENDGRID_API_KEY, plus MAIL_FROM. A team whose members each run OKR.ai needs a real mail service: a code printed in your own terminal would let anyone sign in as anyone.

#Continue with Google

1. Create an OAuth client in Google Cloud (type: Web application).
2. Add the redirect URI <OKRAI_URL>/api/auth/oidc/callback.
3. Paste the client ID and secret in Collaborate → Sign-in methods → Google, or set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET and restart.

#OIDC single sign-on

OKR.ai works with any OpenID Connect provider. It uses the authorization code flow with PKCE and verifies tokens against the provider’s JWKS. There are presets for Okta, Microsoft Entra ID, Google Workspace, Auth0, Keycloak, JumpCloud and AD FS.

#In the app

Admins open Collaborate → Sign-in methods → SSO / identity provider → Add identity provider and fill in:

• Provider: a preset fills in the label and the shape of the issuer URL.
• Issuer URL, e.g. https://company.okta.com. Test issuer checks it publishes an OpenID configuration.
• Client ID and client secret from your provider. The secret is stored encrypted.
• Email domain (optional): only these emails may use it.

Copy the redirect URI shown in the panel into your provider’s app settings. Each provider becomes a Continue with … button on the sign-in screen. You can add several.

#Deployment-wide

To set one provider for the whole deployment, use environment variables:

SSO_NAME="Okta"
SSO_ISSUER="https://company.okta.com"
SSO_CLIENT_ID="…"
SSO_CLIENT_SECRET="…"
SSO_DOMAIN="company.com"

#Sessions

Sessions are HMAC-signed with OKRAI_SECRET_KEY and stored in an HttpOnly, SameSite=Lax cookie. Every RPC call needs a CSRF token and passes a same-origin check.