SSO and MFA

Single sign-on (SSO) allows administrators and users to log in using their organization’s identity provider instead of a separate username and password. Multi-factor authentication (MFA) adds a second verification step — such as a code from a mobile app — for stronger security. Both are supported via the OIDC (OpenID Connect) standard.

Overview

SSO is supported for both the Configuration Manager (admin panel) and Thirdlane Connect (user app). When configured, a “Sign in with SSO” button appears on the login page. Users click it, authenticate with the identity provider (and complete MFA if required), and are redirected back to the application.

Username and password login always remains available as a fallback.

Supported Identity Providers

Any OIDC-compliant identity provider can be used. The following are available as named options in the Authentication Providers dropdown:

• Okta
• Microsoft Entra ID (Azure AD)
• Google Workspace
• Keycloak
• Auth0
• Authentik (self-hosted, OIDC)
• Zoho
• Generic OIDC (any other OIDC-compliant provider)

All OIDC-based providers use the same protocol: the system auto-discovers endpoints from your provider’s /.well-known/openid-configuration URL. Named entries are convenience labels that map to the same underlying OIDC mechanism.

Configuring SSO

Step 1: Create an OIDC Application in Your IdP

In your identity provider’s admin console, create a new OIDC/OAuth2 application with these settings:

• Application type: Web application (confidential client)
• Redirect URIs: Add both of these:
  • https://your-server/oidc/manager/callback (for Configuration Manager)
  • https://your-server/oauth2/oidc/callback (for Thirdlane Connect)
• Scopes: openid, email, profile
• Grant type: Authorization Code

Note the Client ID, Client Secret, and Issuer URL from your IdP.

Step 2: Configure in PBX Manager

1. Navigate to System Settings > Authentication Providers
2. Click Add to add a new provider
3. Select the appropriate provider from the dropdown (or Generic OIDC for unlisted providers)
4. Fill in:
   • Client ID — from your IdP
   • Client Secret — from your IdP
   • Issuer URL — the base URL of your IdP (e.g., https://your-org.okta.com)
   • Button Label — the text to show on the login button (e.g., “Company SSO”)
5. Click Save
6. Copy the displayed redirect URIs and add them to your IdP’s allowed callback URLs

The “Sign in with SSO” button will appear on both login pages.

For detailed per-provider setup instructions, see Authentication Providers.

User Mapping

When a user logs in via SSO, the system matches their identity provider email to an existing PBX account:

• For Configuration Manager: matches against admin usernames and email addresses
• For Thirdlane Connect: matches against user extension names and email addresses

Users must have pre-existing accounts in the PBX. SSO does not automatically create new accounts. Use Directory Services to sync accounts from your corporate directory if needed.

Multi-Factor Authentication

MFA is handled entirely by the identity provider. No additional configuration is needed in the PBX.

Configure MFA policies in your identity provider’s admin console (Okta, Azure AD, Google Workspace, Keycloak, Authentik, etc.). The PBX trusts the identity provider’s authentication result — if the provider issued the token, the user passed all required challenges including MFA.

Configuration Manager Login

When OIDC is configured, the login page shows:

1. The standard username and password form
2. A divider with “or”
3. A “Sign in with SSO” button (or your custom button label)

Clicking the SSO button redirects to the identity provider. After successful authentication, the user is redirected back to the Configuration Manager.

Thirdlane Connect Login

When OIDC is configured, Connect’s login page shows the OIDC provider alongside any other configured providers (Google, Microsoft). Users click the provider icon to open a sign-in popup.

Tenant-Level Identity Providers

In addition to the global (system-wide) identity providers, each organization can have its own SSO configuration:

1. Navigate to Organization Settings > Integrations > Identity Providers
2. Add a provider with the same steps as the global configuration
3. The redirect URI shown is specific to the tenant

Note: Tenant-level identity providers are configured independently from global providers. Currently, global providers appear on the Connect login page for all tenants. Tenant-specific providers configured here provide an additional level of isolation for multi-tenant deployments.

SSO and User Onboarding

SSO works alongside the onboarding modes (invite link and temporary password). When SSO is enabled:

• Users can log in via SSO without needing their initial password
• The welcome/invite email still notifies users about their account and extension details
• Local passwords remain available as a fallback authentication method

Troubleshooting

Issue	Solution
SSO button not visible on login page	Verify OIDC provider is configured in System Settings > Authentication Providers
”Invalid or expired state” error	The login took too long (>10 minutes). Try again.
Redirect back to login page after SSO	No matching PBX user found for the IdP email. Create a user with a matching username or email address.
Connect OIDC button missing	Verify OIDC is configured and check that the /oauth2/providers endpoint returns your provider in the list.
”Provider error” during callback	Verify Client ID, Client Secret, and Issuer URL are correct. Check that the client secret has not expired.
Wrong redirect URI error from IdP	Ensure both redirect URIs displayed after saving are registered in your identity provider’s allowed callback URLs.
SSO works for Manager but not Connect	Both redirect URIs must be registered. The Connect callback URL uses a different path than the Manager callback.
Token exchange fails silently	Enable debug logging and check /var/log/thirdlane/debug.log for OAuth2-related errors.