Configure Google Single Sign-On (SSO) with Twilio Flex
Twilio is launching a new Console. Some screenshots on this page may show the Legacy Console and therefore may no longer be accurate. We are working to update all screenshots to reflect the new Console experience. Learn more about the new Console.
Have you already configured SSO using the preview.twilio.com
endpoint? Learn how to update your existing configuration with the Flex SSO Migration Guide. Additionally, Twilio does not yet support SP-Initiated SSO flows with Google SSO. Only IdP-Initiated SSO flows are supported at this time.
1. Prepare your Google App environment
Before we connect Google to your instance of Flex, we have to build a few things in the Google Admin Console to make things run a little bit more smoothly.
To log in a Flex user, you must pass a minimum of three attributes to Flex in the SAML. Google provides email
as an attribute out of the box but does not provide the roles
or full_name
attributes. We will need to build these ourselves.
All the information supplied from the Identity Provider to Twilio is stored inside Twilio TaskRouter Worker Attributes. Consider local regulations for storing data and only provide data relevant for Flex usage. Learn more about Twilio's Privacy policy here.
- Navigate to the User Schema page in your Google Admin Console.
- Click on ADD CUSTOM ATTRIBUTE
- Category = Flex Details
- Create the two attributes below
Name | Info Type | Visibility | No. of Values |
Roles | Text | Visible to Admin | Multi-value |
Full Name | Text | Visible to Admin | Single Value |
Optionally, you can add more attributes to accommodate the attributes needed by WFO.
2. Create a custom SAML app
Navigate to the Google Admin Console and click on Apps
Click SAML apps.
Then click the "Add a service/App to your domain" link, or click the + icon at the bottom right.
a. Enable SSO for SAML application
Click on SETUP MY OWN CUSTOM APP
b. Google IdP Information
Download the certificate in the Option 1 section, and make a note of the SSO URL
and Entity ID
– you'll need these later.
c. Basic information for your custom app
- Set your Application Name – This might be "Twilio Flex", or a name of your choosing
- You may optionally add a description and logo
Here's a logo you can use!
d. Service provider details
Next, we need to set up the Service Provider Details. Twilio Flex is the Service Provider in this instance.
Setting | Value |
ACS URL | https://iam.twilio.com/v1/Accounts/ACxxxx/saml2
Make sure to replace the Account SID (ACxxxx) with your real Account SID. |
Entity ID |
Make sure to replace the Account SID (ACxxxx) with your real Account SID! |
Start URL |
This Login Link is available on the Twilio Console SSO configuration page. |
Signed Response | Checked! |
Name ID |
Basic Information & Primary Email |
Name ID Format |
e. Attribute mapping
Now we need to add attributes that will be passed from the SAML to Flex. Create at least the three required attributes (case sensitive) to pass to Flex and map them to the appropriate fields.
3. Add the mapped roles to your G Suite Users
Navigate back to the Google Admin Console and click on Users.
Select a user and click into their User information section.
Scroll to the attribute name you gave your Flex roles (in this example it's 'Flex Roles') and click the edit icon to add your roles. The current options are 'agent', 'admin', and 'supervisor'.
Complete the setup
Now that you've configured your app, you must
- Verify your domain (if you haven't already) - https://support.google.com/a/answer/60216?hl=en
- Enable your app - https://support.google.com/a/answer/6087519?hl=en
4. Configure Flex with your Google SSO settings
Grab the URLs you noted in the Google IdP Information section and configure SSO on the Flex Console Single Sign-on settings page. Be sure that the Twilio SSO URL field matches the value you provided in Google for ACS URL. To learn more about migrating from the preview.twilio.com URL to iam.twilio.com see our migration guide.
Setting | Value |
Friendly Name | Anything you want |
x.509 Certificate | Open the .pem file you downloaded above in your favorite text editor and copy/paste the entire contents of the file including all dashes. |
Identity Provider Issuer | Google's Entity ID (see above) |
Single Sign-On URL | Google's SSO URL (see above) |
Default Redirect URL |
This Login Link is available at the top of the active SSO configuration page. |
Immediately after you’ve configured your IDP to use the iam.twilio.com
URL you should update the Twilio SSO URL for your account by selecting the USES IAM.TWILIO.COM
radio button.
Additional SSO Configuration
Our Configuring SSO page has additional details on how to initiate login from your Identity Provider, how to login to a self-hosted domain, and details on attributes that can be defined for each identity.
5. Testing Google SSO
Navigate to the Google SSO IdP URL (see above) in incognito mode, login, and you should be redirected to Flex.
Congrats!
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.