Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Configure Okta IdP with Flex



Register a developer account at Okta

register-a-developer-account-at-okta page anchor

Navigate to https://developer.okta.com/(link takes you to an external page) and create a free developer account.


Create an application on Okta

create-an-application-on-okta page anchor

Navigate to Applications > Application in the Okta Admin Console. Staying within your Okta account, create an Application.

  1. Click Applications > Applications > Create App Integration .
  2. A pop-up modal should display with integration options. Pick SAML 2.0 .
  3. Give the Application a name. For example, Twilio Flex . Upload a logo if you have one.

Configure your Application

configure-your-application page anchor

In the "Create SAML Integration" page, enter the following general settings:

General SAML Settings

general-saml-settings page anchor
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 something else that is unique.
ResponseClick Show Advanced Settings and ensure that this is set to "Signed".
Assertion SignatureClick Show Advanced Settings and ensure that this is set to "Signed".
Signature Algorithm, Digest AlgorithmLeave the default selections.
Assertion EncryptionTwilio does not currently support encryption so please set that as "Unencrypted".
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 to be true to the application. Flex uses these to determine the critical information about each Flex User.

(warning)

Warning

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.

In the Attribute Statements section, add the following required claims. The values in the following table are for example purposes only. Replace with the appropriate 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 provided setup, Okta will pass the following attributes to Flex:

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

Scroll down to the bottom of the page to preview the SAML assertion generated based on your settings. It's a good way to validate your SAML settings. In this example, we've replaced the ACL URL and entity ID values with https://ACS_URL and https://entity_ID.


_46
<?xml version="1.0" encoding="UTF-8"?>
_46
<saml2:Assertion ID="id5838987467318981535749982" IssueInstant="2021-08-26T15:19:53.544Z" Version="2.0"
_46
xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
_46
<saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">http://www.okta.com/Issuer</saml2:Issuer>
_46
<saml2:Subject>
_46
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">userName</saml2:NameID>
_46
<saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
_46
<saml2:SubjectConfirmationData NotOnOrAfter="2021-08-26T15:24:53.549Z" Recipient="https://ACS_URL"/>
_46
</saml2:SubjectConfirmation>
_46
</saml2:Subject>
_46
<saml2:Conditions NotBefore="2021-08-26T15:14:53.549Z" NotOnOrAfter="2021-08-26T15:24:53.549Z">
_46
<saml2:AudienceRestriction>
_46
<saml2:Audience>https://entity_ID</saml2:Audience>
_46
</saml2:AudienceRestriction>
_46
</saml2:Conditions>
_46
<saml2:AuthnStatement AuthnInstant="2021-08-26T15:19:53.544Z">
_46
<saml2:AuthnContext>
_46
<saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
_46
</saml2:AuthnContext>
_46
</saml2:AuthnStatement>
_46
<saml2:AttributeStatement>
_46
<saml2:Attribute Name="roles" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
_46
<saml2:AttributeValue
_46
xmlns:xs="http://www.w3.org/2001/XMLSchema"
_46
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.userType
_46
</saml2:AttributeValue>
_46
</saml2:Attribute>
_46
<saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
_46
<saml2:AttributeValue
_46
xmlns:xs="http://www.w3.org/2001/XMLSchema"
_46
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.email
_46
</saml2:AttributeValue>
_46
</saml2:Attribute>
_46
<saml2:Attribute Name="image_url" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
_46
<saml2:AttributeValue
_46
xmlns:xs="http://www.w3.org/2001/XMLSchema"
_46
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.profileUrl
_46
</saml2:AttributeValue>
_46
</saml2:Attribute>
_46
<saml2:Attribute Name="full_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
_46
<saml2:AttributeValue
_46
xmlns:xs="http://www.w3.org/2001/XMLSchema"
_46
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"/>
_46
</saml2:Attribute>
_46
</saml2:AttributeStatement>
_46
</saml2:Assertion>

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


Save Application information and copy Application details

save-application-information-and-copy-application-details page anchor

If you didn't finish your setup the first time, you can navigate to Applications > Applications in the Okta Admin Console and select your active application.

Select the Sign On tab. Click "View Setup Instructions". You will need this information to configure Flex to use your Okta application.


Configure Flex with your new SAML credentials

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

Next, configure SSO on the Flex Console Single Sign-on settings page(link takes you to an external page). You will need the following fields from the Okta Setup Instructions page:

Twilio SSO FieldOkta Setup Instructions 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

create-your-application-users page anchor

You can add an Okta user individually by navigating to Directory > People and clicking Add person, or you can import a group from a CSV by selecting "Import users from CSV" on the More actions dropdown. Make sure that you assign a Flex role to your Okta application users, leveraging the user attribute defined for the "roles" SAML claim.

Available Flex roles are agent, admin, and supervisor. You may add multiple roles for a user by separating their various roles with commas.

(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.

One way to assign a role would be to:

  1. Navigate to Directory > People , select the user, and click on the Profile tab.
  2. Edit the attribute defined for the "roles" SAML claim with the Flex roles you want to assign to the user.

After you've defined the role(s) for a user, Flex will update the Worker attributes with each successful SSO authentication.


Ensure Users in Directory are assigned to the application

ensure-users-in-directory-are-assigned-to-the-application page anchor

To assign your newly created Okta application to a user, navigate to Applications > Applications and click Assign Users to app.

sso-assign-application.

Select the application and the users you want to add then click Next. You may enter user-specific attributes. If you are defining a custom username, ensure it is unique. When you are ready, click Confirm Assignments.


Additional Configuration

additional-configuration page anchor

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 attributes that can be defined for each identity.


Navigate to the Flex Console Single Sign-on settings page(link takes you to an external page). You can click "Login with SSO", or copy the login link and paste it into your browser address bar, which will redirect you to the identity provider (IdP) login page.

Use the credential of the test user you created in the previous steps. Depending on the user settings, you may be requested to set your password. Once the authentication is completed, you will be redirected to the Flex UI. What you can see depends on the Flex role(s) set in the IdP user profile.

You can 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 such as email and assigned role(s).


Flex application unassigned

flex-application-unassigned page anchor

If the user is not assigned the Flex application in Okta, you will see the following error message:

"Sorry, you can't access Twilio Flex because you are not assigned this app in Okta."


Rate this page: