Zuvo Docs

Guide

Multiple SSO Providers

Configure multiple SSO providers for different environments, teams, or use cases

Many enterprises need multiple single sign-on (SSO) providers configured within Zuvo to support different environments, teams, or organizational structures. This guide explains when and how to set up multiple providers effectively.

Why multiple SSO providers?

Common scenarios requiring multiple SSO providers include:

  • Multiple environments: Separate Dev, Staging, and Production organizations
  • Team separation: Different business units or departments
  • Migration: Transitioning from one identity provider to another
  • Acquisitions: Integrating subsidiaries with different identity systems
  • Testing: Isolated test environments alongside production

Key concept: IDP-initiated enables unlimited providers per domain

The traditional challenge with multiple SAML apps is domain conflicts. With SP-initiated flow only, each SAML app requires a unique email domain. Since all your employees use the same domain (e.g., company.com), this creates a problem.

Solution: Use identity provider (IdP)-initiated flow, which doesn't require domain configuration. You can create unlimited SAML apps under the same domain.

Use case 1: Multiple environments (dev/staging/prod)

This is the most common enterprise pattern and the primary use case for IDP-initiated flow.

The challenge

You have three Zuvo organizations:

  • Development (dev-org)
  • Staging (staging-org)
  • Production (prod-org)

All employees use company.com email addresses. You need separate SSO configurations for each environment.

The solution

Create three separate SAML apps in your identity provider, each pointing to a different Zuvo organization.

In your identity provider (Okta, Azure AD, Google Workspace)

  1. Create "Zuvo Dev" SAML app

    • Configure with Dev organization's ACS URL
    • Assign developers and testers
    • Deploy app tile labeled "Zuvo Dev"

  2. Create "Zuvo Staging" SAML app

    • Configure with Staging organization's ACS URL
    • Assign QA team and release managers
    • Deploy app tile labeled "Zuvo Staging"

  3. Create "Zuvo Production" SAML app

    • Configure with Production organization's ACS URL
    • Assign production users only
    • Deploy app tile labeled "Zuvo Production"

In each Zuvo organization

  1. Navigate to the SSO settings section of the dashboard
  2. Enable Single Sign-On
  3. Leave Enable SP-initiated login "OFF", this is critical
  4. Configure metadata from the corresponding IDP app
  5. Set up attribute mappings
  6. Configure auto-join if desired

Result

  • Users click the appropriate app tile for the environment they need
  • No domain conflicts (all apps use company.com)
  • Clean isolation between environments
  • Each environment can have different user assignments and roles

Configuration example

Here's how the three configurations differ:

EnvironmentOrganizationIDP App NameACS URL
Devdev"Zuvo Dev"https://...dev-org.../saml/acs
Stagingstaging"Zuvo Staging"https://...staging-org.../saml/acs
Productionprod"Zuvo Prod"https://...prod-org.../saml/acs

Each organization

  • SP-initiated: OFF (no domains configured)
  • IDP-initiated: ON (automatic, no configuration needed)
  • Auto-join: Your preference (typically enabled for dev, disabled for prod)

Use case 2: Different teams or business units

Some organizations need to isolate teams within separate Zuvo organizations.

Example scenario

  • Engineering team uses engineering-org
  • Data team uses data-org
  • Both teams have company.com emails

Configuration approach

Option A: IDP-initiated with different app tiles

Create separate SAML apps in your IDP:

  • "Zuvo Engineering" → Points to engineering-org
  • "Zuvo Data" → Points to data-org

Assign appropriate users to each app. Users only see the tiles they're assigned to.

Option B: Both IDP and SP-initiated with role-based routing

Configure both organizations with SP-initiated enabled using the same domain:

  • Both organizations add company.com as a domain
  • Users can log in via SP-initiated at zuvodev.com
  • System routes based on org membership (first match wins)
  • Also provide IDP tiles for explicit routing

Use case 3: Migration from one IDP to another

When migrating from one identity provider to another, multiple providers help ensure a smooth transition.

Migration workflow

Phase 1: Dual configuration

  1. Configure new IDP as additional SSO provider
  2. Keep existing IDP active
  3. Test new IDP with small group
  4. Both providers operational simultaneously

Phase 2: Gradual rollout

  1. Migrate users in batches to new IDP
  2. Update app tile assignments
  3. Monitor for issues
  4. Keep old IDP as fallback

Phase 3: Cutover

  1. Move all users to new IDP
  2. Verify no users depend on old IDP
  3. Disable (don't delete) old IDP provider
  4. Monitor for any issues

Phase 4: Cleanup

  1. After verification period (1-2 weeks)
  2. Delete old IDP provider
  3. Update documentation

Use case 4: Acquisitions and subsidiaries

Organizations with multiple email domains need provider configurations for each domain.

Example scenario

  • Parent company: parent.com
  • Subsidiary 1: subsidiary1.com
  • Subsidiary 2: subsidiary2.com

All authenticate through the same central IDP but use different email domains.

Configuration approach

Option A: Single provider with multiple domains (SP-initiated)

  1. Enable SSO with SP-initiated flow
  2. Add all domains: parent.com, subsidiary1.com, subsidiary2.com
  3. Configure single IDP metadata
  4. Users with any matching domain can log in via zuvodev.com

Option B: Separate providers per subsidiary (IDP-initiated)

  1. Create separate SAML apps for each entity
  2. Configure as IDP-initiated only
  3. Assign users based on their subsidiary
  4. More isolation, clearer organization boundaries

Step-by-step setup guide

For IDP-initiated multi-environment pattern

This is the recommended pattern for most enterprises.

Step 1: Plan your environments

Document:

  • Organization names and slugs
  • Environment purposes (dev, staging, prod)
  • Which users need access to which environments
  • Default roles for each environment

Step 2: Create SAML apps in your IDP

For each environment, follow your provider-specific guide to create a SAML app:

Naming convention example

  • "Zuvo - Production"
  • "Zuvo - Staging"
  • "Zuvo - Development"

Use consistent naming to help users identify the right environment.

Step 3: Configure each Zuvo organization

For each organization:

  1. Navigate to the SSO settings section of the dashboard
  2. Enable Single Sign-On
  3. Verify Enable SP-initiated login is "OFF"
  4. Upload or paste metadata from the corresponding IDP app
  5. Configure attribute mappings:
    • Email (required): Map to email
    • Name (optional): Map to name or displayName
  6. Configure auto-join settings:
    • Dev: Usually enabled with "Developer" role
    • Staging: Usually enabled with "Developer" role
    • Prod: Usually disabled (explicit invitations only)
  7. Save configuration

Step 4: Test each environment separately

For each environment:

  1. Open your IDP dashboard (Okta, Azure, Google)
  2. Click the corresponding app tile
  3. Verify redirect to correct Zuvo organization
  4. Check that user information is populated correctly
  5. Verify auto-join behavior (if enabled)

See the SSO Testing and Best Practices guide for comprehensive testing procedures.

Step 5: Assign users in your IDP

Configure app assignments in your IDP:

  • Production: Only production users (restrictive)
  • Staging: QA team, release managers, senior engineers
  • Development: All engineers and testers (permissive)

Users only see app tiles they're assigned to.

Step 6: Document and communicate

Create documentation for your team:

  • Which app tile corresponds to which environment
  • Access request process for each environment
  • Naming conventions and organization structure
  • Emergency access procedures (non-SSO owner account)

User access management

IDP app assignment strategies

Per-environment access control

Control who can access each environment by managing app assignments in your IDP:

Engineering Team:
├─ Zuvo Dev (assigned) ✅
├─ Zuvo Staging (assigned) ✅
└─ Zuvo Prod (assigned) ✅

QA Team:
├─ Zuvo Dev (assigned) ✅
├─ Zuvo Staging (assigned) ✅
└─ Zuvo Prod (NOT assigned) ❌

Contractors:
├─ Zuvo Dev (assigned) ✅
├─ Zuvo Staging (NOT assigned) ❌
└─ Zuvo Prod (NOT assigned) ❌

Role assignment patterns

Option 1: Different default roles per environment

  • Dev: Auto-join with "Administrator" role (developers need full control)
  • Staging: Auto-join with "Developer" role
  • Prod: No auto-join, explicit invitations with "Read-only" or "Developer"

Option 2: Consistent roles, manual promotion

  • All environments: Auto-join with "Developer" role
  • Promote to "Administrator" or "Owner" manually as needed
  • Provides consistent baseline, explicit elevation

Option 3: No auto-join, explicit control

  • All environments: Auto-join disabled
  • Send explicit invitations with appropriate roles
  • Maximum control, more management overhead

Choose based on your organization's security posture and operational preferences.

Best practices

Naming conventions

IDP app names

Use consistent, descriptive names that clearly indicate the environment:

  • ✅ "Zuvo - Production"
  • ✅ "Zuvo Prod"
  • ❌ "Zuvo" (ambiguous)
  • ❌ "SUPA_PROD" (unclear abbreviation)

Zuvo organization names

Match your IDP app names when possible:

  • IDP app: "Zuvo - Production" → Org: acme-production
  • IDP app: "Zuvo - Staging" → Org: acme-staging
  • IDP app: "Zuvo - Dev" → Org: acme-development

Configuration synchronization

Keep critical settings synchronized across environments:

  • Attribute mappings: Should be identical across all providers
  • Certificate settings: Coordinate renewals across all environments
  • Safety accounts: Each org needs a non-SSO owner account

Configuration drift checklist

  • Attribute mappings match across environments
  • Certificate expiration dates documented for all providers
  • Non-SSO owner accounts exist in all organizations
  • Auto-join settings are intentional (not accidental)
  • Default roles appropriate for each environment

Testing in lower environments first

Always test SSO changes in non-production environments:

  1. Make change in Dev environment
  2. Test thoroughly (see testing guide)
  3. Deploy to Staging and verify
  4. Monitor for issues (1-2 days)
  5. Deploy to Production during low-usage period
  6. Monitor closely after production deployment

Security considerations

Environment isolation

  • Never reuse metadata between environments (security risk)
  • Each environment should have unique ACS URLs
  • Verify IDP app assignments are correct (don't give prod access accidentally)

Access reviews

  • Quarterly review of who has access to production
  • Verify IDP app assignments are up to date
  • Remove access for users who have changed roles
  • Audit auto-join configurations (still appropriate?)

Break-glass access

Each organization must have at least one non-SSO owner account:

  • Create dedicated "break-glass" accounts
  • Store credentials in secure password manager
  • Test these accounts regularly (quarterly)
  • Document emergency access procedures

Troubleshooting

Users accessing the wrong environment

Symptom

User clicks "Zuvo Prod" tile but sees the dev environment.

Causes

  • Metadata configured incorrectly (swapped between environments)
  • ACS URL points to wrong organization
  • User has bookmarked the wrong organization

Solution

  1. Verify ACS URL in IDP app configuration
  2. Compare metadata in Zuvo SSO settings
  3. Check that organization slug matches expected environment
  4. Have user clear browser cookies and try again
  5. Verify user is clicking correct app tile

Configuration drift between environments

Symptom

SSO works in dev but fails in staging or production.

Causes

  • Attribute mappings differ between providers
  • Certificate expired in one environment but not others
  • Domain configuration inconsistent (if using SP-initiated)

Solution

  1. Compare SSO configurations side-by-side
  2. Check attribute mappings are identical
  3. Verify certificate expiration dates
  4. Test with same user account across all environments
  5. Review IDP audit logs for authentication failures

Users don't see expected app tiles

Symptom

User cannot find "Zuvo Staging" tile in IDP dashboard.

Causes

  • User not assigned to the app in IDP
  • App not deployed/published in IDP
  • User looking in wrong place (different IDP portal)

Solution

  1. Verify app assignment in IDP admin console
  2. Check app is published/active
  3. Confirm user has logged out and back into IDP
  4. Verify user is checking correct IDP portal (some organizations have multiple)

Auto-join adding users to wrong organization

Symptom

User joins dev environment when they should join production.

Cause

User clicked wrong app tile, auto-join is enabled.

Prevention

  • Disable auto-join in production (explicit invitations only)
  • Use clear app tile naming
  • Document which tile corresponds to which environment
  • Consider using different IDP groups for different environments

Remediation

  1. Remove user from incorrect organization
  2. Send explicit invitation to correct organization
  3. Educate user on correct app tile to use
  4. Consider disabling auto-join to prevent recurrence

Multiple organizations with same domain (SP-initiated confusion)

Symptom

With SP-initiated enabled and same domain in multiple organizations, users get routed to unexpected organization.

Cause

SP-initiated routing uses first matching provider.

Solution

  • Recommended: Switch to IDP-initiated only (disable SP-initiated)
  • Remove domain configuration from all but one organization
  • Provide clear IDP app tiles for explicit routing
  • Document which organization users should access via SP-initiated

Migration from single to multiple providers

If you currently have a single SSO provider and need to add more:

Phase 1: Planning

  1. Decide which pattern to use (environments, teams, etc.)
  2. Document new organization structure
  3. Identify users for each environment
  4. Plan user communication strategy

Phase 2: Create new organizations

  1. Create additional Zuvo organizations
  2. Configure projects within each organization
  3. Migrate data if needed (see project transfer)

Phase 3: Configure SSO providers

  1. Create additional SAML apps in your IDP
  2. Configure SSO in each new organization
  3. Start with auto-join disabled
  4. Test with small group

Phase 4: Migrate users

  1. Communicate changes to users
  2. Assign users to appropriate IDP apps
  3. Test that users can access correct environments
  4. Enable auto-join if desired

Phase 5: Decommission old configuration (if applicable)

  1. Migrate all users to new structure
  2. Verify no one depends on old configuration
  3. Disable old SSO provider
  4. Monitor for issues
  5. Delete after verification period

Next steps