OKTA SSO Configuration (Legacy)

Documentation for OKTA SSO integration with Twilio Flex.

Not Currently Used

Current Status: ThreadConnect currently uses Auth0 for SSO. OKTA integration is not actively deployed.

This documentation is preserved for:

Historical reference
Future migration path if needed
Demonstrating ThreadConnect's multi-provider support

🎯 Purpose

This legacy documentation demonstrates that ThreadConnect supports both Auth0 and OKTA as identity providers. The architectural patterns and principles described in this authentication section apply to OKTA as well as Auth0.

Current Recommendation: Use Auth0 Configuration for active deployments.

🏗️ OKTA Architecture Overview

OKTA integration follows the same SAML-based SSO pattern as Auth0:

Key Similarity: Both Auth0 and OKTA use SAML 2.0 for Flex integration.

📋 OKTA vs Auth0 Comparison

Feature	Auth0	OKTA	Notes
SAML 2.0 Support	✅ Yes	✅ Yes	Both use same protocol
Pattern A Support	✅ Yes	✅ Yes	Multi-program with teams
Pattern B Support	✅ Yes	✅ Yes	Isolated organizations
Attribute Mapping	Via Actions	Via Attribute Statements	Different implementation
User Metadata	`app_metadata`	Custom Attributes	Different storage
Current Deployment	✅ Active	⚠️ Not Used	Auth0 preferred currently

🔧 OKTA Configuration Overview

If migrating to OKTA in the future, the configuration would involve:

1. OKTA Application Setup

Create SAML 2.0 application in OKTA
Configure with Flex SAML endpoints
Set audience and recipient URLs

2. Attribute Mapping

Map OKTA user attributes to Flex requirements:

Flex Requirement	OKTA Attribute
`email`	`user.email`
`full_name`	`user.firstName + user.lastName`
`roles`	`user.flexRoles` (custom attribute)
`team`	`user.flexTeam` (custom attribute, Pattern A)

3. Custom Attributes in OKTA

Would need to create:

flexRoles - String array for role assignment
flexTeam - String for team assignment (Pattern A)
flexProgram - String for usage tracking (Pattern A)

4. OKTA Groups vs Team Attributes

OKTA offers two approaches:

Groups: Map OKTA groups to Flex teams
Custom Attributes: Similar to Auth0 approach

📖 Historical Context

Why Auth0 is Currently Used

ThreadConnect initially evaluated both OKTA and Auth0 for SSO integration. Auth0 was selected for current deployments due to:

Rapid prototyping and development flexibility
Simpler custom attribute management via Actions
Cost structure for nonprofit clients
Developer experience and documentation

Important: This was a pragmatic choice for current needs, not a permanent commitment. ThreadConnect architecture remains identity-provider agnostic.

🔄 Migration Path: OKTA ↔ Auth0

If future requirements necessitate OKTA:

Auth0 → OKTA Migration

Preparation:

Audit all Auth0 users and metadata
Map Auth0 app_metadata to OKTA custom attributes
Document Auth0 Actions logic for OKTA implementation
Test OKTA configuration in non-production environment

Migration:

Configure OKTA application with Flex SAML
Create OKTA users with appropriate attributes
Update Flex SSO settings to use OKTA metadata
Test with pilot users
Cutover during maintenance window
Monitor for 48 hours

Rollback Plan:

Keep Auth0 configuration for 30 days post-migration
Document rollback steps
Have emergency contacts ready

📊 OKTA Pattern Support

Both Pattern A (Multi-Program) and Pattern B (Isolated Organizations) work with OKTA:

Pattern A with OKTA

Team Segmentation via OKTA:

OKTA Groups:
├── NSS_Admins (no team attribute)
├── NSS_RAMP_Supervisors (team: RAMP)
└── NSS_RAMP_Agents (team: RAMP)

Or via custom attributes:

User: jbuckley@nevadaseniorservices.org
Custom Attributes:
- flexRoles: ["supervisor"]
- flexTeam: "RAMP"
- flexProgram: "RAMP"

Pattern B with OKTA

Separate OKTA Tenants:

Organization A → OKTA Tenant A → Flex Instance A
Organization B → OKTA Tenant B → Flex Instance B

Complete isolation achieved same as Auth0 Pattern B.

🔐 OKTA-Specific Features

Advantages of OKTA

If migrating to OKTA, these features would be available:

Universal Directory:

Centralized user management across applications
Automated user provisioning/deprovisioning
Advanced user lifecycle management

Advanced Security:

Adaptive Multi-Factor Authentication
Risk-based authentication
Detailed security event logging

Enterprise Integration:

Pre-built integrations with enterprise tools
Directory integration (Active Directory, LDAP)
HR system integration (Workday, BambooHR)

Compliance:

SOC 2, ISO 27001 certified
HIPAA compliance features
FedRAMP authorized (government clients)

🆘 OKTA Documentation References

If implementing OKTA in the future:

Official OKTA Docs:

Twilio Flex + OKTA:

Configure OKTA SSO with Flex

📝 OKTA Reference Implementation

For future implementation reference:

OKTA Attribute Statements (SAML)

Pattern A (Multi-Program):

Name: email
Value: user.email

Name: full_name
Value: String.append(user.firstName, " ", user.lastName)

Name: roles
Value: user.flexRoles

Name: team
Value: user.flexTeam

Name: program
Value: user.flexProgram

Pattern B (Isolated Organizations):

Name: email
Value: user.email

Name: full_name
Value: String.append(user.firstName, " ", user.lastName)

Name: roles
Value: user.flexRoles

✅ Validation That OKTA Would Work

ThreadConnect's authentication architecture was designed with provider agnosticism in mind:

Evidence:

✅ SAML 2.0 standard protocol (OKTA supports)
✅ Pattern A and B are protocol-agnostic
✅ Attribute mapping flexible (both providers support)
✅ Team segmentation works via attributes or groups
✅ Twilio Flex officially supports OKTA

Confidence Level: High confidence OKTA would work if needed.

🎯 When to Consider OKTA

Scenarios where OKTA might be preferred:

Enterprise Requirements
- Client already has OKTA deployment
- Enterprise-wide SSO strategy requires OKTA
- Compliance requirements favor OKTA
Scale Considerations
- Managing 1000+ users across multiple organizations
- Complex directory integration needs
- Advanced security requirements (adaptive MFA)
Government/Healthcare
- FedRAMP authorization required
- HIPAA compliance with specific OKTA features
- Government contractor requirements

Current Deployments: Auth0 meets all current nonprofit client needs.

Current Standard: Auth0 Configuration
Architecture Overview: Identity & Multi-Tenant Architecture
Pattern A: Multi-Program Setup
Pattern B: Isolated Organizations

📞 Contact

Considering OKTA for your deployment?

Before implementing OKTA:

Review Decision Matrix for pattern choice
Consult with ThreadConnect CTO on implementation strategy
Consider Auth0 vs OKTA for your specific requirements
Document rationale for provider choice

Professional Services: OKTA integration implementation available. Contact your ThreadConnect representative for details.

Future-Proofing

This documentation exists to demonstrate ThreadConnect's provider-agnostic architecture. We can support OKTA or Auth0 based on client needs, not vendor lock-in.

Core Principle: Identity provider is a configuration choice, not an architectural constraint.

Currently Using Auth0?

You're in the right place! Follow the Auth0 Configuration Guide for active deployment documentation.

🎯 Purpose​

🏗️ OKTA Architecture Overview​

📋 OKTA vs Auth0 Comparison​

🔧 OKTA Configuration Overview​

1. OKTA Application Setup​

2. Attribute Mapping​

3. Custom Attributes in OKTA​

4. OKTA Groups vs Team Attributes​

📖 Historical Context​

Why Auth0 is Currently Used​

🔄 Migration Path: OKTA ↔ Auth0​

Auth0 → OKTA Migration​

📊 OKTA Pattern Support​

Pattern A with OKTA​

Pattern B with OKTA​

🔐 OKTA-Specific Features​

Advantages of OKTA​

🆘 OKTA Documentation References​

📝 OKTA Reference Implementation​

OKTA Attribute Statements (SAML)​

✅ Validation That OKTA Would Work​

🎯 When to Consider OKTA​

📖 Related Documentation​

📞 Contact​