Configuring the Ooma / Auth0 SSO Integration

Modified on Fri, 01 Dec 2023 at 04:16 PM

Description: The purpose of this article is to guide you through the process of configuring the Ooma / Auth0 SSO integration.

This user guide provided below assumes that you meet certain prerequisites: you should be familiar with the Ooma Enterprise interface and have an Auth0 account.

To simplify the integration process, which involves navigating between two applications and performing specific actions, the following steps will be provided. Each step will be performed within a specific app, allowing for a clearer and more manageable process.

Step 1

To initiate the configuration process for SSO integration, you need to access two specific pages. You can organize them as two neighboring tabs in your web browser.

Firstly, open the "IdP and SSO" tab on your company account page in the Phone System App of the Ooma Admin Portal.

Secondly, open the Home page of your Auth0 account.

Step 2

In this step, you will begin the configuration process in Ooma Enterprise. Go to the Ooma Admin Portal page in your web browser and press the "Set Up Identity Provider" button.

This dialog form will appear.

Enter the random URL address into the SSO URL field on this form.

There are two circular dependency issues when setting up an IdP in the Ooma Admin Portal and completing the configuration of the SP. 
1. An X.509 certificate is required, but Auth0 generates this certificate only after the SP configuration is finalized. 
2. An SSO URL is required, but Auth0 generates this URL address only after the SP configuration is finalized.

However, there is a trick to overcome these issues: You can enter a random SSO URL address and create a "placeholder" X.509 certificate, which will enable you to finalize the SP configuration and input the SP's data into Auth0. This will generate a real SSO URL and X.509 certificate that can then be uploaded to the IdP configuration in the Ooma Admin Portal.

You have the flexibility to choose the method for creating the "placeholder" X.509 certificate. Here are a few examples of how to do it: 
1. Use the console to generate the certificate via OpenSSL (link). 
2. Use any suitable online tool (link)

Then, press the "Upload File" button and upload the "placeholder" X.509 certificate.

Step 3

Find the "Unique ID Claim" field on this dialog form.

This value should be entered into this field:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier

Step 4

Find the "Email Claim" field on this dialog form.

This value should be entered into this field:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

After finishing the given actions, make sure to click the "Save" button to save the changes you have made.

After that, the interface of the "IdP and SSO" tab of the Ooma Admin Portal will be updated accordingly.

Step 5

On the updated "IdP and SSO" tab of the Ooma Admin Portal, you will require two URLs: Callback URL (ACS) and Issuer.

Prepare to copy these URLs to the clipboard and paste them in the following steps of this guide.

Step 6

Go to the Auth0 page in your web browser and navigate to the Application tab in the left menu of the system.

Step 7

Once you click on the Application tab, it will expand to display a nested menu. From the menu, choose the "Applications" option. This action will open a new page in the main area of the application. Next, locate the "+Create Application" button that has now become visible and press it.

Following that, a pop-up window will appear, prompting you to set the name for the application. In this window, you will also be provided with a variety of application types to choose from for the new app. From this list, select the option labeled "Native" and then press the "Create" button.

Step 8

Navigate to the recently created application.

Scroll down to the section labeled "Advanced Settings," and download the X.509 certificate by clicking on the "Download Certificate" button. On the resulting dropdown menu, choose the option labeled "PEM"

Step 9

Next, return to the top of the page and access the Addon tab.

Once the tab is open, enable the SAML2 feature by toggling the switch.

Following that, a fresh pop-up window will emerge. In this window, navigate to the Settings tab.

Locate the Application Callback URL field and populate it with the Callback URL (ACS) obtained from the recently updated "IdP and SSO" tab in the Ooma Admin Portal. To do so, please return to the browser tab containing the Ooma Admin Portal, copy the URL, and then paste it into the designated field.

Additionally, there is a section for inserting code below, ensure that you place the provided code into that specific section.

{

"audience": " ",

"mappings": {

"user_id": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",

"email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",

"name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",

"given_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",

"family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",

"upn": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",

"groups": "http://schemas.xmlsoap.org/claims/Group"

"includeAttributeNameFormat": true,

"nameIdentifierFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent ",

"nameIdentifierProbes": [

"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",

"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",

"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"

]

}

The code includes a highlighted yellow section on the "Audience" line, which must be filled out, while the remaining fields are optional and should be set based on the user's specific integration case. In this section, you are required to input the Issuer URL. You can find the Issuer URL on the updated "IdP and SSO" tab of the Ooma Admin Portal. To do so, please navigate back to the browser tab containing the Ooma Admin Portal, copy the URL, and then paste it into the designated field within the Audience line.

After finishing the given actions, make sure to click the "Save" button to save the changes you have made.

Step 10

Now, proceed to the Settings tab and copy the Identity Provider Login URL to the clipboard. You will require this URL to re-configure the SSO parameters for the SP.

Step 11

Go to the updated "IdP and SSO" tab of the Ooma Admin Portal and press the "Edit Identity Provider Information" button.

In the opened dialog form, replace the SSO URL address in the top field with the correct one you can find on the Auth0 page:

Step 12

Then, delete the existing "placeholder" X.509 certificate by clicking on the Trash Bin badge next to it. Then, upload the correct certificate by clicking the "Upload File" button once it becomes active again.

After finishing the given actions, make sure to click the "Save" button to save the changes you have made.

Step 13

On the updated "IdP and SSO" tab of the Ooma Admin Portal, toggle the "Enable" switch in order to activate the SSO integration between the Ooma (SP) and Azure AD (IdP).

From this point onwards, the SSO integration is considered complete and expected to function properly.

It is important to note that this user guide does not cover troubleshooting steps. If you require further assistance with this matter, please contact our customer support team.