Objective

This article explains how to configure Single Sign-On (SSO) for Twilio Flex plugins when developing and testing on localhost. If you are unable to sign in to the Flex UI using SSO while running plugins locally, follow these steps to ensure your SSO and OAuth settings are correct and that localhost is properly registered as a trusted URL. This guide uses keywords such as Flex, SSO, localhost, appConfig.js, and login to help you find solutions to SSO authentication issues during local plugin development.

Product

Flex

Environment

Twilio Console

User Account Permission/Role(s) Required 

Admin access to Flex SSO settings in the Twilio Console as well as access to Plugin deployments in Twilio Flex

Procedure 

1. Update appConfig.js for Each Plugin

   • In your plugin’s public directory, open or create the appConfig.js file.

   • Add or update the sso and oauth configuration blocks. Example:

     var appConfig = {
       pluginService: {
         enabled: true,
         url: '/plugins',
       },
       sso: {
         accountSid: 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', // Your Twilio Account SID
         redirectUrl: 'http://localhost:3000/login/callback' // Use your local port if different
       },
       oauth: {
         connection: 'YOUR_CONNECTION_NAME',
         clientId: 'YOUR_CLIENT_ID',
         redirectUrl: 'http://localhost:3000'
       }
     };

   • Ensure the redirectUrl matches your local development port.

2. Register Localhost as a Trusted URL

   • In the Twilio Console, navigate to Flex > Users and access > Single sign-on (SSO).
   • Add your local development URL (e.g., http://localhost:3000) to the Trusted URLs section.
   • Set the Default redirect URL to your localhost address if testing locally.

3. Restart Your Local Plugin Server

   • After making changes to appConfig.js, restart your local development server to apply the new configuration.

4. Troubleshoot SSO Login Issues

   • If SSO login still fails, use a tool like SAML Tracer (Chrome extension) to capture the authentication flow and identify issues with SAML responses or redirect URLs.
   • Double-check that all plugins you wish to test locally have the updated configuration.

Additional Information

• Each plugin you run locally must have the correct SSO and OAuth configuration in its own appConfig.js file to support SSO login.
• For more details, see the official documentation: Configure SSO for Self-Hosted Flex
• Related article: Getting Started with Flex Plugins