Embedded AI Assistant: Multi-SSO Configuration Guide

Overview

This guide explains how to configure the Embedded AI Assistant to support multiple SSO identity providers (IdPs), enabling different user populations to authenticate through different SSO providers while accessing the same Moveworks bot.

Common Use Cases:

• Multiple Azure AD tenants (e.g., Commercial and Government Cloud)
• Supporting acquired companies with separate identity providers
• Different SSO providers for different regions or business units
• Legacy and modern authentication systems running in parallel

How Multi-SSO Works

The Embedded AI Assistant uses an auth_key parameter to determine which SSO configuration to use for each user. The flow works as follows:

1. Configuration in Moveworks Setup: Create multiple SSO configs and Embedded AI Assistant Auth configs, each with a unique auth_key
2. Runtime Selection: The embedding application passes the appropriate auth_key when loading the Embedded AI Assistant
3. SSO Redirect: The Embedded AI Assistant redirects the user to the correct IdP based on the auth_key
4. Authentication: User authenticates with their designated IdP
5. Bot Access: User returns to the application with the Embedded AI Assistant successfully loaded

The auth_key Parameter

The auth_key is an arbitrary identifier you define that connects:

• The Embedded AI Assistant Auth configuration in Moveworks Setup
• The embedding application's initialization code

Example:

• Moveworks Setup: Auth Config with auth_key = "subsidiary"
• Application: Loads Embedded AI Assistant with ?auth_key=subsidiary parameter

Configuration Steps

Step 1: Create SSO Configurations

Navigation: Setup → Organization Details → SSO

For each identity provider, create a separate SSO configuration:

1. Click "Add New SSO Config"
2. Set Moveworks Product to movewebchat
3. Select your connector (Okta, Azure AD, Ping, etc.)
4. Choose protocol (SAML or OIDC)
5. Configure IdP settings:
   • IDP Issuer: Your IdP's issuer URL
   • IDP Client ID: Application client ID from IdP
   • IDP Client Secret: Application secret from IdP
   • IDP Redirect URI: The callback URL (typically https://<your-domain>/login/sso/oidc)
   • User Attribute: Attribute to match users (typically email)
   • Identifier Type: How to identify users (EMAIL_ADDR, IDM_USER_ID, etc.)

Important: The redirect URI must match exactly what's configured in your IdP's application settings.

Repeat this process for each identity provider.

Step 2: Create Embedded AI Assistant Auth Configurations

Navigation: Setup → Web Chatbot → Auth Settings

For each SSO configuration created above, create a corresponding Auth config:

1. Click "Add New Auth Config"
2. Set Auth Key: Choose a descriptive identifier
   • First/primary configuration should use "default"
   • Additional configurations: use descriptive names (e.g., "subsidiary", "region2", "legacy")
   • Must be lowercase alphanumeric only
3. Set Auth Type: Select "Generic SSO"
4. SSO Config: Select the corresponding SSO config from Step 1
5. Save the configuration

Example Configuration:

Step 3: Configure Azure AD Applications (or equivalent IdP)

For each identity provider, ensure the application registration is configured:

1. Redirect URI: Must match the idp_redirect_uri in Moveworks Setup
2. Client Secret: Must be valid and not expired
3. API Permissions: Ensure proper permissions are granted
4. Token Configuration: Verify required claims are included

Step 4: Configure the Embedding Application

The application embedding the Embedded AI Assistant must determine which auth_key to use for each user and pass it when initializing the assistant.

Determining the auth_key

The embedding application needs logic to identify which IdP each user should use. Common approaches:

Option A: User Attribute

// Check user's department, company, or custom field
if (user.company === "Subsidiary Inc") {
    authKey = "subsidiary";
} else {
    authKey = "default";
}

Option B: Email Domain

// Route based on email domain
if (user.email.endsWith("@subsidiary.com")) {
    authKey = "subsidiary";
} else {
    authKey = "default";
}

Option C: Group Membership

// Check user's group or role
if (user.groups.includes("Legacy-Auth-Users")) {
    authKey = "legacy";
} else {
    authKey = "default";
}

Passing the auth_key to the Embedded AI Assistant

Method 1: URL Parameter

<iframe src="https://your-moveworks-domain/chat?auth_key=subsidiary"></iframe>

Method 2: JavaScript Initialization

Moveworks.init({
    domain: 'your-moveworks-domain',
    authKey: 'subsidiary'
});

Method 3: Script Tag with Query Parameter

<script src="https://your-moveworks-domain/chat-client.js?auth_key=subsidiary"></script>

Identity Considerations

When using multiple SSO providers, ensure users can be uniquely identified across systems:

Consistent User Identifiers

Users authenticating through different IdPs must map to the same user record in your ITSM/IDAM systems.

Best Practice Options:

1. Employee ID (Recommended): Use a consistent employee ID across all IdPs and systems
2. Email Normalization: Ensure email addresses are consistent or use converters to normalize them
3. Custom Attribute: Use a custom user attribute that's consistent across all systems

Example Identity Flow

User A authenticates via Subsidiary IdP
└─> Returns email: [email protected]
    └─> Moveworks maps to ITSM user: [email protected]
        └─> User accesses their tickets, knowledge, etc.

This mapping typically requires configuration in the identity ingestion settings.

Testing & Validation

Test Each SSO Configuration

1. Test User Setup: Identify test users for each IdP
2. Clear Browser Cache: Ensure clean test environment
3. Test Authentication Flow:
   • Access the Embedded AI Assistant with the appropriate auth_key
   • Verify redirect to correct IdP
   • Complete authentication
   • Verify assistant loads successfully
4. Test Bot Functionality: Ensure the assistant works correctly after authentication

Validation Checklist

• Each SSO config created in Moveworks Setup with correct IdP settings
• Each Auth config created with unique auth_key values
• IdP applications configured with matching redirect URIs
• Embedding application logic determines correct auth_key per user
• Embedding application passes auth_key to Embedded AI Assistant correctly
• Test users authenticate successfully through each IdP
• Assistant loads and functions correctly for all user populations
• User identity maps correctly to ITSM/other systems

Common Issues & Troubleshooting

Issue: Bot doesn't load after SSO redirect (302 redirect loop)

Symptoms:

• User completes SSO authentication
• Gets redirected back to the application
• Bot fails to render or initialize

Possible Causes:

1. Redirect URI mismatch: Moveworks Setup config doesn't match IdP application settings
2. Missing auth_key: Application not passing auth_key parameter
3. Incorrect auth_key: Application passes wrong auth_key value
4. CSP/CORS issues: Security policies blocking Embedded AI Assistant iframe

Solutions:

• Verify redirect URI matches exactly in both Moveworks Setup and IdP
• Check browser network tab for the auth_key parameter in requests
• Verify auth_key value matches an existing Auth config in Moveworks Setup
• Check browser console for CSP/CORS errors

Issue: Wrong IdP is used for authentication

Symptoms:

• User is redirected to incorrect IdP
• Authentication succeeds but user has wrong identity

Possible Causes:

1. Missing or default auth_key: Application not passing correct auth_key
2. Logic error: User determination logic in embedding application is incorrect

Solutions:

• Verify embedding application logic correctly identifies user's IdP
• Add logging to confirm correct auth_key is being passed
• Test with users from each population to verify routing

Issue: Bot works for some users but not others

Symptoms:

• Primary IdP users can use bot successfully
• Secondary IdP users cannot authenticate or bot doesn't load

Possible Causes:

1. Incomplete configuration: Secondary SSO config not fully set up
2. Expired credentials: Client secret or certificate expired for secondary IdP
3. Identity mapping failure: Users from secondary IdP not mapping to ITSM

Solutions:

• Verify all SSO configs are complete and active
• Check client secrets and certificates for expiration
• Review identity ingestion logs for mapping errors
• Verify test users from secondary IdP exist in ITSM

Issue: Authentication succeeds but user sees "Unauthorized" or empty chat

Symptoms:

• SSO authentication completes successfully
• Bot loads but shows error or empty state

Possible Causes:

1. Identity mismatch: User authenticated but not found in Moveworks roster
2. Missing channel ID: User record doesn't have Embedded AI Assistant channel information
3. Permission issues: User doesn't have access to the Embedded AI Assistant

Solutions:

• Check Moveworks roster for the authenticated user
• Verify user record includes Embedded AI Assistant/web channel identity information
• Review user access permissions and licenses

Best Practices

Planning

1. Document user populations: Clearly define which users should use which IdP
2. Test with real users: Validate with actual users from each population before rollout
3. Plan identity mapping: Ensure user identity strategy works across all systems
4. Consider future changes: Plan for adding additional IdPs or migrating users

Naming Conventions

1. Use descriptive auth_keys: "subsidiary" is better than "config2"
2. Document auth_key usage: Maintain documentation of which auth_key serves which population
3. Use "default" for primary: The primary/largest user population should use auth_key = "default"

Security

1. Rotate secrets regularly: Update IdP client secrets on a regular schedule
2. Monitor authentication logs: Watch for unusual authentication patterns
3. Test after changes: Validate after any SSO or IdP configuration changes
4. Use OIDC over SAML: When possible, prefer OIDC for better security and features

Maintenance

1. Monitor certificate expiration: Set up alerts for expiring certificates and secrets
2. Test regularly: Periodically test authentication flows for all IdPs
3. Document changes: Keep configuration documentation up to date
4. Review access logs: Regularly review authentication and access logs

Support

For assistance with multi-SSO configuration, contact Moveworks Support with:

• SSO configuration details (screenshots with sensitive data redacted)
• IdP application settings
• Test user examples from each population
• Browser console logs and network traces
• Error messages and authentication flow descriptions