Vonage Business Cloud AU Support

Vonage Business Communications Support

Enter a search topic
Vonage Support

Single Sign-On for Vonage Business Communications

Updated: 4/19/2024 3:39 AM

Single Sign-On (SSO) is an authentication method that allows users to log in with a single user name and password to several systems. Single Sign-On support for VBC allows you to use a single username and password across other single sign-on enabled apps and VBC. Once an account is configured for SSO, users log in using the Log in with Single Sign-On button on the Vonage account login page. 

  • SSO is a free service
  • SSO uses a common standard (SAML 2.0) and supports the following Identity Providers (IDP):
     
    • Okta
    • Azure AD 
    • OneLogin
    • Google Workspace

      NOTE: Vonage is not an IDP and you must have a membership with a third-party IDP
  • SAML 2.0 is a protocol for web browser SSO using secure tokens; SAML uses standard cryptography and digital signatures to pass a secure sign-in token from an IDP to a SaaS application. 
Set Up Azure Active Directory SSO

Azure Active Directory (Azure AD) is Microsoft's cloud-based identity and access management service, which helps your employees sign in and access resources. Azure Active Directory enables single sign-on access to cloud applications (like Vonage Business Communications).

Once a user signs into Azure Active Directory, they can then launch any of their enabled web apps without re-entering their login credentials for each app. Azure Active Directory establishes a secure connection with the user’s browser. It then authenticates the user to login to Azure Active Directory managed apps via SAML, a pre-integrated, federated authentication protocol. The following is required for Azure SSO:

  • A Microsoft Azure account is required to configure Single Sign-on using Azure AD.
  • Vonage Business Communications usernames are required to match the NameID of the corresponding user account in Azure AD, which is typically the email address of the user. If your Vonage Business Communications usernames are not email addresses or do not match across platforms, it is recommended that they are updated prior to setup to avoid errors.
Step 1: Add Vonage Application
  1. Sign in to the Azure Active Directory portal using your Microsoft identity platform administrator account.
  2. Select Enterprise Applications > New application.
  3. Go to Search Application and search for Vonage. 
  4. Click the Vonage application.
  5. Rename the application, if desired, and then click the Create button; the Application Overview page opens.
Step 2: Edit the Azure AD SAML Configuration

To edit the basic SAML configuration options:

  1. Go to the Basic SAML Configuration section and select Edit (pencil icon).
  2. Copy the values from your Vonage Business Communications Service Provider Settings on the VBC Single Sign-on Settings page into your enterprise application.
     
    VBC SettingAzure AD Setting
    Entity IDIdentifier (Entity ID)
    Replace existing value.
    Sign-in URL (Default)Reply URL (Default)
    Sign-in URL (Secondary)Reply URL (Secondary)
    Sign-out URLLogout URL
  3. Update the following settings:
     
    Azure AD SettingValue
    Relay State0
  4. Click Save.
screenshot of SAML configuration
Step 3: Set up Vonage Business Communications to use Azure AD

The Set up <applicationName> section lists the values that need to be configured so that Vonage Business Cloud uses Azure AD as a SAML identity provider.

  1. Go to Application Overview page, click the Set up single sign on tile.
  2. Select SAML; the Setup Single Sign-On with SAML page appears.
  3. Go to SAML Signing Certificate section, then go to Certificate (Base64) and click Download link.
  4. Save the certificate for when you set up Vonage to use Azure AD.
  5. Go to Set up <applicationName>  section.
  6. Open the Vonage Business Communications Single Sign-on Settings page in a separate browser window.
  7. Copy the values from Azure AD into your Vonage Business Communications Single Sign-on Settings:
     
    Azure AD SettingVBC Setting
    Login URLSign-in page URL
    Azure AD IdentifierEntity ID
    Logout URLSign-out page URL
  8. Go to Upload Certificate field and upload your X509 certificate.
  9. Click Save.
  10. Go to Phone System > Users.
  11. Click Bulk Edit and select all users or a subset of users you wish to enable for SSO.
  12. Click Enable for SSO icon on the right upper corner.
Step 4: Configure User attributes (optional)

This step is only required for advanced configurations. When a user authenticates to the application, Azure AD issues the application a SAML token with information (or claims) about the user that uniquely identifies them. By default, this information includes the user's username, email address, first name, and last name. You might need to customize these claims if, for example, the application requires specific claim values or a Name format other than username.

  1. Go to User Attributes and Claims section, select the Edit (pencil icon).
  2. Verify the Name Identifier Value; the default value is user.principalname.
     
    • The user identifier uniquely identifies each user within the application.
    • For example, if the email address is both the username and the unique identifier, set the value to user.mail.
  3. Modify the Name Identifier Value by selecting Edit (pencil icon) for the Name Identifier Value field.
  4. Make the applicable changes to the identifier format and source.
  5. Click Save; the new claim appears in the table.
Step 5:Add user assignments

If User assignment required was selected when creating your enterprise application, you must add users to your application so they can sign in.

  1. Go to Users and Groups and click Add user.
  2. Go to Add Assignment pane and select Users and groups.
  3. Select the user or group you want to assign to the application or start typing the name of the user or group in the search box. You can choose multiple users and groups, and your selections appear under Selected items.
  4. When finished, click Select.
  5. Go to Users and groups pane, select one or more users or groups from the list, and then click Select at the bottom of the pane.

Now that you have configured Vonage Business Communications to use Azure AD, your end users are ready to use Single Sign-on.

You can start using Single Sign-on from any Vonage Business Communications login page. Get started by clicking Login with Single Sign-on on the login page.

Set Up Google Workspace SSO
Step 1: Add Application
  1. Log into Google Workspace Account.
  2. Go to Settings (6 dots on the top right) and select the Admin app; the Google Workspace Admin Console page displays. NOTE: You must have a business Google Workspace account to have access to the Admin app. 
  3. Go to the left navigation menu and go to Apps > Web and Mobile Apps; the Web and Mobile apps page displays.
  4. Click Add App dropdown on the top of the page and select Add Custom SAML app; the App Details page displays.
  5. Enter the name of the app as Vonage SAML or the desired name.
  6. Add the Vonage logo as the App icon (optional). Vonage logo 
  7. Click Continue and the Google Identity Provider Settings page displays.
Step 2: Add Google Workspace Settings to Vonage
  1. Open the Vonage Admin Portal in a separate browser tab.
  2. Go to Account and then SSO Settings.
  3. Refer to Option 2 on the Google Identity Provider Settings page and copy the values from Google Workspace into the SSO Settings page in Admin Portal as follows: 
     
    Google Workspace SettingVonage Setting
    SSO URLSign-in Url
    Entity IDEntity ID
    n/aSign-out Url
  4. Go to Identity Provider Settings and click Download Certificate.
  5. Go to the Vonage Admin Portal SSO Settings page and upload the certificate you just downloaded using Upload Certificate. 
  6. Click Save.
     
Step 3: Add Vonage Settings to Google
  1. Go to the Google Identity Provider Settings page and click Continue; the Service Provider Details page displays.
  2. Go to the Vonage Admin Portal SSO Settings page, click View Settings, and copy the values from the SSO Settings page in Admin Portal into Google Workspace as follows: 
     
    Vonage SettingGoogle Workspace Setting
    Entity IDEntity ID
    Sign in URL (default)ACS URL
    Sign in URL (secondary)Start URL
  3. Click Continue on the Google Workspace page. 
  4. On the next page displayed, click Finish. 
Step 4: Enable Users for SSO
  1. In Google Workspace, go to Admin > Apps > Web and Mobile Apps, then click on the application you just created.
  2. Go to the User Access section, click the down arrow. 
  3. Update the Service Status to On for Everyone or indicate specific uses or groups that require SSO access to Vonage.
  4. Go to the Vonage Admin Portal and then Phone System > Users page.
  5. Click Bulk Edit and select all users or a subset of users you wish to enable for SSO.
  6. Click Enable for SSO icon on the right upper corner.
Set Up Okta SSO

Okta is a cloud-based identity and access management service that helps your employees sign in and access resources. Okta enables single sign-on access to cloud applications (like Vonage Business Communications). 

Once a user signs into Okta, they can then launch any of their enabled web apps without re-entering their login credentials for each app. Okta establishes a secure connection with the user’s browser and then authenticates the user to login to Okta managed apps via SAML, a pre-integrated, federated authentication protocol. The following is required for Okta SSO:

  • An Okta account is required to configure Single Sign-on using Okta.
  • Usernames are required to match the NameID of the corresponding user account in Okta, which is typically the email address of the user. If your Vonage Business Communications usernames are not email addresses it is recommended that they are updated prior to setup to avoid errors.
Preparation (for Existing Customers)

These steps apply for existing customers only, new customers go through this process before going live with with their Vonage account.

  1. Identify the timeframe to perform the change.
  2. Notify the users of the maintenance window. 
  3. Notify Vonage Platinum Support and Advanced Ops teams of the maintenance window. 
  4. Ensure VBC usernames match Okta usernames, proceed with user clean up in Okta if needed.
  5. Identify test users for SSO.

    NOTE: If you need to reset the previous configuration using Reset SSO Settings, all users are disabled for SSO and you are required to reenable SSO using Bulk/Edit feature on the Users page of the Vonage Admin Portal. It can be helpful to export the users before resetting, to capture any of the users disabled for SSO as exceptions.
Adding App
  1. Sign in to your Okta portal.
  2. Go to Applications and then click Browse App Catalog.
  3. Type Vonage in the search field and select the Vonage app; do not select the Vonage Business app.
  4. Click Add;  the General Settings page displays.
  5. Update the General Settings or name (if applicable), and then click Next; the Sign-On Options page displays.
Set Up SSO for Vonage App
  1. Keep Okta portal browser tab open on the Sign-On Options page and in a separate tab, open the Vonage Business Communications Single Sign-on Settings page as an Account Super User or Account Administrator.
  2. Determine if existing SSO settings need to be removed:
    • To remove the previous settings, click Reset All Settings, then click Yes to confirm the reset. 

      NOTE: If you need to reset the previous configuration using Reset SSO Settings, all users are disabled for SSO and you are required to reenable SSO using Bulk/Edit feature on the Users page of the Vonage Admin Portal. It can be helpful to export the users before resetting, to capture any of the users disabled for SSO as exceptions.
    • Skip this step, if SSO settings are blank.
  3. Under Configure your Identify Provider (IDP) section, click View Settings:
     
    1. Go to the Sign-in URL field and copy the Customer ID value, which is part of this URL. Copy right after "ID=" and before "&". 
    2. Click Download Public Certificate. 
  4. Go to Okta browser tab, and on the Sign-On Options page: 
     
    1. Go to Advanced Sign-on Settings and paste the copied value into the Customer ID field.
    2. Enable the checkbox for Enable Single Logout. Once this section is expanded, upload the Vonage certificate you just downloaded into the Signature Certificate field in Okta.
  5. Click the View Setup Instructions button in Okta, the details open in a separate browser tab:
     
    1. Copy the values below and paste into appropriate fields under Configure Vonage for the SSO section in Admin Portal.
       
      OktaVonage
      Entity IDEntity ID
      Sign-in URLSign-in URL
      Sign-out URLSign-Out URL
    2. Click on the link to download and save the certificate.
    3. Go to Vonage Admin Portal SSO Settings and then upload the certificate using the Upload Certificate field. 
  6. Enable the toggle Enable Single Sign-On for this account.
  7. Click Save in Admin Portal.
  8. Go to Okta tab and click Done.
  9. Assign Users and Groups to the new Vonage App in Okta.
  10. Enable users for SSO in Admin Portal:
     
    1. Go to Admin Portal > Phone System > Users. 
    2. Go to Bulk/Edit, then select users that need to be enabled for SSO.
    3. Click the Enable SSO for Users icon on the top of the page.
       
  11. Perform a test to ensure users on the account can access the application using SSO.
Set up SCIM for Vonage App
  1. These steps apply for existing customers only, new customers go through this process before going live with with their Vonage account:
     
    1. Identify the timeframe to perform the change.
    2. Notify the users and Vonage Support teams of the maintenance window. 
    3. Identify test users for SCIM.
  2. Ensure VBC usernames match IAA Okta, proceed with user clean up in Okta if needed.

    NOTE: If the same user has different usernames in Okta and VBC, it results in creating a new user in the Vonage account. 
  3. Review the Vonage requirements for usernames, first names, and last names to provision properly. These must be followed or the sync is not performed:
     
    • Usernames must be between 6 and 50 characters
    • Usernames only contain letters, numbers, or the following characters:
       
      • Colon
      • Parentheses
      • Underscore
      • @ sign
      • Dash
      • Comma
      • Period
    • First/Last name not more than 45 characters.
    • First/Last name only contains letters, numbers, or the following characters:
       
      • Colon
      • Parentheses
      • Dash
      • Comma
      • Period
      • Apostrophe
  4. Log in to the Vonage Admin Portal and create a user dedicated to SCIM Integration.

    NOTES:
     
    • It is best practice if the SCIM user is the Account Super User, otherwise use Account Admin user type.
    • To sync the users, the SCIM Integration user must have higher permissions than the user being synced. For example, a SCIM integration user with an Account Admin user type does not allow for syncing changes for Account Super Users.
    • This user is required for setting up SCIM on the IDP side.
    • If the password or username is changed, SCIM re-authorization is required.
  5. Go to Account > User Provisioning and enable Configure Vonage for SCIM toggle; Only Account Admins and Super Users can enable User Provisioning Settings for the account.
  6. Indicate if you want to create users manually in Admin Portal, outside of SCIM.
  7. Go to Okta > Provisioning Tab, click Configure API Integration, and click Enable API integration checkbox.
  8. Click Authenticate with Vonage which opens a VBC log-in screen, enter the SCIM Provisioning User Credentials (this is the user you created in step 6), and then click Save. The Okta to Vonage page opens in the Okta portal.
  9. Click Edit and then select Create Users, Update User Attributes, Deactivate Users checkboxes as applicable. Once the specific actions are selected, the provisioning sync is applied to the actions.
  10. Click Save.
  11. Click Assignments/Provision User in Okta.
     
Set Up OneLogin SSO
Troubleshoot SSO
If Issue Is...Then...
(All IDPs) User logs in and gets an error: Authentication Error: We are experiencing technical difficulties: please try again later.
Impacts all users on the account.		Verify the settings are entered into IDP and Vonage according to the instructions for your specific IDP.  This requires comparing the values in IDP and Vonage. Vonage does not have access to your IDP portal.

NOTES:
  • The entire URLs must be copied. Even one character missing breaks the integration.
  • Azure Only: If you are changing Vonage Settings in your IDP, you must reupload the Azure certificate into VBC.
  • Azure Only: In addition to following the instructions, verify that the Sign-on URL field under the Basic SAML Configuration section is blank in the Azure Portal.
(All IDPs) User logs in and gets an error: Authentication Error: We are experiencing technical difficulties: please try again later.
Impacts one specific user on the account.		Verify the username is a match in IDP and VBC.
(All IDPs) User logs in and gets an error: This username may be incorrect. Make sure you typed it correctly. Otherwise, contact your admin.Verify the username is a match in IDP and VBC.
(Azure only) User logs in and gets an error: SAML authentication request's RequestedAuthenticationContext Comparison value must be 'exact'. Received value: 'Minimum'The error is related to a custom configuration setting from Azure. To resolve this issue, contact Vonage Support.

If these steps do not correct the issue, or if the issue is not detailed here, Contact Us to escalate the issue. Recommended template:

  • Screenshots from the IDP with Vonage entered and IDP settings; you must provide these screenshots, as Vonage does not have access to this.
  • Document the steps to reproduce the issue and the actual error displayed. For example, does the error display when the user clicks on a single sign-on link from the login page.
  • Perform a SAML Trace:
     
    1. Download and add the SAML-tracer tool:
       
    2. Open SAML-tracer by clicking the small orange button in the top-right corner.
    3. Navigate to Admin Portal or Desktop App website and duplicate the issue.
    4. Identify SAML entries by the orange SAML label.
    5. Export the entire SAML trace using None as the cookie-filter profile.
Modify User Names with Profile Mappings
Modify Azure User Names
  1. Sign in to the Azure portal as a cloud application admin, or an application admin for your Azure AD tenant.
  2. Go to Azure Active Directory > Enterprise applications and select the application from the list; to search for the application:
    1. Go to the Application Type menu, select All applications, and then select Apply.
    2. Enter the name of the application in the search box, and then select the applicable application from the results.
  3. Go to the Manage section, select Single Sign-On, and then select SAML. The Setup Single Sign-On with SAML page appears.
  4. Scroll down to the User Attributes & Claims section and select Edit.
  5. Select a claim to modify; to modify the username select the Unique User Identifier (Name ID) claim; the Manage Claim screen opens.
  6. Change the source to Transformation; this opens the Manage transformation section on the right side of the screen.
  7. Go to the Parameter dropdown and select the parameter to use for the claim. 
  8. Go to the Transformation dropdown and select the transformation to apply; for example, to change a username from lower case to upper case:
    1. Go to Parameter and select user.userprincipalname.
    2. Go to Transformation and select ToLowercase().
  9. Click Add and repeat steps 7 and 8 for multiple transformations, if applicable.  NOTE: Additional transformations apply to the output from the previous transformation.
  10. Click Add to apply the transformation.
  11. Click Save to save changes to the claim.
Modify Okta User NamesIn the Okta portal:
  1. Go to Applications and then Sign-On.
  2. Go to Settings and then click Configure profile mapping; this takes you directly to the profile mapping for the current application.
  3. Select Okta to <application name>; select the applicable application name for Vonage.
  4. Select Override with mapping to open a text box that allows you to enter an attribute, or enter an expression to modify an attribute.
  5. Enter an expression to update the user name; as an example to change a username from lower case to upper case:
     
    • Enter String.toUpperCase(user.login) in the text box. 
    • There are two components to this formula:
       
      • The function: String.toUpperCase(value)
      • The value: user.login
    • This expression uses the String.toUpperCase(value) function to change the user.login value to change the user name to upper case.
    • A complete selection of values and expressions is available here: Okta Expression Language Overview
  6. Select the applicable direction the change should be applied in the dropdown next to the expression box.
  7. Click Apply mapping user create and update.

Did this article answer your question?