Corporate Single Sign-On: OpenID Connect (OIDC) & SAML 2.0 (Plugins)
Plugins (
oidc-auth&saml-auth): Built-in official plugins for enterprise identity integration. Enable them on demand under Integration → Plugin Catalog (/plugins). See Plugin system & developer guide.
AiPBX includes native enterprise Single Sign-On (SSO) support through two official plugins:
- OpenID Connect (
oidc-auth): Standard OAuth 2.0 / OIDC Core 1.0 authentication profile. - SAML 2.0 (
saml-auth): Enterprise SAML 2.0 Web Browser SSO profile (Service Provider - SP role) with cryptographic XML signature verification.
Both plugins seamlessly integrate with the web login portal, support mobile client authentication via app deep-links (aipbx://auth), and offer Just-In-Time (JIT) user auto-provisioning with automatic role assignment.
Supported Identity Providers (IdP)
Out-of-the-box compatibility has been verified with major enterprise identity and access management (IAM) platforms:
- Microsoft Entra ID (formerly Azure Active Directory — Enterprise Applications & App Registrations)
- Okta (OIDC Web Apps & SAML 2.0 Applications)
- Keycloak (Open Source Identity and Access Management)
- Authentik & Authelia
- Active Directory Federation Services (ADFS) (Windows Server)
- Google Workspace (Cloud Identity & Google SAML Apps)
- PingFederate & OneLogin
1. OpenID Connect (OIDC) Plugin (oidc-auth)
The OIDC plugin connects AiPBX to any OpenID Provider (OP) implementing discovery and token exchange.
Key Features
- Dynamic OpenID Discovery: Automatically resolves authorization, token, userinfo, and jwks endpoints directly from the provider's discovery URL (e.g.
https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration). Discovery metadata is cached in persistent KV storage (sys_plugin_kv). - Admin Discovery Tester: The plugin detail page (
/plugins/detail?slug=oidc-auth) includes an interactive validation tool to test discovery endpoints and display available token claims in real time. - Security & Token Exchange: Enforces cryptographically random
stateandnonceparameters against Cross-Site Request Forgery (CSRF) and replay attacks. Client secrets are encrypted at rest using AiPBX'sSecretBox.
Configuration
| Setting Key | Description | Example / Default |
|---|---|---|
issuer_url | OpenID Provider base URL or discovery endpoint | https://auth.company.com/realms/corp |
client_id | OAuth 2.0 Client ID assigned by your provider | aipbx-client |
client_secret | OAuth 2.0 Client Secret (encrypted at rest) | •••••••• |
redirect_uri | Callback URL registered in your identity provider | https://pbx.company.com/auth/oidc/callback |
scopes | OAuth scopes to request | openid profile email |
default_role | Fallback role for newly provisioned users | user (admin, cc_manager, cc_agent) |
role_claim_path | Token claim path used to resolve roles | roles or groups |
allowed_domains | Comma-separated email domain allowlist | company.com, subsidiaries.com |
2. SAML 2.0 Web Browser SSO Plugin (saml-auth)
The SAML plugin operates as an enterprise Service Provider (SP), receiving and validating SAML 2.0 Assertions sent via HTTP-POST binding.
Key Features
- SP Metadata Endpoint: AiPBX publishes standard SAML EntityDescriptor XML at
https://<server>/auth/saml/metadata. - Assertion Consumer Service (ACS): Inbound assertion reception at
https://<server>/auth/saml/acs. - One-Click IdP Metadata XML Importer: Administrators can paste or upload the federation metadata XML exported from Microsoft Entra ID, Okta, Keycloak, or ADFS. The parser extracts Entity ID, SingleSignOnService URL, and X.509 public signing certificates automatically.
- Cryptographic XML-DSig Verification: Validates SHA-256 and SHA-1 digital signatures using the IdP's public certificate, canonicalizing enveloped XML elements (
C14N). - Replay & Temporal Integrity: Validates assertion conditions, audience restrictions, destination endpoints, and
NotBefore/NotOnOrAftertimestamps with a 120-second clock skew tolerance.
Configuration
| Setting Key | Description | Example / Default |
|---|---|---|
sp_entity_id | Unique Service Provider Entity ID (defaults to server URL) | https://pbx.company.com |
idp_entity_id | Issuer / Entity ID of the Identity Provider | https://sts.windows.net/{tenant-id}/ |
idp_sso_url | IdP SingleSignOnService HTTP-POST endpoint | https://login.microsoftonline.com/.../saml2 |
idp_x509_cert | X.509 Public Certificate of the IdP (PEM format) | -----BEGIN CERTIFICATE-----... |
nameid_format | SAML NameID Policy Format | emailAddress (persistent, transient) |
default_role | Default system role assigned to new users | user |
role_attribute | SAML attribute name mapping to AiPBX roles | http://schemas.microsoft.com/ws/2008/06/identity/claims/role |
allowed_domains | Email domain restrictions | company.com |
Start the sign-in from the AiPBX login page. A SAML response must answer a request started in the same browser and is accepted once, so a sign-in started from the Identity Provider's own portal (IdP-initiated) is refused. Assertions must carry a bearer subject confirmation and an audience restriction, as the SAML Web Browser SSO profile requires.
Just-In-Time (JIT) Auto-Provisioning & Role Mapping
When a user signs in through corporate SSO for the first time:
- Identity Extraction: Username and email are extracted from identity claims (
preferred_username,email, or SAMLNameID). - Domain Verification: If
allowed_domainsis configured, only matching corporate email domains are accepted. - Collision Avoidance: If a matching username or email already exists in
sys_users, the account is securely linked; otherwise a new user row is created with a strong random password hash. - Role Assignment: If a role claim is present in the token or assertion, it is mapped to system roles (
admin,cc_manager,cc_agent,user). If no mapping matches, it falls back to the configureddefault_role.
Mobile Client Deep-Linking
The Android and iOS apps support corporate SSO out of the box. Clicking the SSO login button on a mobile client opens the organization's authentication portal in a secure web tab. Upon successful authentication, AiPBX issues a single-use authorization code and redirects back to the mobile app via deep-linking:
aipbx://auth?success=1&code=<auth_token>
The mobile application exchanges the code for a local session token, enabling corporate login without storing passwords on the mobile device.
Security & Best Practices
- Keep Certificates Current: IdP signing certificates typically expire every 1–3 years. When updating certificates in Microsoft Entra ID or Okta, update the certificate in AiPBX before the old certificate expires to prevent sign-in interruptions.
- Restricting Access by Group: For strict access control, assign the AiPBX enterprise application only to designated groups within your corporate IdP directory.
- Audit Logging: Every successful and failed SSO attempt is recorded in the security audit log (
sys_audit_log) with client IP address, User-Agent, and detailed diagnostic error messages.
Sign In Only Through the Identity Provider
Under Security → Sign-in → Sign in only through the identity provider, choose SAML or OpenID Connect. Then local passwords, passkeys, Google sign-in and the password reset stop working for signing in, and the sign-in page goes straight to the provider.
- You cannot turn it on by mistake. It can only be turned on from a session that really signed in through that provider.
- If the provider is switched off or its plugin disabled, local sign-in comes back by itself.
- API keys, SIP phones and softphones are not affected: they do not sign in with a portal password.
- The mobile apps' user name and password sign-in stops working. Users can still add the app with the QR code on My Phone after signing in on the web.
Single Logout
By default, signing out of AiPBX ends the AiPBX session only. To end the session at the identity provider too:
- SAML: enter the provider's Single Logout URL in the plugin. The SP metadata then lists
/auth/saml/sls. The request is not signed, as AiPBX has no signing key, so a provider that requires signed logout requests refuses it. Tested against SimpleSAMLphp. - OpenID Connect: turn on Single Logout in the plugin. It uses the
end_session_endpointof the provider's discovery document, and you register/loginthere as a post-logout address. Not tested against a real provider.
If the identity provider is down
On the server, as root:
sudo php /opt/aipbx/web/bin/aipbx_sso_recovery.php
It prints a link that works once, within 15 minutes. It allows an administrator's password, and only that, for ten minutes in that browser. Two-factor authentication still applies, and the link's creation and use go in the audit log.
To allow local sign-in again for everyone:
sudo php /opt/aipbx/web/bin/aipbx_sso_recovery.php --off
Which providers have been tried
SAML was tested against SimpleSAMLphp. Microsoft Entra, Okta and others have not been tried yet, so reports are welcome.