Configuring a SAML 2.0 Identity Provider with Bandwidth Single Sign-On Integration
Single Sign-On (SSO) is an authentication method that allows you to log in to multiple applications using just one set of credentials. Bandwidth supports the integration of many common identity providers as an additional layer of security and management on top of our existing user management system.
This guide describes how to configure a SAML 2.0 Identity Provider (IdP) with Bandwidth SSO to authenticate users to the Bandwidth App.
Prerequisites
You must have the following to configure an SSO Integration with Bandwidth:
- An IdP that supports SAML 2.0. If you don’t know whether your IdP supports SAML 2.0, contact your IT department for confirmation.
- Admin credentials for the Bandwidth App (only admins can access the SSO Integration page).
- Bandwidth App users whose usernames are in the email format.
- We do not support usernames that are not email addresses for SSO Integration.
- If you have users whose usernames are not email addresses, you must recreate those users for them to be able to use SSO.
Step 1: Create a Bandwidth SSO integration
- Log in to the Bandwidth App.
- In the side navigation bar, click Account and select Overview. This will take you to the Account Overview page.
- Under the Account Management section, click Manage SSO Integration.
- On the SSO Integration page, select Get Started (or click Add if you already have an SSO Integration created) which will bring up a form. Complete the following fields:
- Identity provider name: This value is used to help you identify your IdP and it won’t affect the SSO configuration itself.
- Select account(s): The accounts you want to associate with the SSO Integration.
- Create an SSO Integration with a status set to Off. This status means it has not been enabled yet.
- Keep this tab open – you’ll need to refer to and further configure the integration in later steps.
Step 2: Gather SSO Integration information
There are two ways you can gather this information on the Bandwidth SSO Integration page:
- Click Metadata in the IdP created in Step 1. This will download a metadata file containing the information you’ll need to provide to your IdP.
- Click the drop-down arrow next to the Name of the integration you just created. This will expand the row and display the Assertion Consumer Service Url and the Entity ID you can copy for later use.
Step 3: Create and configure a SAML 2.0 application in your IdP
- In your IdP, create a SAML 2.0 application.
- Copy and paste the following values gathered in Step 2 into your IdP. These are required in order for your IdP to recognize the Bandwidth SSO Integration:
- Entity ID/Audience Uri: This value is the entityID attribute under the EntityDescriptor tag in the metadata file.
- Assertion Consumer Service Url/Single Sign-On Url: This value is the Location attribute under the AssertionConsumerService tag in the metadata file.
- We require the NameID to follow the emailAddress format. Its value should match the username of the users you confirmed were created (or recreated in Prerequisites). The format of the NameID should be configurable in the Claims configuration of your IdP.
- We also require the following additional claims to be sent exactly as they’re defined here:
- firstName
- lastName
- mobilePhone (optional)
Step 4: Finish configuring your Bandwidth SSO Integration
- While keeping your IdP information handy, navigate back to the Bandwidth SSO Integration page and click on Details for your integration.
- Copy and paste the corresponding values from your IdP into the following fields:
- Single sign-on Url: Depending on your IdP, this value could be listed as “Login URL”, or “SSO Url”.
- Issuer Uri: Depending on your IdP, this value could be listed as “Identifier”, “Entity ID”, or “Identity Provider Issuer”.
- Signature certificate: This certificate must contain the public key to verify sign-in requests. The supported certificate format is X.509.
- Click Save changes and then Confirm your changes.
Step 5: Enable and test your Bandwidth SSO Integration
Once you’ve completed the previous steps, you can enable SSO for your users:
- On the SSO Integration page, change the status of the SSO integration you want to enable to On and then select Confirm.
- In the top navigation bar, click Log out to log out of the SSO integration page.
- If you're logged into the Bandwidth App in other tabs or windows, also click Log out on those pages to ensure you don’t have any existing sessions and that future logins will use SSO.
- Navigate back to the Bandwidth App, enter the username of your user, and (if prompted) select the IdP you just created. You’ll be redirected to your IdP login page.
- After logging in with your IdP, you should be redirected back to the Bandwidth App.
Note: If the SSO Integration doesn’t work correctly, disable the integration by clicking Off and then Confirm. If needed, refer to the Break glass section of this guide for details on how to disable a broken SSO Integration.
Troubleshooting
Here are some of the common issues, that could be the root cause of any 400: Bad Request Error Code: GENERAL_NONSUCCESS error messages you receive and/or you being redirected to another login page after logging in with your IdP:
- The provided Signature Certificate is incorrect. Ensure that the certificate is the public key of the certificate chain.
- NameID is incorrectly formatted. We require the NameID to follow the emailAddress format. This means that users in the Bandwidth App must have an email address as their username.
- Required additional claims (firstName, lastName, and email) are not being sent in the SAML response.
- The provided Issuer Uri is incorrect. The name of this value differs across IdPs. Please double-check the value you provided.
A SAML tracer (browser extension) can be useful in debugging issues with the SSO Integration and confirming the formats and claims are being sent as expected.
If none of the above helps resolve your issue, please open a ticket with your Bandwidth Support Team for further assistance.
Break glass
We offer a “break glass" solution for admins to log in to the Bandwidth App while a broken SSO Integration is active. You can access it by completing the following steps:
- Navigate to the Bandwidth App (log out if you have a session established).
- Once on the login page, enter your username and click Next.
- You’ll then see the following text: “Single sign-on not working? Use your password”. Click Use your password.
- Enter your password and click Sign In.
- Important: If your current password doesn’t work, it has likely expired. If so, please click Forgot password? and follow the password reset instructions.
- Navigate to the SSO Integration page and turn Off the broken integration.
- Advise your users to reset their passwords if they need to access the Bandwidth App.
Frequently Asked Questions
What SSO providers does Bandwidth support?
We support SAML 2.0-compliant providers. Here are a few examples:
- Okta
- Azure AD
- ADFS
- Shibboleth
There are more SAML 2.0 providers, of course. To see if your provider is supported, please ask your IT admin whether it's SAML 2.0-compliant.
What if I have multiple IdPs configured across my accounts?
If you have the same user configured across multiple IdPs, they will be presented with multiple options on the login screen with the different IdPs you have configured for their accounts.
Are API users required to use SSO?
No, API users can continue to use the password configured via the Bandwidth App. However, if the API user uses the no longer supported combined access method, we recommend doing the following:
- Under User Access Method, change Combined Dashboard and API user to Allow user credentials to authenticate API.
- Create a new user with the Allow user to login to the Bandwidth App access method. This will allow that person to log into the Bandwidth App using their UI credentials that are separate from their API ones.
Can I turn off SSO?
Yes, but once SSO is turned on, all your users will be accustomed to using your IdP’s user credentials. Turning off SSO will disable this, and user logins won’t work with those credentials. If you must turn off SSO, users may have to go through the password reset process to re-establish a password for their username. This may happen if their Bandwidth password has expired since turning on SSO, or if a password was never established because they've always used SSO.
Article is closed for comments.