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 with the account they already use at work.

SSO is not self-serve yet: there is no SSO screen in the workspace admin app. Email help@cirrux.info and we set up the connection for your workspace with you.

How it works

Sign-in flow

When SSO is configured, users enter their email address on the Cirrux login page. If the address is at one of your workspace’s domains, the button changes to Continue with SSO and takes them to your identity provider. Once they have signed in there, they land back in Cirrux, signed in.

Cirrux uses the Authorization Code flow with PKCE (Proof Key for Code Exchange). The ID token’s signature, issuer, audience and nonce are checked against your provider’s published JWKS keys.

SSO covers signing in on the Cirrux login page. Mail, calendar and contacts apps that connect over IMAP, SMTP, CalDAV or CardDAV do not go through your identity provider; they sign in with an app password.

Auto-provisioning

When auto-provisioning is enabled, someone who signs in via SSO for the first time is added to your workspace automatically. Cirrux creates a user account, a mailbox at your workspace’s default domain, and a workspace membership, with no invitation needed.

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

SSO can optionally be enforced for your workspace. When enforcement is on:

  • Non-admin members are sent to your identity provider when they sign in
  • Password sign-in on the login page is refused for them, whether they type their address, their username or another alias
  • Workspace admins keep password access, so you are never locked out if your identity provider is down

Setup

Setting it up with us

  1. Create an OIDC application in your identity provider (see the guides below)
  2. Email help@cirrux.info with your issuer URL, and we arrange with you how to hand over the client_id and client_secret
  3. We add the connection to your workspace. Cirrux discovers your provider’s endpoints from its .well-known/openid-configuration document
  4. Tell us whether you want auto-provisioning and enforcement switched on

Callback URL

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

https://api.cirrux.info/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.info/auth/sso/callback
  5. Under Assignments, assign the users or groups who should have access
  6. Send us the Client ID and Client Secret
  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.info/auth/sso/callback
  3. Under Certificates & secrets, create a new client secret
  4. Send us the Application (client) ID and the client secret value
  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.info/auth/sso/callback as an authorized redirect URI
  4. Send us the Client ID and Client Secret
  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 signed in via SSO before, 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 there is no match and auto-provisioning is enabled, a new user and mailbox are created. Without auto-provisioning, sign-in fails and the user is asked to contact their administrator

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

HelpPrivacyTermsDPASustainability