Single Sign-On (SSO)

Your IT security team requires that all 500 users across three manufacturing sites authenticate through your corporate Azure AD tenant -- no local passwords, no password resets, and every login event correlated with your SIEM. ProBeya supports enterprise SSO with OIDC and SAML 2.0, with Just-In-Time provisioning and optional SSO enforcement that disables password-based login entirely.

SSO is available on the Enterprise plan (feature gate level 3).

SSO Protocol Decision Matrix

Choose a protocol based on your IdP capabilities and organizational requirements:

Criterion	OIDC (Azure AD / Generic)	SAML 2.0
Best for	Azure AD, Okta, Auth0, Keycloak, Google Workspace	ADFS, Shibboleth, Ping Identity, OneLogin, legacy IdPs
Certificate management	Automatic via .well-known discovery	Manual X.509 certificate upload, must track expiry
Token format	JWT (compact, inspectable)	XML assertions (verbose, signed)
Setup complexity	Lower (auto-discovery)	Higher (certificate exchange, metadata import)
Session binding	Standard OAuth 2.0 flows	SAML assertion consumer service (ACS)
GxP audit trail	Login events logged with IdP token claims	Login events logged with SAML assertion attributes
Recommendation	Preferred for new deployments	Use when OIDC is not supported by your IdP

Provider Types

ProBeya stores SSO configuration with three provider type identifiers:

Provider Type	Protocol	Description
azure_ad	OIDC	Microsoft Azure Active Directory / Entra ID -- the primary SSO target for enterprise pharma
oidc_generic	OIDC	Any OIDC-compliant IdP (Okta, Auth0, Keycloak, Google Workspace)
saml	SAML 2.0	Enterprise SAML IdPs (ADFS, Shibboleth, Ping Identity, OneLogin)

Only one SSO configuration is active per organization at a time. The configuration is stored in the sso_configurations table with a UNIQUE constraint on organizationId.

Getting Started

1. Navigate to Settings > SSO.
2. Select your provider type (Azure AD, OIDC Generic, or SAML).
3. Enter the required fields (see sections below).
4. Click Save, then Test Connection to verify.
5. Click Activate to enable SSO for your organization.

tip

Save your SSO configuration before clicking Test Connection. The test reads the saved configuration from the database, not the unsaved form values.

OIDC Configuration (Azure AD / Generic)

Required Fields

Field	Description	Example
Client ID	Application/client identifier from your IdP	abc123-def456-ghi789
Client Secret	Application secret (stored encrypted, masked with •••••••••••• in all API responses)	Generated in IdP
Issuer URL	Base URL of the OIDC provider	https://login.microsoftonline.com/{tenantId}/v2.0

Optional Fields

Field	Description	When to Use
Authorization URL	Override the authorization endpoint	Only for non-standard providers that lack .well-known discovery
Token URL	Override the token endpoint	Only for non-standard providers

ProBeya auto-discovers endpoints via the .well-known/openid-configuration document when you test the connection. For Azure AD, the issuer URL format is https://login.microsoftonline.com/{tenantId}/v2.0.

Azure AD Setup Checklist

1. In the Azure Portal, register a new App Registration.
2. Set the Redirect URI to https://{slug}.probeya.com/api/auth/callback/azure-ad.
3. Under Certificates & secrets, create a new client secret.
4. Under Token configuration, add the email, preferred_username, and name optional claims.
5. Copy the Client ID, Client Secret, and Tenant ID into ProBeya.
6. Test the connection and activate.

Security

The OIDC client secret is never returned in API responses. It is replaced with a mask placeholder (••••••••••••) after initial entry. If you need to change the secret, enter a new one -- you cannot view the existing value. This prevents accidental exposure through API response logging or browser developer tools.

SAML 2.0 Configuration

Required Fields

Field	Description	Example
SSO Entry Point	IdP's sign-in URL (HTTP-Redirect binding)	https://idp.example.com/saml/sso
X.509 Certificate	IdP's public signing certificate (PEM format)	-----BEGIN CERTIFICATE-----...
Issuer / Entity ID	IdP entity identifier	https://idp.example.com/entity

Optional Fields

Field	Description	When to Use
Metadata URL	URL to the IdP's SAML metadata XML	Enables auto-population of entry point, certificate, and entity ID

Copy the ACS (Assertion Consumer Service) URL and SP Entity ID from the ProBeya settings page into your IdP. ProBeya can also generate SP metadata XML for import into your IdP.

SAML Metadata Support

When a Metadata URL is provided, ProBeya:

1. Fetches the XML document from the IdP.
2. Parses and validates the metadata structure.
3. Extracts the SSO entry point, certificate, and entity ID.
4. Auto-populates the configuration fields.

If parsing fails, a SsoProviderError is returned with details (network error, invalid XML, missing required fields).

SSO Lifecycle Management

Operation	Description	Security Impact
Save Config	Create or update SSO configuration (upsert)	Configuration stored; no user impact until activated
Test Connection	Verify OIDC discovery or SAML metadata reachability	No user impact; validates IdP connectivity
Activate	Enable SSO after passing readiness checks	SSO button appears on login page
Deactivate	Disable SSO and turn off enforcement	SSO button disappears; users fall back to password auth
Toggle Enforcement	Enable or disable SSO-only login	When enforced, password login is disabled for non-admin users
Delete Config	Remove SSO configuration entirely	SSO button immediately disappears from login page

SSO Enforcement

When SSO enforcement is enabled, all non-admin users lose password login access. Before enabling enforcement:

1. Verify at least one org_owner or tenant_admin retains password access for emergency recovery.
2. Confirm all users have been provisioned in your IdP.
3. Test the SSO flow with a non-admin account.
4. Document the break-glass procedure for SSO outages.

Permissions

• View/Edit SSO settings -- Organization Owners and Admins only. The assertAdminRole check verifies the caller's membership role before every SSO operation.
• Regular members and guests cannot access or modify SSO configuration.
• All SSO configuration changes are logged to the audit trail.

Integration with Multi-Site Deployments

Single Org with Multiple Sites (Recommended)

One SSO configuration covers all sites. Users from Brussels, Dublin, and Singapore authenticate through the same Azure AD tenant. Site-level access is controlled through workspace roles, not SSO configuration.

Multiple Orgs per Site

Each organization has its own SSO configuration. This requires separate app registrations in your IdP, one per ProBeya organization (subdomain). Callback URIs differ per org: https://{site-slug}.probeya.com/api/auth/callback/.

21 CFR Part 11 Compliance

Requirement	SSO Contribution	Reference
Unique user identification	SSO maps corporate identities 1:1 to ProBeya users	11.10(d)
Authority checks	IdP group claims can be used for role mapping	11.10(d)
Audit trail of logins	Every SSO login event is recorded with timestamp and IdP claims	11.10(e)
Session management	SSO sessions inherit IdP token expiry + ProBeya session timeout	11.10(g)
Open system controls	SSO enforcement eliminates password-based attack surface	11.10

Recovery Procedures

Scenario	Resolution
SSO IdP is down, users locked out	An org_owner or tenant_admin with password access can deactivate SSO enforcement to restore password login
IdP certificate expired (SAML)	Upload the renewed certificate in Settings > SSO and re-test the connection
SSO misconfigured, all users locked out	Contact ProBeya support for emergency SSO bypass using the organization's registered billing email
Azure AD tenant migration	Update the Issuer URL and Client ID/Secret in Settings > SSO; update the callback URI in the new Azure AD app registration
SSO button not appearing	Verify the configuration is saved, the test passes, and the configuration is activated (not just saved)

Best Practices

• Use OIDC where possible -- it provides richer discovery and simpler certificate management.
• Configure a descriptive Display Name so users recognize their corporate login option (e.g., "Sign in with Acme SSO").
• Combine SSO with 2FA enforcement for defense-in-depth.
• Keep the IdP certificate up to date -- expired certificates cause silent login failures.
• Monitor SSO login events in the Audit Log for failed authentication attempts.
• When activating SSO enforcement, ensure at least one admin retains password access for the break-glass scenario.

Related Features

• Security Settings -- 2FA enforcement, session policies, IP allowlisting.
• Roles & Permissions -- Control who can manage SSO.
• Audit Log -- SSO login events and configuration changes appear in the audit trail.
• Branding -- The SSO login button uses your organization's branding.