AiPBX
Features Install Videos Mobile Docs Live demo Contact Sponsor on GitHub UpCloud ($250 Free Credit) YouTube GitHub
ODOO Connect AiPBX with Odoo CRM & ERP — manage calls & customers in one place. Try Odoo Free →
Home / Documentation / Corporate Single Sign-On: OpenID Connect (OIDC) & SAML 2.0 (Plugins)

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:

  1. OpenID Connect (oidc-auth): Standard OAuth 2.0 / OIDC Core 1.0 authentication profile.
  2. 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 state and nonce parameters against Cross-Site Request Forgery (CSRF) and replay attacks. Client secrets are encrypted at rest using AiPBX's SecretBox.

Configuration

Setting KeyDescriptionExample / Default
issuer_urlOpenID Provider base URL or discovery endpointhttps://auth.company.com/realms/corp
client_idOAuth 2.0 Client ID assigned by your provideraipbx-client
client_secretOAuth 2.0 Client Secret (encrypted at rest)••••••••
redirect_uriCallback URL registered in your identity providerhttps://pbx.company.com/auth/oidc/callback
scopesOAuth scopes to requestopenid profile email
default_roleFallback role for newly provisioned usersuser (admin, cc_manager, cc_agent)
role_claim_pathToken claim path used to resolve rolesroles or groups
allowed_domainsComma-separated email domain allowlistcompany.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 / NotOnOrAfter timestamps with a 120-second clock skew tolerance.

Configuration

Setting KeyDescriptionExample / Default
sp_entity_idUnique Service Provider Entity ID (defaults to server URL)https://pbx.company.com
idp_entity_idIssuer / Entity ID of the Identity Providerhttps://sts.windows.net/{tenant-id}/
idp_sso_urlIdP SingleSignOnService HTTP-POST endpointhttps://login.microsoftonline.com/.../saml2
idp_x509_certX.509 Public Certificate of the IdP (PEM format)-----BEGIN CERTIFICATE-----...
nameid_formatSAML NameID Policy FormatemailAddress (persistent, transient)
default_roleDefault system role assigned to new usersuser
role_attributeSAML attribute name mapping to AiPBX roleshttp://schemas.microsoft.com/ws/2008/06/identity/claims/role
allowed_domainsEmail domain restrictionscompany.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:

  1. Identity Extraction: Username and email are extracted from identity claims (preferred_username, email, or SAML NameID).
  2. Domain Verification: If allowed_domains is configured, only matching corporate email domains are accepted.
  3. 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.
  4. 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 configured default_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_endpoint of the provider's discovery document, and you register /login there 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.

View or edit this page on GitHub

On This Page