For Admins
Twilio Flex SSO

Twilio Flex Single Sign-On

Reps sign in to Twilio Flex with their portal account. The portal acts as the SAML identity provider: Flex sends the sign-in request here, the portal authenticates the user with their normal portal credentials (including OTP where enabled), and sends Flex a signed confirmation of who they are.

There are no separate Flex passwords to manage. The portal's user list is the single source of truth for who can work in Flex.

Who gets access

Access follows the portal role, checked on every sign-in:

Portal roleFlex access
AgentFlex agent
SupervisorFlex supervisor (includes the monitoring UI)
AdminFlex admin
CustomerNo access — sign-in is refused

A user's first Flex sign-in creates their Flex account and worker automatically from the portal record (name, email, role) — there is nothing to pre-provision. Flex re-syncs those details on every subsequent sign-in.

To revoke Flex access, deactivate or discard the user in the portal. They are cut off at their next sign-in. There is no separate Flex user to clean up for access purposes, though a departed rep's Flex/TaskRouter records can be removed in the Twilio Console like any other.

How sign-in flows

  1. The rep opens Flex (directly or inside the CIC Assistant).
  2. Flex redirects them to the portal.
  3. Already signed in to the portal? Flex opens immediately — no prompt. Otherwise they see the normal portal sign-in (email, password, OTP if enabled).
  4. The portal confirms their identity to Flex, and Flex opens with the right role.

Password resets, OTP enrollment, and lockouts are all handled by the portal exactly as for portal sign-in — there is no Flex-specific variant of any of them.

Initial configuration (one-time, admin + Twilio Console access)

  1. In the Twilio Console → Flex → Single sign-on, create the SSO connection and copy its entity ID and ACS URL.
  2. Add both to the portal's production credentials as flex_sso.entity_id and flex_sso.acs_url (or set the FLEX_SSO_ENTITY_ID / FLEX_SSO_ACS_URL environment variables). Changes are picked up without a restart.
  3. Generate a signing certificate and add it as saml_idp.certificate / saml_idp.private_key via bin/rails credentials:edit --environment production.
  4. Back in the Twilio Console, register the portal's metadata URL: https://portal.cicops.ai/saml/metadata.

Until steps 2–3 are done, the SSO endpoints deliberately answer 503 Service Unavailable — the portal never signs with a placeholder key.

Troubleshooting

SymptomLikely cause
Rep reaches the portal sign-in but Flex then shows an errorTheir portal role is Customer, or the Twilio-side connection points at a different entity ID than the portal is configured with
503 Service Unavailable on the SSO pagesSigning certificate or Flex connection values missing from production credentials (configuration steps 2–3)
Rep signs in but lands in Flex with the wrong roleFix the role in the portal; it re-syncs on their next Flex sign-in
Rep keeps their Flex session after being deactivatedSign-out isn't forced mid-session; their access ends at the next sign-in. For immediate removal, deactivate them in the Twilio Console too

Certificate rotation: generate a new keypair, update the credentials, and re-import the portal metadata in the Twilio Console. Do it in a maintenance window — Flex validates against the registered certificate, so the two must change together.

Users & ImpersonationStripe Billing