Skip to contentSkip to navigationSkip to topbar
On this page

Flex SSO URL Migration Guide



Overview

overview page anchor

If your Flex instance is running Flex UI 2.7.x or later, migrate your SSO connection to a new solution that offers enhanced security using OAuth 2.0.

(information)

Info

All Flex customers using the legacy SSO configuration need to migrate to the enhanced SSO configuration prior to June 2025.


Migrating to enhanced SSO configuration requires changes in two places: Flex Console and your IdP. When choosing a setup type, consider whether the Flex administrator has access to make changes in the IdP. If you need to collaborate with an IdP administrator on the migration, this may influence which setup method works best for your organization.

Modify existing SSO connection

modify-existing-sso-connection page anchor

With this option, the IdP administrator will update the Entity ID and ACS URL for the existing IdP application used for Flex.

BenefitsConsiderationsUse this option if
  • Doesn't require any new IdP setup.

  • Doesn't require updates for users who already have access to Flex.
  • If a configuration error occurs during migration, you'll have to revert to the legacy SSO connection while you troubleshoot. This could cause new agent logins to be denied until you successfully revert your connection.
  • You can collaborate with your IdP administrator in real-time to complete the migration.

  • Your business can tolerate the risk of time where new agent logins are denied.

Create new existing SSO connection

create-new-existing-sso-connection page anchor

With this option, the IdP administrator will set up a new IdP application to use for Flex.

BenefitsConsiderationsUse this option if
  • The legacy SSO connection remains unchanged, and you can switch back to it in case of a configuration error during migration. This reduces the chance that new agent logins will be denied if issues occur.

  • The Flex administrator and the IdP administrator can collaborate asynchronously to complete the migration.
  • Requires additional effort to set up a new IdP application and SSO connection.

  • The IdP administrator has to configure all current Flex users to access the new IdP application for Flex before you can start sending login traffic to it.
  • You can't collaborate with your IdP administrator in real-time to complete the migration.

  • Your business can't risk having any time where new agent logins are denied.

Migrating has three or four steps, depending on your setup type:

  1. Select setup type.
  2. Update your identity provider.
  3. Enter identity provider data.

    Note This page only appears if you create a new SSO connection. If you modify your existing connection, Flex uses the IdP data from your legacy connection, so you don't need to enter this information again.

  4. Validate successful connection in Flex.
(information)

Info

If you're a self-hosted Flex customer, you have to do an additional step before validating your new SSO connection. See Self-hosted Flex: additional SSO configuration for instructions.

To start your migration:

  1. In Console, navigate to Flex > Manage > Single sign-on . If you're running Flex UI 2.7.x or later, you'll see a New SSO Solution Available section.
  2. Click Start setup.

    The Single sign-on set up workflow appears.

Step 1: Select setup type

step-1-select-setup-type page anchor
  1. Select a setup type:
    • Modify existing SSO connection
    • Create new SSO connection
  2. Click Continue .

Step 2: Update your identity provider

step-2-update-your-identity-provider page anchor

In this step, the IdP administrator sets the Entity ID and ACS URL values for the new connection in the IdP. However, the IdP may not use the same labels to identify these values.

Check the following table to see what field labels your IdP uses. If you need help locating the fields, click the IdP name in the table to go to the full setup instructions. There, you can find the steps to navigate to the appropriate page in your IdP.

IdPIdP pageEntity ID labelACS URL label
Google SSOService provider detailsEntity IDACS URL
Okta IdPCreate SAML integrationAudience URI (SP Entity ID)Single sign on URL
Salesforce SSOWeb App settingsEntity IDACS URL
Azure ADSAML > General SAML settingsIdentifier (Entity ID)Reply URL (Assertion Consumer Service URL)
Auth0 IDPSAML2 Web App > Settingsaudience settingApplication Callback URL

To update your IdP:

  1. Copy the Entity ID and ACS URL values from the Single sign-on setup workflow.
  2. In your IdP, paste the values into the appropriate fields.
    • If you're modifying your existing connection, update these values in your existing application.
    • If you're creating a new SSO connection, make sure you add the values to the new application, not to the application used for your legacy connection.
  3. In the Single sign-on setup workflow, confirm that the values have been updated.
  4. Click Save and Continue .

Step 3: Enter identity provider data

step-3-enter-identity-provider-data page anchor

This page only appears in the workflow for creating a new SSO connection.

(information)

Info

If you're a self-hosted Flex customer, you must provide a value for the Trusted domains field and the Domain redirect URL field, in addition to the fields marked as required on the page. See How do I log in to a self-hosted domain? to make sure your domain URL conforms to one of the allowed patterns.

  1. Enter the SAML setting values from your new application. If you need more information about the settings, see the setup instructions for your IdP:
  2. Click Save .

Step 4: Validate successful connection in Flex

step-4-validate-successful-connection-in-flex page anchor
(information)

Info

If you were previously logged in to Flex, you'll need a new login to validate your new SSO connection. You can either log out of Flex and log back in, or you can log in using a private or incognito browser.

  1. Click Log in with SSO .
  2. When prompted, enter the credentials of a user who has access to the application in your IdP used for Flex.

    Flex loads when your login is successful.

  3. Click Finish to complete the migration.

This returns you to the Single sign-on page:

  • If you modified your existing connection, you'll see your new OAuth 2.0 connection.
  • If you created a new SSO connection, you'll see both your new OAuth 2.0 connection and your inactive legacy connection.

Switch back your SSO connection

switch-back-your-sso-connection page anchor

Flex saves your legacy connection details for 30 days after completing the migration. If you experience login issues during this time, you can switch back while you troubleshoot your SSO connection.

Revert modified connection

revert-modified-connection page anchor

If you modified your existing connection, you have only one SSO connection defined. To switch to your legacy connection, have the IdP administrator revert the Entity ID and ACS URL values in your IdP to those of your previous connection.

  1. On the Single sign-on page, under New connection saved, click switch back to legacy connection.

    The Revert SSO connection page appears.

  2. From the Legacy Flex SSO section, provide the Entity ID and ACS URL values to your IdP administrator to add to the IdP.
  3. When the IdP updates are complete, click I confirm that my Flex application reflects the Legacy Flex SSO connection .
  4. Click Switch connection .

When you want to return to using your new connection, complete the migration steps again.

Switch from new connection to legacy connection

switch-from-new-connection-to-legacy-connection page anchor

If you created a new SSO connection, both your OAuth 2.0 connection and your legacy connection are saved. Switch back to your previous connection using the link on the Single sign-on page.

  1. On the Single sign-on page, under New connection saved , click switch back to legacy connection .
  2. In the Switch to OAuth 2.0 SSO Connection dialog, click Confirm .

The link on the Single sign-on page now reads switch back to OAuth 2.0 connection. Use this link you want to return to using your new connection.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.