Security Assertion Markup Language (SAML) signing certificates expire, usually every one to three years depending on your Identity Provider (IdP). When the certificate on your Bandwidth Single Sign-On (SSO) integration expires, your users can no longer log in to the Bandwidth App with SSO.
This guide describes how to rotate a SAML signing certificate on an existing Bandwidth SSO integration. Plan for a short, expected window of downtime for users attempting to authenticate to the Bandwidth App during the cutover, and schedule the rotation accordingly (this will not impact any API integrations). If you're setting up SSO for the first time, see Configuring a SAML 2.0 Identity Provider with Bandwidth Single Sign-On Integration instead.
Prerequisites
You must have the following to rotate a SAML certificate:
Admin credentials for the Bandwidth App (only admins can access the SSO Integration page).
Admin access to your IdP, with permission to generate and activate signing certificates.
A working Bandwidth SSO integration with a status of On.
The expiration date of your current certificate, so you can schedule the rotation ahead of time.
Important: Your Bandwidth SSO integration stores one signature certificate at a time. Your IdP can keep the old and new certificates active at the same time, but Bandwidth trusts only one of them, so there's no way to overlap the two on the Bandwidth side.
This means Steps 3 and 4 create a short window where new SSO logins fail. To keep that window as small as possible:
Schedule the rotation outside your users' core hours, and let them know ahead of time.
Have both browser tabs open before you start: your IdP settings on one, the Bandwidth SSO Integration page on the other.
Have the new certificate downloaded and ready to paste before you change anything.
Complete Steps 3 and 4 back to back, without pausing to test in between.
Users with an active Bandwidth App session aren't signed out by the change. When users sign in to the Bandwidth App, we validate their sign-in using the active certificate in our system. Only users attempting a new sign-in during the cutover are affected. Before you start, confirm you can still log in with the break glass method described in the if you get locked out section. This gives you a way back into the Bandwidth App if something goes wrong mid-rotation.
Step 1: Generate a new certificate in your IdP
Log in to your IdP (e.g., Okta, Azure AD, or Ping Identity).
Navigate to the Single Sign-On (SSO) or SAML settings of the application you created for Bandwidth.
Find the SAML Signing Certificates section and create a new certificate. Depending on your IdP, this option may be called Generate new certificate or Add a certificate.
Leave the old certificate Active (or Primary). Most IdPs allow more than one active certificate, which prevents downtime across your other applications while you roll the new certificate out.
Note: Rotating a certificate doesn't change your Entity ID or Assertion Consumer Service URL. Leave those values alone.
Step 2: Download the new certificate
Download the new certificate, or the updated federation metadata XML file, from your IdP.
You need the public key of the certificate chain in X.509 format. If you downloaded the metadata file, the certificate is the value inside the X509Certificate tag.
Step 3: Update the signature certificate in the Bandwidth App
Log in to the Bandwidth App.
In the side navigation bar, click Account and select Overview.
Under the Account Management section, click Manage SSO Integration.
Find your active integration and click Details.
Replace the value in the Signature certificate field with the new certificate from Step 2.
Click Save changes and then Confirm your changes.
Leave this tab open. If the rotation doesn't work, you'll come back here to roll the change back.
Note: The Bandwidth App validates the certificate when you save. If the certificate has already expired, your save is rejected and the integration keeps its current value. Generate a new certificate in your IdP and try again.
Step 4: Activate the new certificate in your IdP
Return to your IdP settings.
Change the status of the new certificate to Active or Primary.
Save your settings.
Your IdP now signs SAML responses with the same certificate Bandwidth trusts.
Step 5: Test your SSO login
Open a new incognito or private browser window, so you're testing with a clean session rather than an existing one.
Navigate to the Bandwidth App, enter your username, and (if prompted) select your IdP.
Log in with your IdP credentials. You should be redirected back to the Bandwidth App.
Ask a second user to test their login as well, ideally one without admin permissions.
Note: If logins fail, you have two rollback options. If the old certificate hasn't expired yet, restore it in the Signature certificate field and revert your IdP to signing with it. If the old certificate has already expired, that save is rejected, so disable the integration instead by clicking Off and then Confirm. Your users then log in with their Bandwidth passwords, though some may need to go through the password reset process first. Users who have only ever logged in with SSO may never have set a password, and existing passwords may have expired since you turned SSO on.
Step 6: Remove the old certificate
Once you've confirmed that users can log in without errors, return to your IdP.
Find the old certificate and delete or revoke it.
Save your settings.
Troubleshooting
If your save is rejected in Step 3, the certificate is either expired or malformed. Confirm the expiration date in your IdP, then re-copy the value and check that the header and footer lines are intact.
Note that the save only checks whether the certificate has expired. A certificate with a future start date saves successfully but fails at login until that date passes. If your save went through and logins still fail, check the certificate's notBefore date in your IdP.
If you see a 400: Bad Request Error Code: GENERAL_NONSUCCESS message, or your users land back on a login page after authenticating with your IdP, check the following:
You pasted the wrong part of the certificate. The Signature certificate field needs the public key of the certificate chain, not the private key.
Your IdP is still signing with the old certificate. Confirm the new certificate is set to Active or Primary in your IdP, not just created.
You updated the wrong integration. If you have several integrations configured, confirm you edited the one your users authenticate against.
The certificate didn't copy cleanly. Extra whitespace or missing header and footer lines can invalidate the value. Re-copy it from the source file.
Required claims stopped coming through. Your IdP should still send firstName, lastName, and email, and the NameID should still use the emailAddress format.
A SAML tracer browser extension is useful for confirming which certificate your IdP is actually signing with.
If none of the above resolves your issue, open a ticket with your Bandwidth Support Team.
If you get locked out
Admins can use our break glass solution to log in to the Bandwidth App while a broken SSO integration is active:
Navigate to the Bandwidth App and log out if you have a session established.
Enter your username and click Next.
Click Use your password under the text "Single sign-on not working? Use your password".
Enter your password and click Sign In.
Important: If your current password doesn't work, it has likely expired. Click Forgot password? and follow the password reset instructions.
Navigate to the SSO Integration page. If your previous certificate is still valid, restore it in the Signature certificate field. If it has expired, turn the integration Off instead, since an expired certificate won't save.
Frequently asked questions
How do I know when my certificate expires?
Bandwidth sends you reminders 90, 60, 30, and 7 days before your certificate expires, so you don't have to track the date yourself. You can also check the SAML Signing Certificates section of your IdP application. Most IdPs list an expiration date next to each certificate and can notify you before it lapses.
What happens if the certificate expires before I rotate it?
Your users can't log in with SSO. Admins can still get in with the break glass method above, then either rotate the certificate or turn the integration Off while you work through it.
Can I store two certificates on my Bandwidth SSO integration?
No. Each integration holds one signature certificate, so your IdP needs to sign with that certificate for logins to succeed. Keep both certificates active in your IdP during the rotation, then remove the old one once you've tested.
How much downtime should I expect?
Only the time it takes you to move from Step 3 to Step 4, typically a minute or two if you've prepared both tabs in advance. During that window, users attempting a new SSO login see an error. Anyone already signed in keeps working, and admins can always get in with the break glass method above.
Do I need to reconfigure anything else on the Bandwidth side?
No. The Entity ID, Assertion Consumer Service URL, Single sign-on Url, and Issuer Uri all stay the same. The signature certificate is the only value that changes.
Do my users need to do anything?
No. Once the rotation is complete, they log in exactly as they did before.
I have multiple SSO integrations. Do I rotate them all at once?
Rotate them one at a time and test each one before moving to the next. That keeps the blast radius small if something goes wrong.