/
PBX GUI - SAML

PBX GUI - SAML

The PBX SAML Module icon is a puzzle piece on a shield.
PBX SAML Module icon.
The traditional FreePBX admin login with an button option to sign in with Microsoft.
Example SAML login to FreePBX Administrator Control Panel with Microsoft as Identity Provider.

 

Introduction

SAML (Security Assertion Markup Language) is a standard for enabling secure Single Sign-On (SSO) across different applications.

The PBX SAML module provides SSO capabilities for FreePBX/PBXact Administrator Control Panel (ACP - often referred to as “Admin”) and associated user applications such as the User Control Panel (UCP) and the Sangoma Phone Desktop Client. It allows users to authenticate using the same email address and credentials managed by an Identity Provider (IdP), such as Azure Active Directory (Azure AD), Google or OKTA.

With SAML SSO enabled, if a user is already logged into an IdP connected application in their browser, they will be automatically logged into FreePBX or PBXact without needing to re-enter credentials. If not, they will be redirected to the configured Identity Provider’s login page. Once authenticated, they are seamlessly redirected back to the PBX system.

This integration simplifies the login experience, enhances security, and ensures centralized identity management.

The PBXSAML module currently supports the following IdP backends for SAML SSO:

  1. Microsoft Azure Active Directory (Azure AD)

  2. Okta

  3. Google

Microsoft logo with red, green, blue and yellow squares making up a larger square, and the word Microsoft on the right.
OKTA logo is a white circle with black rectangles emanating from the perimeter in a sun ray fashion with lower case okta spelled out on the right side.
Google logo in blue, red, yellow and green letters that spell out Google.

PBX SAML Requirements

The PBX must use HTTPS with valid recognized certificates for SAML authentication to work properly.

Only one IdP can be configured at any given time on your PBX.

The email address of the PBX user must match the email address from the IdP.

There must not be multiple users with the same email address in User Manager.

PBX SAML Key Definitions 

Keys

Definition 

Identity Provider (IdP) 

The system that authenticates the user and provides identity information. Example: Azure AD. 

Service Provider (SP) 

The system (application/website) that the user wants to access. Example: FreePBX. 

SAML Assertion 

A secure, signed message from the IdP that contains information about the user, like their identity and attributes. 

SAML Request 

A message sent by the Service Provider to the Identity Provider, asking for authentication. 

SAML Response 

The Identity Provider’s reply to the SAML Request, usually carrying a SAML Assertion. 

Single Sign-On (SSO) 

A system where users can log in once and access multiple applications without re-entering credentials. 

Metadata 

Configuration information (in XML format) shared between the IdP and SP to establish trust (includes URLs, certificates, etc.). 

ACS URL (Assertion Consumer Service URL) 

The endpoint on the Service Provider where the IdP sends the SAML Response after authentication. 

Entity ID 

A unique name or identifier for an IdP or SP used to recognize each other. 

RelayState 

An optional parameter used to remember the page the user was trying to access before being redirected for login. 

How to install 

To utilize the "SAML" commercial module, a valid commercial module license is required for its proper functioning.

Please refer to How to purchase SAML to know more about how to purchase commercial license for PBX SAML module.

After installing any module, run fwconsole chown to reset file and directory ownership. This ensures that all permissions are correctly applied and the system operates reliably.

Installation via Module Admin Section

The Module Admin section in PBX provides a user-friendly interface for managing and installing modules. To install "Pbxsaml" using this method, follow these steps:

  1. Log in to your PBX administration panel.

    1. Open your web browser and access the PBX administration panel.

  2. Navigate to the "Admin" menu and select "Module Admin."

    1. Click on the "Admin" menu within the interface and choose "Module Admin."

  3. Locate and select the "Pbxsaml" module from the available modules list.

    1. You may need to update your module list by clicking “Check Online.”

    2. Scroll through the list of available modules and find "Pbxsaml."

  4. Click on the "Download and Install" button.

  5. Follow the on-screen prompts to complete the installation process.

    1. The system will guide you through the installation steps. Simply follow the prompts to finalize the installation.

  6. Once installed, the "Pbxsaml" module will be ready to use.

  7. You can access and configure the module's settings according to your requirements.

Installation via PBX CLI

The PBX Command Line Interface (CLI) allows for advanced management of the PBX system. To install "Pbxsaml" using the CLI, follow these steps:

  1. Access the command line interface of your PBX system, either through SSH or directly.

    1. Depending on your setup, connect to the PBX system's command line interface.

  2. Execute the command fwconsole ma downloadinstall pbxsaml.

    1. Use the command fwconsole ma downloadinstall pbxsaml to initiate the installation of the "Pbxsaml" module.

  3. Wait for the installation to complete, and the "Pbxsaml" module will be installed and ready to use.

 

By following either of these installation methods - GUI or CLI - you can set up the "Pbxsaml" commercial module in your PBX system and take advantage of its advanced features for transcribing audio files.

PBX SAML Configuration Wizard

This guide explains how to configure SAML authentication for the PBX system using the built-in wizard.

It supports integration with popular Identity Providers (IdPs) such as Microsoft Azure AD, Okta, and Google. Configuration can be completed through a guided wizard, either by uploading metadata or entering details manually.

Wizard Field Abbreviations

Each IdP implementation will require defining these fields to meet their unique requirements.

Field 

Abbreviation 

SP Entity ID 

Service Provider Entity ID (e.g. FreePBX)

IdP Entity ID 

Identity Provider Entity ID

IdP Certificate 

X.509 certificate 

ACS 

Assertion Consumer Service URL 

There are unique ACS for ACP, UCP and Sangoma Desktop Phone Client login.

SSO URL

Single Sign On Login URL 

SLO URL 

Single Logout URL 

Some Identity Providers (such as Google Workspace) may not support SAML Single Logout (SLO).
In such cases, use the same URL as the SSO URL for the SLO URL field to complete the setup.

Wizard Location

Navigate to Admin → PBX SAML module to open up the configuration wizard. The ACS URLs are required for configuring the IdP application. Use these URLs during the IdP app setup.

View of a step-by-step wizard, starting at Step 1 Choose Your Identity Provider, showing images for the three supported IdPs. ACS URL section shows the 3 URLs needed.
Opening up the configuration wizard will start at Step 1 “Choose IDP”.

 

Wizard Steps

Step 1: Choose Your Identity Provider (IdP) 

Select your organization’s IdP from the available options: 

  • Microsoft Azure AD 

  • Okta 

  • Google 

View of a step-by-step wizard, starting at Step 1 Choose Your Identity Provider, showing images for the three supported IdPs. This is the same as the previous image except the ACS URL section is collapsed.
Choose your IDP and click on Next button

 

Steps 2, 3 and 4: Configure SAML Settings 

This module currently supports SAML for:

  • PBX Admin UI (Admin)

  • User Control Panel UI (UCP)

  • Sangoma Phone Desktop Client (SPD)

We have to configure SAML for all three (3) endpoints. Therefore, this step is divided into three sub-steps for each IdP, corresponding to the different application modules: Admin, UCP, and Sangoma Phone Desktop Client. You can configure them either by uploading metadata that you previously download from your IdP, or by entering settings manually (alternative option).

Step 2 for Admin Application SAML Settings with sub-steps 1, 2, 3 labeled on the diagram to show which buttons to click. 1 is upload metadata XML button. 2 is upload and parse button. 3 is next button.
Follow the buttons 1-2-3 to upload the XML metadata that you previously downloaded from the IdP.

Microsoft Azure AD

Follow the Microsoft Azure SSO Setup for FreePBX/PBXact to configure application and download the metadata.

  • You only need one application in Azure AD. 

  • Download the single metadata XML file from Azure AD. 

  • Upload the same file for Admin, UCP, and Sangoma Phone Desktop Client modules. 

  • Click Upload & Parse to auto-fill the configuration fields. 

  • After file is uploaded, SP Entity ID need to be added manually and it must match the Application Name you used when creating the app in Azure.

 

Okta

Follow the Okta SSO Setup for FreePBX/PBXact to configure application and download the metadata.

  • You must create three separate applications in Okta:  

    • One for Admin 

    • One for UCP 

    • One for Sangoma Phone Desktop Client 

  • Download the metadata XML file for each application. 

  • Upload each file to its corresponding module in the wizard. 

  • After upload, the following fields will not auto-populate and must be entered manually:  

    • SP Entity ID → Must match the Application Name you used when creating the app in Okta. 

    • SLO URL → Copy the SLO url from IDP app and Enter the logout url . 

 

Google

Follow the Google SSO Setup for FreePBX/PBXact to configure application and download the metadata.

  • You must create three separate applications in Google Workspace:  

    • One for Admin 

    • One for UCP 

    • One for Sangoma Phone Desktop Client

  • Download the metadata XML file for each application. 

  • Upload each file to its respective module in the wizard. 

  • After upload, you must manually enter:  

    • SP Entity ID → Must be identical to the Application Name you assigned in Google. 

    • SLO URL → Copy the SLO URL from IDP app and Enter the logout URL (If not supported from IDP, you can use same as SLO URL to complete the setup). 

 

How to setup SAML Manual Configuration (Alternative Option) 

If metadata upload is not used, enter the following fields for each module (Admin, UCP, Sangoma Phone Desktop Client): 

Field Name

Example Value

Field Name

Example Value

SP Entity ID 

FreePBX-SAML

IdP Entity ID 

https://sts.windows.net/XXXXXX-XXXX-XXX-XXX-XXXXXXXXXXX/

SSO URL 

https://login.microsoftonline.com/XXXXXX-XXXX-XXX-XXX-XXXXXXXXXXX/saml2

SLO URL 

https://login.microsoftonline.com/XXXXXX-XXXX-XXX-XXX-XXXXXXXXXXX/saml2

IdP Certificate 

Paste the X.509 certificate provided by your IDP. 

image-20251118-043635.png

 

Click Next to proceed. 

Step 5: Review the Configuration 

This step provides a summary of the configured modules and allows you to review/edit SAML authentication. 

Configuration Summary 

  • Admin SAML: ✔️ Configured 

  • UCP SAML: ✔️ Configured 

  • SDC: ✔️ Configured 
    Once all app configuration are successful, then click Finish Configuration to complete the setup.

    Title is Step 5 Review Settings with Configuration Summary below that showing three rows - Admin, UCP, and SDC - and some checkboxes to indicate succesful setup, along with a pencil icon to edit and and eye icon to review. At the bottom are buttons labeled Previous and Finish Configuration.
    Review the SAML Configuration in Step 5.

Test SAML Configuration 

You can use the provided test buttons to validate SSO functionality at any time after initial installation: 

  • Test Admin SSO → Test the SSO for admin. 

  • Test UCP SSO → Test the SSO for User Control Panel. 

  • Test Sangoma Phone Desktop Client SSO → Test the login for Sangoma Phone Desktop Client. 

Testing SAML configuration example showing entry box for extension number and a big blue Test Admin Configuration button.
Testing individual user extensions.

Example Test

Test Admin IdP connection:

  1. Click on “Test Admin Configuration” button at the top.

  2. Then enter the SAML enabled user extension number.

  3. Then click “Test Admin Configuration” button at the bottom.

    1. A new pop-up should appear to enter IdP login credentials and complete the process.

    2. If connection is successful, you get the Test Successful message.

    3. The pop-up should automatically close.

Dark green Test Successful message on a lighter green background with note at the bottom in black text that the pop-up will close automatically.
Test Successful message pop-up shown during individual user extension testing.

  1. Once this pop-up is closed, you can check the test result by clicking “Check Result” button.

Testing screen shown post-test with yellow highlight around the Check Result button at the bottom of the page.
After user extension testing is complete, you can retrieve the results without having to re-run the test again.

 

  1. Once done with all three IdP connection tests, reload the SAML page and check the summary page. If required, you can edit / update the configured IdP settings by clicking the “Update SAML Settings” button. You can reset completely to reconfigure the SAML with a different IdP provider using the Reset button.

    Example successful test output with Microsoft logo at the top and several green check marks and fields for each of Admin, UCP and Sangoma Phone Desktop Client tests.
    Summary page showing successfully completed tests.

 

 

Enabling SAML for a user/user group

You can Enable SAML Login method for a specific user or a group of users.

Once SAML login is enabled for a user, it will apply to the Admin Control Panel (ACP), User Control Panel (UCP), and Sangoma Desktop Client (SDC).

Userman user email is mandatory for successful SAML login.

User Group Level

Enabling SAML at user group level:

  1. Navigate to Admin →

  2. User Management →

  3. Groups →

  4. Edit group →

  5. go to PBX SAML tab →

  6. set to yes to enable SAML for a user group.

Edit Group in the upper right, then a list of tabs, with PBX SAML tab selected. Enable SAML is set to Yes.
User Group Level with Enable SAML = Yes

User Level

Enabling SAML at user level:

  1. Navigate to Admin →

  2. User Management →

  3. Users →

  4. Edit User →

  5. go to PBX SAML tab →

  6. set to either:

    1. yes to enable SAML for a user, or,

    2. inherit to inherit setting from user group.

Edit User section of the ACP showing several tabs with PBX SAML tab opened. Enable SAML is set to Inherit.
User Level with Enable SAML = Inherit

Testing

After configuring wizard with selected IdP and FreePBX, logging into the Admin Panel, UCP, or Sangoma Phone Desktop Client will redirect you to the respective IdP login page. Upon successful authentication with them, you will be redirected back to the respective application, and login will be granted based on the verified IdP user details.

Once SAML is enabled for the users, the admin and UCP login screen will show the SSO button with respective configured IdP.

View SAML enabled users list

The View SAML Users List button displays a list of all users who have SAML authentication enabled in the system. This list helps administrators identify which users are actively using SAML for authentication

Same SAML testing page as shown previously, except the button to View SAML Users List has a green rectangle around it.
Click on View SAML Users list to view the list

The SAML Enabled Users page displays all users who currently have SAML authentication enabled in the system. This allows administrators to view and manage which PBX users are using SAML Single Sign-On.

Sample list of SAML users showing email addresses and username extension numbers.
Listing only SAML Enabled Users list

Note

  • This list only includes users with SAML enabled — regular (non-SAML) PBX users are not shown.

  • The number of users in this list directly affects your SAML license usage. (See https://sangoma.atlassian.net/wiki/spaces/FDT/pages/4913922049).

  • Disabling users here can help free up SAML licenses for new users.

  • Once a license is freed up, a manual submission is required at the User or Group level to enable SAML for a new user.

 

Example SAML User Experience with Microsoft IdP

Once SAML is configured and working properly, this is what you should see when you login.

Admin

Administrator Control Panel of the FreePBX GUI.

FreePBX Administrator Control Panel login screen with username and password fields then below that, showing a - or sign in with - option and below that a Microsoft logo at the bottom.
Administrator Control Panel example. Each IdP will show the appropriate logo. Remember that only one IdP can be active at a time on your PBX.

UCP

User Control Panel of the FreePBX GUI.

User Control Panel login screen showing username and password fields, then below that an option - or sign in with - then a button with the Microsoft logo.
User Control Panel example.

 

 

Return to Documentation Home | Sangoma Support