> ## Documentation Index > Fetch the complete documentation index at: https://docs.experio.cloud/llms.txt > Use this file to discover all available pages before exploring further. # SSO Configuration > Set up enterprise Single Sign-On with PropelAuth BYO and identity providers like Microsoft Entra ID, Okta, and Generic OIDC ## Overview Experio uses [PropelAuth BYO](https://docs.byo.propelauth.com/) (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:///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: ```bash theme={null} kubectl port-forward svc/propelauth 2884:2884 ``` 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](/admin-guide/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](/admin-guide/system-settings) for the complete reference. | Setting | Default | Description | | ---------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | `USE_PROPELAUTH` | `False` | Enable PropelAuth-based SSO. When enabled, the login page shows SSO authentication. | | `PROPELAUTH_API_KEY` | — | Integration API key for the PropelAuth BYO sidecar. Set automatically during deployment or manually via the steps above. | | `PROPELAUTH_AUTH_URL` | `http://propelauth:2884` | Internal URL of the PropelAuth BYO sidecar. Only change if your sidecar runs on a different host or port. | | `PROPELAUTH_SSO_USERS_ACTIVE_BY_DEFAULT` | `True` | When enabled, users created through SSO are automatically activated. Disable to require manual admin activation. | | `ALLOW_HYBRID_LOGIN` | `False` | When enabled, both password-based and SSO login are available. When disabled (with SSO enabled), only SSO login is shown. | **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](https://portal.azure.com): * 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:///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](https://docs.byo.propelauth.com/sso/example-setup-guides/entra). ### 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:///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](https://docs.byo.propelauth.com/sso/example-setup-guides/okta). ### Generic OIDC For any OIDC-compatible provider, collect these values: | Field | Description | | --------------- | ----------------------------------- | | `client_id` | OAuth2 Client ID from your provider | | `client_secret` | OAuth2 Client Secret | | `auth_url` | Authorization endpoint URL | | `token_url` | Token endpoint URL | | `userinfo_url` | UserInfo endpoint URL | Set the redirect URI in your provider to `https:///api/auth/sso/callback`. ## Supported Identity Providers | Provider | Protocol | Required Fields | | --------------------------------- | -------- | ----------------------------------------------------------- | | **Microsoft Entra ID** (Azure AD) | OIDC | Client ID, Client Secret, Tenant ID | | **Okta** | OIDC | Client ID, Client Secret, Okta Domain | | **Generic OIDC** | OIDC | Client ID, Client Secret, Auth URL, Token URL, UserInfo URL | ## 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:///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 | Problem | Possible Cause | Solution | | ------------------------------------------ | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "SSO not configured for this organization" | No SSO client with a matching email domain and no allow-all client | Create an SSO client that includes the user's email domain, or configure an allow-all client | | "SSO not enabled for this organization" | SSO client exists but is deactivated | Activate the SSO client in Admin > Users > SSO Clients | | SSO redirect fails or returns 500 | Invalid API key or PropelAuth unreachable | Verify `PROPELAUTH_API_KEY` and `PROPELAUTH_AUTH_URL` in system settings | | "Account pending administrator approval" | `PROPELAUTH_SSO_USERS_ACTIVE_BY_DEFAULT` is `False` and the user is new | Open **Admin > Users > Profile Management**, click the **Activate** action on the inactive user (this also sends them a welcome email), or change the setting to `True`. Activating from Django admin at `/staff/core/user/` skips the welcome email. | | "Only one allow-all client is supported" | Trying to create or edit a second SSO client with no email domains | Only one active SSO client can be configured as "allow all" at a time. Deactivate the existing one first | | Locked out after enabling SSO | SSO misconfigured with hybrid login disabled | Access Django admin at `/staff/` to change `USE_PROPELAUTH` back to `False` | | Client secret expired | IdP client secret has reached its expiration | Rotate the secret in your IdP and update the SSO client in Experio | ## External References * [PropelAuth BYO Documentation](https://docs.byo.propelauth.com/) * [Microsoft Entra Setup Guide](https://docs.byo.propelauth.com/sso/example-setup-guides/entra) * [Okta Setup Guide](https://docs.byo.propelauth.com/sso/example-setup-guides/okta) * [PropelAuth SSO Overview](https://docs.byo.propelauth.com/sso/overview) * [PropelAuth Backend Setup](https://docs.byo.propelauth.com/getting-started/backend-setup)