Configure Auth0 IdP with Twilio Flex

Auth0 is a platform that provides authentication as a service. Instead of managing your own user’s credentials, Auth0 can take care of that for you. In this guide, you will learn how you can configure Auth0 as a SAML Identity Provider with Flex. To learn more about how Auth0 works, visit the official Auth0 overview page.

Create an Application on Auth0

1. Navigate to the Applications page, and click Create Application.
2. Enter a name for your application, select Regular Web Applications as the application type, then click Create.
3. Select the Addons tab, then click on SAML2 Web App.
4. Click on the Settings tab and enter the Application Callback URL with the following URL: https://iam.twilio.com/v1/Accounts/ACXXXXXXXXX/saml2. Replace ACXXXXXXXXX with your Account SID, which you can find on the Twilio Console.
5. Copy and paste the SAML Protocol Settings in the Addons Settings:

   {
     "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
     "signResponse": true
   }​

6. Click on Usage and download a copy of your Auth0 certificate.
7. To save your settings, scroll down and click the Enable button, then click Save.
8. Select Settings.
9. Scroll down to Application URIs, and add https://iam.twilio.com/v1/Accounts/ACXXXXXXXXX/saml2/metadata to the Allowed Callback URLs. Remember to replace ACXXXXXXXXX with your own Account SID.

   

10. Scroll down to Advanced Settings and select the Endpoints tab. Copy the SAML Protocol URL and Save the settings.

    

Create an Authentication Rule

Authentication rules are JavaScript functions that execute when a user successfully authenticates themselves with your application. They can be customized and extend the default capabilities provided by Auth0 out of the box. To learn more about rules and how they work, visit the official Auth0 docs on Authentication Rules.

1. Go to Auth Pipeline on the sidenav, then click “Rules”.
2. Click + Create.
3. Select Empty rule.
4. Enter a Name for the Authentication Rule and add the following script:

   function (user, context, callback) {
    context.samlConfiguration.mappings={
       "email":"email",
       "full_name": "name",
       "first_name": "given_name",
       "last_name": "family_name",
       "image_url": "picture",
       "roles": "app_metadata.flex.roles"
     };
     console.log(context.samlConfiguration);
     callback(null, user, context);
   }

   Note For the roles property, this must be configured when creating a new User. Please refer to the Adding a User step and make sure you configured the necessary roles for your user.
5. Click Save changes.

Adding a User

1. Go to User Management and click on Users.
2. Click + Create User.
3. Fill in the Email, Password, and any required user details and then click Create.
4. Scroll down to app_metadata and assign the required roles (agent, admin or supervisor).
   Example:

   {
     "flex" : {
       "roles" : ["admin"]
     }
   }

   Note If you do not configure the roles for the user, the Authentication Rule created from earlier will fail.
5. Click Save.

Configure Flex with your SAML credentials

1. Navigate to Twilio Console > Flex > Single Sign-On
2. Under X.509 Certificate, copy and paste the contents of the Auth0 certificate you downloaded earlier. You can read the .pem file by using the cat command in your command prompt or terminal. For example: cat ./name/of/certificate-file.pem
3. For Identity Provider Issuer, go to Applications > Your App > Addons > SAML2 Web App. Click Usage, and copy the value of “Issuer”.
4. For Single Sign-On URL, paste the url for the SAML Protocol URL that you copied from Configure Auth0 IdP with Flex, step 8. Be sure to also append the query string at the end: `?connection=Username-Password-Authentication`
5. For the Twilio SSO URL, select the USES IAM.TWILIO.COM option.
6. Add your trusted domain which you can find under your application’s settings, and copy the value under “Domain”.
7. Turn on Login Using Popup.
8. Click Save to save your settings.
9. If everything was done correctly, your settings should look something like this