Single sign-on (SSO) with OpenID Connect (OIDC)

For IT / identity and Festivo team owners or admins. This page describes what to configure in your identity provider (IdP) and what to enter in the Festivo app.

Where: Open Festivo, then Settings → Team → SSO (/settings/team/sso). Only owners and admins see this screen.

Plan: OIDC SSO is included on the Titan plan. If you are unsure which plan you have, check Settings → Subscription in Festivo or see Pricing. For other commercial arrangements, contact Festivo sales.
Scope: These settings apply to human sign-in to Festivo (Explorer, calendars, billing, and the rest of the signed-in experience). API keys are separate unless your org adopts a different policy later.

1. What you are connecting

Item	Value
Protocol	OpenID Connect (OIDC), authorization code flow.
Sign-in flow	After SSO is saved, users whose email matches an allowed domain use Continue with Email on the Festivo login (and join) page and are redirected to your IdP.
Redirect URI	Copy the exact value from the SSO page (Redirect URI (for your IdP)). It looks like `https://<your-portal-host>/api/auth/sso/oidc/callback`.
Allowed domains	Domains that may use this team’s SSO (e.g. `example.com`). Use the same domains your IdP puts in `email` claims.

Store the IdP OpenID Connect discovery URL, client ID, and client secret in Festivo. The client secret is encrypted at rest; the API deployment must have ORG_SSO_ENCRYPTION_KEY set (32-byte key; operators often generate with openssl rand -base64 32). Your Festivo operator should confirm this is set in production before you save a client secret.

2. Microsoft Entra ID (Azure AD)

App registration: Entra admin center → App registrations → New registration.
- Name: e.g. Festivo Portal.
- Supported account types: match your security policy (single tenant vs guests).
Redirect URI: Web → paste Festivo’s redirect URI from the SSO page.
Certificates & secrets: New client secret — copy once; paste into Festivo as Client secret.
Endpoints: Endpoints (or app overview) → copy OpenID Connect metadata document URL — paste as Discovery URL (must be https://).
API permissions: For sign-in you typically need Microsoft Graph → openid, email, profile (delegated). Grant admin consent if your tenant requires it.
Token configuration (optional): Ensure the ID token includes email (and name fields) if you rely on JIT provisioning.

Festivo Client ID = Application (client) ID on the overview blade.

3. Okta

Create app integration: Applications → Create App Integration → OIDC → Web.
Sign-in redirect URIs: paste Festivo’s redirect URI.
Client authentication: Client secret (what the portal stores today).
General tab: copy Client ID and Client secret into Festivo.
Discovery URL: usually
https://<your-okta-domain>/oauth2/default/.well-known/openid-configuration
or /oauth2/<auth-server-id>/... for a custom authorization server. Must be HTTPS.

Assign users or groups in Okta so they can sign in to the app.

4. Google Workspace (Cloud Identity)

Google Cloud Console → APIs & Services → Credentials → Create credentials → OAuth client ID.
Application type: Web application.
Authorized redirect URIs: Festivo’s redirect URI.
Discovery URL: commonly
https://accounts.google.com/.well-known/openid-configuration
(issuer https://accounts.google.com) unless your security team requires a different setup.
Client ID and Client secret from the credentials screen → Festivo.

Restrict the OAuth client to internal (workspace) users if you must block consumer Google accounts.

5. Policies in Festivo

Policy	Meaning
JIT provisioning	When enabled, first-time users with a matching domain can be added as members after a successful SSO (subject to seat limits and IdP assignment).
Require SSO	When on, members whose email matches allowed domains must use company OIDC for this team — not magic link, Google/GitHub, or passkey for that account. API keys are unchanged.

Start with JIT and Require SSO off until redirect URIs and tokens work end-to-end. Use Test discovery URL on the SSO page to confirm the metadata endpoint is reachable before saving secrets.

6. Checklist before go-live

Redirect URI in the IdP matches Festivo character-for-character (scheme, host, path).
Discovery URL is HTTPS and reachable from Festivo’s API environment.
Client secret rotated if exposed; new secret saved in Festivo.
Allowed domains match the email domains your IdP asserts.
Test discovery URL succeeds from the SSO form.
Test user completes sign-in from the Festivo login page (the email typed before redirect should match the identity the IdP returns).
Where enabled, Team → Activity (Growth and above) helps audit membership and settings changes.

7. Troubleshooting

Symptom	What to check
“Server is not configured for SSO secret storage”	Operators must set `ORG_SSO_ENCRYPTION_KEY` (32-byte key, base64 or hex) on the API service.
403 when opening SSO settings	User is not owner/admin, or your subscription does not include SSO — upgrade to Titan or contact Festivo sales.
IdP error `redirect_uri_mismatch`	Redirect URI in the IdP must match Festivo exactly (including trailing slash rules).
“Use company SSO” on magic link / passkey / social	Require SSO is on and your email domain matches — complete sign-in via Continue with Email (OIDC).

Product questions: contact@getfestivo.com (team name only — never put secrets in email).

See also: Enterprise SSO (OIDC) · Festivo for enterprises · Pricing