Configure Okta IdP with Flex

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.

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.

1. Follow Okta's documentation to create a SAML app integration.
2. On the Create SAML Integration page, enter the following general settings. Make sure to click Show Advanced Settings to access all the fields:

Expand image

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.

1. 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 also populated.

You can optionally add the following attribute:

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>

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

To locate your Okta application details, refer to Okta's documentation for managing signing certificates.

1. In Twilio Console, go to Flex > Users and access > Single sign-on (SSO).
2. Using the application details from the previous section, add the following information:

Expand image

Follow Okta's documentation to add users manually, import users from an app, or import users from a CSV file.

Assign a Flex role to your Okta application users by leveraging the user attribute defined for the "roles" SAML claim.

To assign a role:

1. Navigate to Directory > People, select the user, and click the Profile tab.
2. In Attributes, edit the User type attribute to specify the roles that you want to assign to your Flex user. Available Flex roles are agent, admin, and supervisor. To assign multiple roles, use a comma-separated list.

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

To assign users to your application in Okta, follow Okta's documentation to assign app integrations.

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 (SSO) 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 to review other attributes, like email and assigned roles.

See Configuring SSO to learn more about:

• Initiating login from your IdP
• Logging in to a self-hosted domain
• Defining attributes for each identity