Configure OpenID Connect SSO for Google Workspace, Microsoft Entra, and generic OIDC identity providers.

Enterprise and Agency plans can configure organization-level SSO using a single OpenID Connect (OIDC) integration layer. Additional contract-phase identity or network requirements are handled by your account team.

Overview

CookieShift acts as an OIDC relying party (RP):

1. User enters their work email on the login page.
2. CookieShift discovers the organization SSO configuration by email domain.
3. User is redirected to your IdP with PKCE (S256).
4. On callback, CookieShift validates the ID token against the IdP JWKS, maps roles, and JIT-provisions the user into the correct workspace.

Password and consumer Google sign-in can be blocked when your organization enables enforce SSO.

Prerequisites

• Enterprise or Agency plan with the SSO feature enabled
• Admin access with Users manage permission on the organization
• An OIDC application registered with your identity provider
• Redirect URI registered at the IdP:

https://YOUR_DASHBOARD_HOST/api/auth/oidc/callback

Optional environment override: OIDC_REDIRECT_URI.

Configure SSO (API)

Org admins can read and update SSO settings:

The PATCH body supports:

• enabled, provider, clientId, clientSecret (stored encrypted)
• issuerUrl (generic OIDC)
• allowedDomains — email domain allow list
• enforceSso, disablePasswordLogin
• provisioning — JIT defaults, optional requireInvite
• claimMapping — IdP groups/roles claim names

Provider templates

Generic OIDC (Auth0, Okta, Keycloak, OneLogin, custom)

Set provider to oidc (or auth0, okta, keycloak, onelogin, custom) and provide:

• issuerUrl — OpenID Provider issuer (discovery document at /.well-known/openid-configuration)
• clientId / clientSecret
• allowedDomains — e.g. ["example.com"]

Google Workspace

Set provider to google_workspace:

• Register a Web application OAuth client in Google Cloud Console
• Authorized redirect URI: your CookieShift callback URL
• Set googleHostedDomain to your primary Google Workspace domain (e.g. acme.com)
• Add the same domain (and aliases) to allowedDomains

CookieShift validates the IdP hd (hosted domain) claim on login.

Microsoft Entra ID (Azure AD)

Set provider to entra:

• Register an app in Microsoft Entra admin center
• Redirect URI: Web → your CookieShift callback URL
• Set entraTenantId to your tenant GUID (or common for multi-tenant apps)
• Add corporate email domains to allowedDomains

CookieShift validates the tid (tenant id) claim when a specific tenant is configured.

Role mapping

Use role mappings to map IdP group IDs or role names to CookieShift workspace roles:

{
  "mappings": [
    {
      "idpGroupId": "admins-group-id",
      "workspaceId": "WORKSPACE_OBJECT_ID",
      "workspaceRole": "admin",
      "priority": 10,
      "enabled": true
    }
  ]
}

Unmatched users receive provisioning.defaultRole in provisioning.defaultWorkspaceId (or the org’s first active workspace).

JIT provisioning

When provisioning.jitEnabled is true (default):

• New IdP users are created without a personal shadow tenant
• Workspace membership is upserted on each SSO login
• Set provisioning.requireInvite to allow SSO only for emails with a pending workspace invite

Login flow (end users)

1. Open the CookieShift login page.
2. Enter your work email — if SSO is configured, Continue with SSO appears.
3. Complete authentication at your IdP.
4. You are redirected back to the dashboard with a session cookie.

Troubleshooting

Security notes

• Authorization requests use PKCE (S256) and signed state (JWT)
• ID tokens are validated with remote JWKS (cached discovery + keys)
• SSO policy is enforced on password and consumer Google paths via evaluateSsoPolicy

For contract-specific network or identity requirements beyond OIDC, contact your account team.