Skip to contentSkip to navigationSkip to topbar
On this page

Configure Okta IdP with Flex



Overview

overview page anchor

To set up Okta as your identity provider (IdP) for Flex, you need to create a SAML 2.0 integration in Okta and then configure Flex with those credentials.

For prerequisites to create a SAML 2.0 integration, or for more information about this type of integration, see Okta's documentation(link takes you to an external page).


Create an application in Okta

create-an-application-in-okta page anchor

In the Okta Admin Console, navigate to Applications > Application. Staying within your Okta account, create an application:

  1. Click Applications > Applications > Create App Integration .
    A dialog appears with integration options.
  2. Click SAML 2.0 .
  3. Give the application a name. For example, Twilio Flex .
  4. Optionally, upload a logo.

Tip: If you can't finish your setup in one sitting, continue by navigating back to Applications > Applications in the Okta Admin Console and selecting your active application.

Configure your general SAML settings

configure-your-general-saml-settings page anchor

On the Create SAML Integration page, enter the following general settings:

General and advanced settingsValues
Single sign on URLEnhanced SSO configuration: Copy this value from the Set up your identity provider page, which provides the specific value for your account. Your value will look similar to this: https://login.flex.us1.twilio.com/login/callback?connection=JQxxxx

Legacy SSO configuration: Replace ACxxxx with your real Twilio Account SID. https://iam.twilio.com/v1/Accounts/ACxxxx/saml2
Audience URI (SP Entity ID)Enhanced SSO configuration: Copy this value from the Set up your identity provider page, which provides the specific value for your account. Your value will look similar to this: urn:flex:JQxxxx

Legacy SSO configuration: Replace ACxxxx with your real Twilio Account SID. https://iam.twilio.com/v1/Accounts/ACxxxx/saml2/metadata
Default RelayStateLeave blank.
Name ID formatLeave Unspecified selected, unless you are working with a specific format.
Application usernameThis can be an email, Okta username, or another unique name.
ResponseClick Show Advanced Settings and make sure Signed is selected.
Assertion SignatureClick Show Advanced Settings and make sure Signed is selected.
Signature Algorithm, Digest AlgorithmLeave the default selections.
Assertion EncryptionSelect Unencrypted. Twilio doesn't currently support encryption.
Assertion Inline Hook, Authentication context class, Honor Force Authentication, SAML Issuer IDLeave the default selections.
saml-settings.

Claims are key-value pairs that the Identity Provider asserts are true to the application. Flex uses these to determine the critical information about each Flex User.

(warning)

Warning

All the information the Identity Provider supplies 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(link takes you to an external page).

In Okta, in the Attribute Statements section, add the following required claims. The values shown in the table below are only examples. Replace placeholders with values specific to your Okta implementation. Make sure the Okta user attribute you are using for the Flex roles is populated.

NameName formatValue
full_nameBasicString.join(" ", user.firstName, user.lastName) OR ${user.firstName} ${user.lastName}
rolesBasicuser.userType
emailBasicuser.email

You can optionally add the following attribute:

NameName formatValue
image_urlURI Referenceuser.profileUrl

For a list of mandatory attributes and example values, see Configuring SSO and IdP in Flex.

With the setup described above, Okta passes the following attributes to Flex:

  • full_name
  • image_url (for use in the agent avatar)
  • roles
  • email

Preview the SAML assertion generated and validate your SAML settings. In this example, the ACL URL and entity ID values are shown using the placeholders https://ACS_URL and https://entity_ID, respectively.

1
<?xml version="1.0" encoding="UTF-8"?>
2
<saml2:Assertion ID="id5838987467318981535749982" IssueInstant="2021-08-26T15:19:53.544Z" Version="2.0"
3
xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
4
<saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.okta.com/Issuer</saml2:Issuer>
5
<saml2:Subject>
6
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">userName</saml2:NameID>
7
<saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
8
<saml2:SubjectConfirmationData NotOnOrAfter="2021-08-26T15:24:53.549Z" Recipient="https://ACS_URL"/>
9
</saml2:SubjectConfirmation>
10
</saml2:Subject>
11
<saml2:Conditions NotBefore="2021-08-26T15:14:53.549Z" NotOnOrAfter="2021-08-26T15:24:53.549Z">
12
<saml2:AudienceRestriction>
13
<saml2:Audience>https://entity_ID</saml2:Audience>
14
</saml2:AudienceRestriction>
15
</saml2:Conditions>
16
<saml2:AuthnStatement AuthnInstant="2021-08-26T15:19:53.544Z">
17
<saml2:AuthnContext>
18
<saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
19
</saml2:AuthnContext>
20
</saml2:AuthnStatement>
21
<saml2:AttributeStatement>
22
<saml2:Attribute Name="roles" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
23
<saml2:AttributeValue
24
xmlns:xs="http://www.w3.org/2001/XMLSchema"
25
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.userType
26
</saml2:AttributeValue>
27
</saml2:Attribute>
28
<saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
29
<saml2:AttributeValue
30
xmlns:xs="http://www.w3.org/2001/XMLSchema"
31
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.email
32
</saml2:AttributeValue>
33
</saml2:Attribute>
34
<saml2:Attribute Name="image_url" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
35
<saml2:AttributeValue
36
xmlns:xs="http://www.w3.org/2001/XMLSchema"
37
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.profileUrl
38
</saml2:AttributeValue>
39
</saml2:Attribute>
40
<saml2:Attribute Name="full_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
41
<saml2:AttributeValue
42
xmlns:xs="http://www.w3.org/2001/XMLSchema"
43
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"/>
44
</saml2:Attribute>
45
</saml2:AttributeStatement>
46
</saml2:Assertion>

On the next screen, select I'm an Okta customer adding an internal app.


Copy your application details

copy-your-application-details page anchor

You need the details of your Okta application to configure Flex to use this application. To locate your Okta application details:

  1. With your application selected, click the Sign On tab.
  2. Do one of the following:
    • Under Sign on methods , in the SAML 2.0 section, click More details .
    • In the right pane, under SAML setup , click View Setup Instructions .

Configure Flex with your new SAML credentials

configure-flex-with-your-new-saml-credentials page anchor

You can configure SSO in Flex Console on the Single Sign-on(link takes you to an external page) page. Make sure you copied your application details using the instructions directly above so you have the values you need from Okta. Flex requires the following fields:

Twilio SSO fieldOkta field
X.509 CertificateX.509 Certificate
Identity Provider IssuerIdentity Provider Issuer
Single Sign-on URLIdentity Provider Single Sign-On URL
sso-setup-twilio-console.

Create your application users in Okta

create-your-application-users-in-okta page anchor

In Okta, add the users you want to access Flex and assign the Flex roles they need to have. You can add Okta users individually or in a batch:

  • To add users individually, go to Directory > People , and click Add person .
  • To import a group of users, on the More actions dropdown, import a CSV file containing the list of users.

Make sure that you assign a Flex role to your Okta application users by leveraging the user attribute defined for the "roles" SAML claim. Available Flex roles are agent, admin, and supervisor. To assign multiple roles, use a comma-separated list.

(information)

Info

Want to learn more? See the documentation on Identity Attributes for further information about naming Attributes and other possible Worker attributes. To assign WFO roles for Flex Insights, see Flex Insights User Roles.

To assign a role:

  1. Navigate to Directory > People , select the user, and click the Profile tab.
  2. Edit the User type attribute to specify the roles that you want to assign to your Flex user.

After you define the roles for a user, Flex updates the Worker attributes with each successful SSO authentication.


Assign users in the directory to your application

assign-users-in-the-directory-to-your-application page anchor

To assign users to your application in Okta:

  1. In the Okta Admin Dashboard, navigate to Applications > Applications and click Assign Users to app .
    sso-assign-application.
  2. Select the application and the users you want to add, and then click Next .
  3. Optionally, enter user-specific attributes. If you are defining a custom username, make sure it's unique.
  4. Click Confirm Assignments .

Troubleshooting a "Flex application unassigned" error

troubleshooting-a-flex-application-unassigned-error page anchor

The message "Sorry, you can't access Twilio Flex because you are not assigned this app in Okta" can appear if a user isn't properly assigned to the Okta app you created for Flex. Revisit the steps above to add them to your application.


To test your SSO setup:

  1. Navigate to the Flex Console Single Sign-on page(link takes you to an external page) .
  2. Do one of the following:
    • Click Login with SSO .
    • Copy the login link and paste it into your browser address bar. This redirects you to the IdP login page.
  3. Log in using the credentials of the test user. Depending on the user settings, the IdP may ask you to set your password.

    Once authentication completes, the IdP redirects you to the Flex UI. What you can see in the UI depends on the Flex roles set in the IdP user profile.
  4. Validate the worker full name display in the Flex UI, or navigate to the Worker page in the TaskRouter Dashboard(link takes you to an external page) to review other attributes, like email and assigned roles.

See Configuring SSO for additional details like the following:

  • How to initiate login from your IdP
  • How to log in to a self-hosted domain
  • Which attributes you can define for each identity

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.