Production Bug Exposed by B2B Guests

Internal QA passed because testers used employee accounts, where Azure AD's preferred_username claim reliably matched their email for whitelisting and access control. But three weeks post-launch, a B2B client's guest users logged in successfully yet hit 403 errors due to mismatched identity. Guests have active sessions and valid Azure AD accounts, but preferred_username doesn't provide a usable email—it's often absent, null, or mismatched for external users invited via B2B collaboration. This single claim broke the entire auth flow, granting sessions without proper rights.

To replicate and confirm: Employee flow succeeds (preferred_username == email), guest flow authenticates but fails authorization since the claim can't anchor whitelists reliably.

preferred_username Limitations for Guests

preferred_username isn't a true email field—it's a user-provided hint for login names, populated only for workplace-joined accounts. For B2B guests (external users invited to your tenant), Azure AD doesn't set it to their guest email; it might reflect their home tenant's UPN or be empty. Result: Your system sees a non-email value or null, failing email-based checks for access groups or features.

Trade-off: Convenient for internal users (matches UPN/email), but zero fallback for guests. Never use it as the sole identifier—it's not guaranteed unique or stable across user types.

Anchor Identities on oid for Cross-User Stability

Use Azure AD's oid (object ID) claim instead: a stable, tenant-wide UUID unique to every user, including guests. Pair it with userType ("Member" vs "Guest") to differentiate and route logic:

  • Fetch user details via Microsoft Graph API using oid.
  • Check userType to apply guest-specific handling (e.g., map to external email from mail or userPrincipalName).
  • Whitelist based on verified attributes, not fragile claims.

This ensures employees and guests both resolve correctly without silent failures. Post-fix: Validate claims in dev/staging with mixed user types, and monitor auth logs for claim mismatches to catch regressions early.