PBX GUI - Okta SSO Setup for FreePBX/PBXact

Table of Contents

1 Step-1 : Configure the Application in Okta
2 Step-2 : Configure Single Sign-On
3 Step-3 : Assign Users and Groups
4 Step-4 : Retrieve and Apply Okta SAML Details to PBX
- 4.1 Steps to Save Okta Metadata XML

Please find steps below to setup SAML Single Sign-On with Okta.

Step-1 : Configure the Application in Okta

Log in to the Okta Admin Console
Navigate to Applications in the left sidebar.
Click Create App Integration.
Select SAML 2.0 as the sign-in method, then click Next.
Enter an app name and optionally add an app logo( logo optional).

Step-2 : Configure Single Sign-On

Fill in the following SAML configuration fields:

If your PBX web interface is configured to use a non-standard HTTPS port, you must include that port number in each ACS URL

Single sign on URL: The Assertion Consumer Service (ACS) URL provided by your service provider (the application).
This is where Okta will send the SAML authentication response. Below are the URL formats that need to be added as Reply URLs.
1. Admin panel - https://<your_pbx_ip_or_domain>/admin/ajax.php?module=pbxsaml&command=checkSAMLAdmin
2. User control panel - https://<your_pbx_ip_or_domain>/admin/ajax.php?module=pbxsaml&command=checkSAMLUCP
3. Sangoma Client Desktop - https://<your_pbx_ip_or_domain>/admin/ajax.php?module=pbxsaml&command=checkSAMLSCD
Audience URI (SP Entity ID): Unique identifier for your application, also provided by the SP.
Default RelayState: (optional, based on your app’s requirements).
Additional settings: (optional) Leave other options as required by the service provider (e.g., Name ID format, attribute statements, or advanced settings).
Scroll down to the bottom of the form and click Next.
You can skip the the feedback form in last step by clicking Finish button.
The app integration will now appear in your Okta dashboard.

Step-3 : Assign Users and Groups

Switch to the Assignments tab.
Click Assign and choose to assign users or groups who should access the application.
Select and assign users/groups as needed, then click Done.

Step-4 : Retrieve and Apply Okta SAML Details to PBX

There are two ways to retrieve and use the SAML configuration values for your integration with Okta:

Download the metadata file from Okta and upload it into PBX. The metadata file is in XML format and contains all necessary SAML settings (like SSO URL, Entity ID, and certificates). PBX can automatically parse this file and populate the needed configuration fields, making the setup easier and reducing room for manual errors.

There is no direct download option to obtain the metadata file as an XML in Okta. Instead, Okta provides a metadata URL.

Steps to Save Okta Metadata XML

In the Okta Admin Console, locate the metadata URL provided for your SAML application.
Copy the metadata URL and open it in a new browser tab.
When the XML content loads in the browser, right-click anywhere on the page and select Save As or use the browser menu to choose File > Save Page As.
Enter a suitable filename ending with ".xml" (for example, "okta_metadata.xml").
Save the file to your computer for use in your SAML integration.

Manually copy the required fields from Okta (such as the Identity Provider Single Sign-On URL, Issuer/Entity ID, and X.509 certificate) and enter them into PBX. This approach may be necessary if PBX does not support metadata file uploading, or if you want more control over which details are entered.

To copy the certificate download signing Certificate and copy the content in the file or copy it from the metadata file.

Okta does not support adding multiple Assertion Consumer Service (ACS) URLs within a single SAML application. Therefore, separate applications need to be created in Okta for each of the following: Admin Control Panel (ACP), User Control Panel (UCP), and Sangoma Client Desktop. For each application, follow the same steps to create and configure the SAML app, ensuring that you use distinct and appropriate names and specify the correct ACS URL for each respective application.