Skip to main content

​
Overview

Experio uses PropelAuth BYO (a self-hosted sidecar) for enterprise Single Sign-On. It supports OIDC-based authentication with Microsoft Entra ID, Okta, and any Generic OIDC-compatible identity provider. PropelAuth acts as the source of truth for SSO client configuration — Experio’s admin panel manages SSO clients by syncing them with the PropelAuth sidecar via its integration API. Navigate to Admin > Users > SSO Clients to manage SSO configurations.

​
Prerequisites

Before configuring SSO, ensure you have:
  • A running Experio deployment with the PropelAuth BYO sidecar container
  • Admin access to the Experio admin panel
  • An identity provider account (Microsoft Entra ID, Okta, or any OIDC-compatible provider)
  • The redirect/callback URL for your deployment: https://<your-domain>/api/auth/sso/callback

​
PropelAuth First-Time Setup

Before configuring SSO clients, 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. 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.

​
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 (Application ID)
    • tenant_id (Directory ID)
    • client_secret (Secret Value)
Client secrets expire. Set a calendar reminder to rotate the secret before expiration to avoid SSO login failures.
For more details, see the PropelAuth Entra Setup Guide.

​
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).
For more details, see the PropelAuth Okta Setup Guide.

​
Generic OIDC

For any OIDC-compatible provider, collect these values: Set the redirect URI in your provider to https://<your-domain>/api/auth/sso/callback.

​
Supported Identity Providers

​
Creating SSO Clients

Navigate to Admin > Users > SSO Clients and click Create New.

​
Basic Information

  • Email Domains: One or more 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. Leave empty to allow all domains — the SSO client becomes a catch-all that any email can use. At most one active SSO client can have empty email domains at a time.
  • Display Name (required): Human-readable name (e.g., “Acme Corporation”).
  • Identity Provider Type (required): Microsoft Entra ID, Okta, or Generic OIDC.

​
Identity Provider Credentials

  • Client ID (required): From your IdP app registration.
  • Client Secret (required): From your IdP.
  • Tenant ID (Microsoft Entra only): Azure Directory/Tenant ID.
  • SSO Domain (Okta only): Your Okta domain (e.g., dev-12345.okta.com). Enter just the domain, not a full URL — the http:// prefix is automatically stripped if provided.
  • Auth URL, Token URL, UserInfo URL (Generic OIDC only): The OIDC endpoint URLs from your provider.

​
Review and Confirm

  • Review the configuration summary.
  • The Redirect URL is displayed (auto-generated as https://<your-domain>/api/auth/sso/callback).
  • This redirect URL must match what you configured in your identity provider.
The Customer ID is automatically generated from the first email domain with a unique suffix (e.g., acme.com becomes acme-com-a1b2c3d4). For allow-all clients with no email domains, the ID uses the format allow-all-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. Enable SSO: Set USE_PROPELAUTH to True in Admin > Settings > System Settings > AUTH.
  3. Enable hybrid login (recommended during testing): Set ALLOW_HYBRID_LOGIN to True to keep password login available as a fallback.
  4. 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.
  5. 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.

​
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 matching SSO client.
  5. If no domain-specific match is found, Experio checks for an active “allow all domains” SSO client as a fallback.
  6. If a matching active SSO client is found (either by domain or fallback), PropelAuth initiates an OIDC login flow.
  7. The user is redirected to their identity provider’s login page (e.g., Microsoft login).
  8. After authenticating, the IdP redirects back to Experio’s callback URL.
  9. PropelAuth completes the OIDC flow and extracts user information.
  10. Experio creates or updates the user account. 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.
  11. Active users are redirected to Experio with an active session.
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. Clients with no email domains display an “Allow all domains” badge.

​
Editing

Click any SSO client to view and edit its configuration. You can clear all email domains to make the client an “allow all” catch-all — the detail page shows an “Allow all domains” badge in this state. Changes take effect immediately for new login attempts.
Client secrets are never displayed after creation for security. To update a client secret, enter the new value in the edit form.

​
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 from both Experio and 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