cirrux

OpenID Connect SSO

Cirrux supports Single Sign-On (SSO) via OpenID Connect (OIDC). Connect your identity provider — such as Okta, Microsoft Entra ID, or Google Workspace — so team members can sign in to Cirrux using their existing corporate credentials.

How it works

Sign-in flow

When SSO is configured, users enter their email address on the Cirrux login page. If their email domain is linked to an SSO connection, they are redirected to your identity provider to authenticate. After successful authentication, users are automatically signed in to Cirrux.

Cirrux uses the Authorization Code flow with PKCE (Proof Key for Code Exchange) for maximum security. Tokens are validated using your provider’s published JWKS keys.

Auto-provisioning

When auto-provisioning is enabled, new users who sign in via SSO are automatically added to your workspace. Cirrux creates a user account, a mailbox at your workspace’s default SCIM domain, and a workspace membership — no manual invitation required.

If a user with a matching email address already exists in your workspace, their account is linked to the SSO identity on first login. No duplicate accounts are created.

Enforcement

You can optionally enforce SSO for your workspace, which disables password-based login for all non-admin members. When enforcement is enabled:

  • Non-admin users must sign in via your identity provider
  • Password login is blocked with a redirect to SSO
  • Workspace admins retain password access as a break-glass mechanism

Setup

Configure in Cirrux

  1. Go to the admin panel in your Cirrux workspace settings
  2. Navigate to the SSO connections section
  3. Enter your identity provider’s issuer URL — Cirrux will automatically discover endpoints from the .well-known/openid-configuration document
  4. Enter the client_id and client_secret from your identity provider
  5. Test the connection, then activate it
  6. Optionally enable SSO enforcement to require SSO for all non-admin members

Callback URL

When configuring your identity provider, you will need to set the redirect (callback) URI to:

https://api.cirrux.co/auth/sso/callback

Make sure this is added as an allowed redirect URI in your identity provider’s application configuration.

Required scopes

Cirrux requests the following OIDC scopes by default:

openid email profile

These scopes allow Cirrux to read the user’s email address and name from the ID token. Make sure your identity provider is configured to include these claims.

Identity provider guides

Okta

  1. In Okta, go to Applications → Create App Integration
  2. Select OIDC — OpenID Connect as the sign-in method
  3. Select Web Application as the application type
  4. Set the Sign-in redirect URI to https://api.cirrux.co/auth/sso/callback
  5. Under Assignments, assign the users or groups who should have access
  6. Copy the Client ID and Client Secret into the Cirrux admin panel
  7. Use your Okta domain (e.g. https://your-org.okta.com) as the issuer URL in Cirrux

Microsoft Entra ID (Azure AD)

  1. In the Azure portal, go to Microsoft Entra ID → App registrations → New registration
  2. Set the Redirect URI to Web and enter https://api.cirrux.co/auth/sso/callback
  3. Under Certificates & secrets, create a new client secret
  4. Copy the Application (client) ID and the client secret value into the Cirrux admin panel
  5. Use https://login.microsoftonline.com/your-tenant-id/v2.0 as the issuer URL in Cirrux
  6. Under API permissions, ensure openid, email, and profile are granted

Google Workspace

  1. In the Google Cloud Console, go to APIs & Services → Credentials
  2. Create an OAuth 2.0 Client ID with application type Web application
  3. Add https://api.cirrux.co/auth/sso/callback as an authorized redirect URI
  4. Copy the Client ID and Client Secret into the Cirrux admin panel
  5. Use https://accounts.google.com as the issuer URL in Cirrux

User identity mapping

How users are matched

When a user signs in via SSO, Cirrux resolves their identity in the following order:

  1. By SSO subject— if the user has previously signed in via SSO, they are matched by the identity provider’s unique subject identifier
  2. By email address— if a workspace member exists with a matching email, the SSO identity is linked to that membership
  3. Auto-provision— if no match is found and auto-provisioning is enabled, a new user and mailbox are created

Once linked, the SSO subject is stored on the workspace membership, so future logins are matched directly without relying on email address.

HelpPrivacyTermsSustainability