Hybrid Mode — Bring Your Own IAM

What Is Hybrid Mode?

In hybrid mode, BizFirstGO accepts tokens from both Passport and one or more external IdPs at the same time. The iss (issuer) claim in each token determines which validator is used. This enables:

Gradual migration — move users from Passport to Azure AD in batches, without a big-bang cutover
Mixed user populations — enterprise users on Azure AD, external partners on Passport
Per-tenant IdP selection — some tenants use Okta, others use Passport
IdP comparison — run both for a period to validate the external IdP before full switchover

How Issuer Routing Works

// When a token arrives, Passport reads the "iss" claim (without validating the token)
// and routes to the matching IExternalTokenProvider

// Registered providers:
{
  "https://passport.bizfirst.ai"                      → PassportTokenProvider (built-in)
  "https://company.okta.com/oauth2/default"           → OktaTokenProvider
  "https://login.microsoftonline.com/{tid}/v2.0"      → AzureADTokenProvider
  "https://your-tenant.auth0.com/"                    → Auth0TokenProvider
  "https://keycloak.company.com/realms/company"       → KeycloakTokenProvider
}

// Unknown issuer → reject token immediately (no provider found)

Per-Tenant IdP Configuration

// Configure which IdP is the primary for a tenant
POST /passport/admin/tenants/{tenantId}/identity-config
Authorization: Bearer {admin-token}
Content-Type: application/json

{
  "primaryProvider": "azure-ad",      // tokens from this provider are accepted for this tenant
  "fallbackProviders": ["passport"],  // also accept Passport tokens (for admin/break-glass)
  "allowedIssuers": [
    "https://login.microsoftonline.com/{aad-tenant-id}/v2.0",
    "https://passport.bizfirst.ai"
  ]
}

Migration Pattern (Passport → External IdP)

Phase 1 — Register External IdP (Parallel Mode)

Register Azure AD / Okta as an additional provider. Both Passport and external IdP tokens are accepted. No users are migrated yet. Validate that token validation and claims mapping work correctly.

Phase 2 — Pilot Migration (Batch)

Migrate a pilot group of users to the external IdP. Update their authentication to use Azure AD. Their tokens now carry Azure AD iss. Other users still use Passport tokens. Monitor for issues.

Phase 3 — Full Migration

Migrate all users to the external IdP. Set the external IdP as the primary provider for the tenant.

Phase 4 — Decommission Passport Tokens (Optional)

Remove Passport from the allowed issuers for this tenant. Only external IdP tokens are now accepted. Passport admin tokens may still be retained for emergency access.

Issuer Conflict Detection

A user may have identities in both Passport and an external IdP. BizFirstGO resolves this using the email address as the stable anchor:

// Conflict resolution strategy
{
  "conflictResolution": "external-wins",  // prefer external IdP token over Passport
  // or:
  "conflictResolution": "issuer-order",   // prefer based on registration order
  // or:
  "conflictResolution": "reject"          // reject if user exists in multiple issuers
}

Audit During Migration

Enable enhanced audit logging during migration to track which issuer is being used for each authentication event. This helps identify users who have not yet switched to the new IdP and detects any unexpected issuer patterns. Use GET /passport/admin/audit?filter=issuer to query by issuer.

← Claims Mapping