Skip to main content

Overview

Experio supports OIDC-based enterprise Single Sign-On with Microsoft Entra ID, Okta, Google Workspace, and any Generic OIDC-compatible identity provider. Two SSO backends are available, selected by the SSO_BACKEND system setting:
  • native: Experio runs the OpenID Connect login itself. SSO client configuration, including the encrypted client secret, is stored in Experio. It supports all four identity provider types.
  • propelauth (default): Experio delegates the OIDC login to the PropelAuth BYO sidecar, and syncs SSO clients to it through its integration API. Google Workspace is not available with this backend.
Both backends use the same login page, the same callback URL, and the same SSO clients, so you can switch between them with a single setting. See Switching to the native backend. Navigate to Admin > Users > SSO Clients to manage SSO configurations.

Prerequisites

Before configuring SSO, ensure you have:
  • Admin access to the Experio admin panel
  • An identity provider account (Microsoft Entra ID, Okta, Google Workspace, or any OIDC-compatible provider)
  • The redirect/callback URL for your deployment: https://<your-domain>/api/auth/sso/callback. The SSO client form shows this URL with a copy button.
  • For the propelauth backend only: a running PropelAuth BYO sidecar container (see below)

PropelAuth First-Time Setup

This section applies only when SSO_BACKEND is propelauth. The native backend needs no sidecar and no API key.
Before configuring SSO clients with the PropelAuth backend, you must set up PropelAuth BYO and obtain an integration API key.

Automated Setup (Default)

The default deployment automatically creates the PropelAuth API key during initialization. To enable this, set the PropelAuth Setup Secret (propelauthSetupSecret) deployment parameter when creating or updating your Experio instance. This is the only configuration needed — everything else is handled automatically. The automated setup works as follows:
  1. You provide the propelauthSetupSecret deployment parameter (must be at least 16 characters). This sets the INITIAL_SETUP_SECRET environment variable on the PropelAuth BYO container.
  2. During deployment, the setup_propelauth management command calls the PropelAuth /api/initial_setup endpoint with this secret.
  3. The returned API key is automatically stored as PROPELAUTH_API_KEY in system settings.
The automated setup only works for the first API key creation, and it skips when any PROPELAUTH_API_KEY is already stored, even one PropelAuth no longer recognizes. If you need to recreate the key, use the manual method below.

Manual Setup (Fallback)

If automated setup is not available or fails, follow these steps:
  1. Access the cluster where Experio is deployed.
  2. Forward the PropelAuth port to your local machine:
  3. Open the PropelAuth dashboard at http://localhost:2884. Log in with the default credentials:
    • Username: root
    • Password: thispasswordistemporary
  4. Create a new password when prompted. Save this password securely.
  5. Create an integration API key: Click the gear icon, then go to Manage Settings and select the Integration Keys tab. Create a new key with FullAccess permissions.
  6. Save the API key in Experio: Navigate to Admin > Settings > System Settings > AUTH and set PROPELAUTH_API_KEY. See System Settings for details.
Change the default PropelAuth dashboard password immediately. Store the new password and the API key securely.

System Settings

Navigate to Admin > Settings > System Settings > AUTH tab to configure SSO behavior. See System Settings for the complete reference.
Login modes based on settings:
  • USE_PROPELAUTH=False — Standard email/password login only
  • USE_PROPELAUTH=True + ALLOW_HYBRID_LOGIN=False — SSO-only login
  • USE_PROPELAUTH=True + ALLOW_HYBRID_LOGIN=True — Both password and SSO login available

Identity Provider Setup

Before creating an SSO client in Experio, register an application in your identity provider. In every case, the redirect URI is https://<your-domain>/api/auth/sso/callback, and the SSO client form in Experio shows it with a copy button.

Microsoft Entra ID (Azure AD)

  1. Register an application in the Azure Portal:
    • Navigate to Microsoft Entra ID then App registrations then New registration.
    • Name the application (e.g., “Experio SSO”).
    • Select Accounts in this organizational directory only (single tenant).
    • Set Redirect URI type to Web and enter: https://<your-domain>/api/auth/sso/callback
  2. Copy credentials from the app’s Overview page:
    • Application (client) ID — used as Client ID
    • Directory (tenant) ID — used as Tenant ID
  3. Create a Client Secret:
    • Go to Certificates & secrets, then Client secrets, then New client secret.
    • Set a description and expiration period.
    • Copy the secret Value immediately (it is shown only once).
  4. You will need these three values when creating the SSO client in Experio: Client ID, Tenant ID, and Client secret.
No optional claims are required. Experio reads the user’s email from the email claim, then the upn claim, then the preferred_username claim, and only accepts tokens issued by the configured tenant.
Client secrets expire. Set a calendar reminder to rotate the secret before expiration to avoid SSO login failures.

Okta

  1. Go to Okta Admin Console, then Applications, then Create App Integration.
  2. Select OIDC - OpenID Connect and Web Application.
  3. Set the Sign-in redirect URI to https://<your-domain>/api/auth/sso/callback.
  4. Note your Client ID, Client Secret, and Okta domain (e.g., dev-12345.okta.com).
  5. If you use an Okta authorization server (for example default), note its ID. Leave it empty to use the Okta org authorization server.
Okta must include a verified email in the ID token (email and email_verified claims).

Google Workspace

Google Workspace requires SSO_BACKEND set to native.
  1. In the Google Cloud Console, open APIs & Services, then Credentials, then Create Credentials, then OAuth client ID.
  2. Select Web application and add https://<your-domain>/api/auth/sso/callback under Authorized redirect URIs.
  3. Note the Client ID and Client secret.
  4. Note your Workspace domain (e.g., acme.com). Experio only accepts accounts from this Google Workspace domain, checked on every login.

Generic OIDC

For any OIDC-compatible provider, collect these values: With the propelauth backend, PropelAuth does not read the discovery document, so it needs the three endpoint URLs as you type them. Your provider lists them in its OpenID configuration at <issuer>/.well-known/openid-configuration. With the native backend you do not enter them. Set the redirect URI in your provider to https://<your-domain>/api/auth/sso/callback. The provider must include a verified email in the ID token (email and email_verified claims). PKCE is on by default; turn off Use PKCE only if your provider rejects it.

Supported Identity Providers

Creating SSO Clients

Navigate to Admin > Users > SSO Clients and click Add client.

Basic Information

  • Display Name (required): Human-readable name (e.g., “Acme Corporation”).
  • Email Domains (required, at least one): The domains this SSO applies to (e.g., acme.com, acme.io). Users with any of these email domains will be redirected to SSO login. Type each domain and press Enter to add it. Each domain can belong to only one SSO client.
    • With the native backend, the domains also let new users in: a person’s email domain is checked the first time they sign in. Removing a domain does not block people who have already signed in, because later sign-ins are not checked against the list again. To remove someone’s access, deactivate them in Admin > Users > Profile Management.
    • With the propelauth backend, only users with these email domains can sign in.
  • Identity Provider Type (required): Microsoft Entra ID, Okta, Google Workspace, or Generic OIDC. The type cannot be changed after creation.

Identity Provider Settings

The form shows only the fields for the selected type:
  • Microsoft Entra ID: Tenant ID, Client ID, Client secret.
  • Okta: Okta domain (just the domain, not a full URL), Authorization server (optional), Client ID, Client secret.
  • Google Workspace: Workspace domain, Client ID, Client secret.
  • Generic OIDC: Issuer URL, Client ID, Client secret, Use PKCE. With the propelauth backend, the form also asks for the Authorization URL, Token URL, and UserInfo URL, all three required.
The Redirect URI is shown read-only with a copy button and instructions for where to paste it in your identity provider.

Check Configuration

Click Check configuration to confirm that Experio can reach your identity provider’s discovery document. A successful check shows the issuer and the authorization and token endpoints. The client ID and secret are not sent and are only verified at the first sign-in.
The Customer ID is automatically generated from the first email domain with a unique suffix (e.g., acme.com becomes acme-com-a1b2c3d4). Customer IDs are immutable after creation.

Activating SSO

Follow these steps carefully to enable SSO without losing admin access:
  1. Create a fallback admin user: Before enabling SSO, ensure you have a local admin user with the same email domain as the SSO client. Set this user as a superuser so you retain access if SSO has issues.
  2. Choose the backend: Keep SSO_BACKEND at propelauth, the default. Read Switching to the native backend before choosing native.
  3. Enable SSO: Set USE_PROPELAUTH to True in Admin > Settings > System Settings > AUTH.
  4. Enable hybrid login (recommended during testing): Set ALLOW_HYBRID_LOGIN to True to keep password login available as a fallback.
  5. Test SSO: Open a new incognito/private browser window, navigate to the login page, enter an email for the configured domain, and verify the SSO redirect works correctly.
  6. Disable hybrid login (optional): Once SSO is confirmed working, set ALLOW_HYBRID_LOGIN to False for SSO-only login.
Always test SSO in an incognito window before logging out of your current session. If SSO is misconfigured and hybrid login is disabled, you may be locked out. Keep ALLOW_HYBRID_LOGIN set to True during initial testing.

Switching to the Native Backend

If users already sign in with SSO on your instance, contact Experio support before switching, and test the switch with one user first.
SSO clients created while SSO_BACKEND was propelauth keep their identity provider configuration in PropelAuth. Before switching, copy it into Experio with the migrate_sso_from_propelauth management command, run on the Experio server:
The command copies each client’s identity provider settings and client secret (stored encrypted), and links existing users to their identity provider accounts so they keep the same Experio account. Without --apply it only previews the changes. It can be run more than once, and never prints secrets or email addresses. Use --customer-id <id> to migrate a single client, and --overwrite-secret to replace a secret already stored in Experio. Then set SSO_BACKEND to native and test a login in an incognito window. To roll back, set SSO_BACKEND back to propelauth; the PropelAuth configuration is left unchanged.
If you would rather not run the command, edit each SSO client and enter its identity provider settings and client secret again before switching. Existing users are then not linked in advance: each is matched by email address at their first native sign-in, so a user whose identity provider sends a different address gets a new account.

How SSO Login Works

  1. User navigates to the Experio login page.
  2. The login page shows an email-only form (SSO-only mode) or both password and SSO options (hybrid mode).
  3. User enters their email and submits.
  4. Experio extracts the email domain and looks up the SSO client that lists that domain. If there is none, or the client is inactive, the login stops with an error.
  5. The user is redirected to their identity provider’s login page (e.g., Microsoft login).
  6. After authenticating, the identity provider redirects back to Experio’s callback URL.
  7. Experio (native) or PropelAuth (propelauth) completes the OIDC flow and verifies the identity provider’s response.
  8. Experio finds or creates the user account:
    • With the native backend, each user is linked to their identity provider account on first login. Later logins use that link, so a changed email address at the identity provider does not create a second account. On first login, the user’s email domain must be one of the client’s domains (later logins are not checked against the list again), and the email must be verified by the identity provider (Okta, Google Workspace, Generic OIDC).
    • A user that an admin already created with the same email is linked on first login. Otherwise a new user is created. If PROPELAUTH_SSO_USERS_ACTIVE_BY_DEFAULT is False, new users are created inactive and see a “pending administrator approval” message instead of being logged in.
  9. Active users are redirected to Experio with an active session. The session is handed to the browser with a one-time sign-in code that expires after 60 seconds, never in the URL itself. Experio keeps the code in Redis, so while Redis is full or cannot be reached the sign-in cannot finish. The user sees “Sign-in is temporarily unavailable. Please try again in a minute.” (see Troubleshooting).
SSO users are automatically provisioned on first login. The PROPELAUTH_SSO_USERS_ACTIVE_BY_DEFAULT setting controls whether they are immediately active or require admin approval.

Managing SSO Clients

Viewing

The SSO clients page shows a table with Display Name, Email Domains, IdP Type, Active Status, and Created dates. Click a client to open its detail page. The Identity provider card shows the provider type, client ID, tenant, domain or issuer, whether a client secret is set and when it was last updated, the redirect URI with a copy button, the number of linked users, and the active SSO backend.

Editing

Click Edit to change the display name, email domains, or identity provider settings. A client must keep at least one email domain. Changes take effect immediately for new login attempts. With the native backend, removing an email domain does not block people who have already signed in (see Basic Information).
Client secrets are never displayed after they are saved. The edit form shows when the secret was last updated; click Replace to enter a new one. If you don’t replace it, the current secret is kept.

Deactivating

Toggle the Active status to disable an SSO configuration without deleting it. Users for that domain will fall back to password authentication (if hybrid login is enabled) or be unable to log in.

Deleting

Remove an SSO client permanently. With the propelauth backend, it is also removed from PropelAuth. A confirmation dialog prevents accidental deletion.

Audit Trail

Each SSO client tracks who created the configuration, when it was created, and when it was last modified.

Troubleshooting

External References