SSO integration guide


Daniel Yeam


How do I enable SSO 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 SSO for the Bandwidth Dashboard to work with your SAML 2.0 Identity Provider (IdP). We suggest doing this with the help of your IT department.

Step 1: Verify that your IdP is ready to enable SSO

  • SSO integration for the Bandwidth Dashboard only works with SAML 2.0, so please confirm that your organization’s IdP supports it. 
  • If you don’t know whether your IdP supports SAML 2.0, contact your IT department for confirmation.

Step 2: Verify that you have admin credentials in the Bandwidth Dashboard

  • Log in to the Bandwidth Dashboard.
  • In the top navigation bar, click Account and select Users.
    • If you’re an admin, you’ll see all the users associated with your selected account.
    • If you are not an admin, you’ll only see your own user information. You must use admin credentials to continue the process.

Step 3: Important: Verify that each user has a username that’s an email address

  • Usernames must be email addresses. Unfortunately, our SSO integration currently does not support usernames that are not email addresses.

Note: This is referring to the actual Username field, not just the Email address field. The Username field can be seen in the User Information section or the Users list in the sidebar, directly underneath the user’s name.

  • Since usernames in the Bandwidth Dashboard cannot be changed, you have to recreate users that have unsupported usernames and make sure their new usernames are email addresses, in order to enable them for SSO. 

Step 4: Configure SSO Integration

  • In the top navigation bar, click Account to navigate to the Account Overview page. Then click the Manage SSO Integration link to access the Single Sign-On (SSO) Integration window.
  • Click ADD to add a new SSO Integration.
    • If you’ve previously created an SSO integration on this page and want to use it now, you can skip this step.
  • Enter the following IdP information in the Setup SSO Integration (SAML) window and then click SAVE:
    • Identity provider name (required)
    • Select account(s) (required)
    • Identity provider issuer URI (optional)
    • Identity provider single sign-on URL (optional)
    • Identity provider signature certificate (optional)

Step 5: Download the IdP metadata

  • Click METADATA to download the metadata.xml file.
  • Use this file to configure your organization’s IdP.
  • If you don’t know how to use the metadata.xml file, contact your IT department for assistance.

Step 6: Enable SSO Integration

  • Use the On/Off toggle to turn on SSO for the desired IdP by setting the Status field to On.

Note: All fields in Step 4 (including optional ones) must be completed before you can turn on SSO.

Step 7: Log in with your own IdP credentials

  • Log in to the Bandwidth Dashboard using your organization’s IdP credentials instead of your Bandwidth Dashboard credentials. This will test the authentication handshake that occurs between Bandwidth and your IdP.
  • If the login is not successful, please open a ticket with your Bandwidth Support Team.

Congratulations! You’ve now successfully configured SSO for the Bandwidth Dashboard.

What if I have multiple IdPs configured across my accounts?

If you have the same user configured across multiple IdPs, they can log in with SSO using only the most recently modified IdP on the SSO Integration page. We’re currently working to allow users to dynamically select which IdP they want to use for their SSO during login. This functionality is coming soon!

Are API users affected?

API users are not affected and will continue to use the password configured via the Bandwidth Dashboard. 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 Dashboard” access method so that this API user can also log into the Bandwidth Dashboard separately.

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.