[Feature Request] Add sovereign cloud support to Azure AD provider

[lance0]

Goals

1. Enable Government Cloud Authentication - Allow Azure Government (GCC-High/DoD) tenants to authenticate with NextAuth.js using correct sovereign cloud endpoints (login.microsoftonline.us) without manual configuration.

2. Simplify Configuration - Reduce sovereign cloud setup from 15+ lines of manual endpoint overrides to a single cloud: "usgov" option, making it accessible to developers unfamiliar with Azure Government infrastructure.

3. Maintain Backward Compatibility - Add this feature with zero breaking changes by defaulting to public cloud ("public"), ensuring existing Azure AD users are unaffected.

Non-Goals

1. Graph API Integration Beyond OIDC - This PR focuses on OIDC authentication only. Advanced Microsoft Graph API features (like profile enrichment beyond ID token claims) remain user-implemented. Users can still call Graph APIs manually with obtained tokens.

2. China Sovereign Cloud (Initial Release) - Azure China (login.partner.microsoftonline.cn) has different requirements and less demand. We can add cloud: "china" in a follow-up PR if needed, but it's out of scope for the initial implementation.

3. Custom Authority Hosts - This PR uses a type-safe enum ("public" | "usgov" | "dod") to prevent misconfiguration and security issues. Users needing completely custom authority hosts can continue using manual issuer/wellKnown overrides, which remain fully supported.

Background

Why This Is Needed

Azure Government is a separate infrastructure from Azure Commercial:

• Different URLs: login.microsoftonline.us vs login.microsoftonline.com
• Network Isolation: Gov clouds are physically and logically isolated for compliance (FedRAMP, DoD IL4/IL5)
• 10,000+ Organizations: Includes federal agencies, state/local governments, and contractors serving them

Current Pain Points:

1. Users must manually override 5+ URLs (issuer, wellKnown, authorization, token, userinfo)
2. Government tenants have different token claim structures (often lack email, use upn instead)
3. No official documentation for NextAuth.js + Azure Government
4. Error-prone configuration leads to security issues (wrong issuer validation)

Current Alternatives (All Suboptimal)

Alternative 1: Manual Endpoint Override (Status Quo)

AzureADProvider({
  clientId: process.env.AZURE_AD_CLIENT_ID,
  clientSecret: process.env.AZURE_AD_CLIENT_SECRET,
  tenantId: process.env.AZURE_AD_TENANT_ID,
  // Manually override every endpoint
  issuer: "https://login.microsoftonline.us/tenant-id/v2.0",
  wellKnown: "https://login.microsoftonline.us/tenant-id/v2.0/.well-known/openid-configuration",
  authorization: {
    url: "https://login.microsoftonline.us/tenant-id/oauth2/v2.0/authorize",
    params: { scope: "openid profile email User.Read" }
  },
  token: "https://login.microsoftonline.us/tenant-id/oauth2/v2.0/token",
  // Custom profile mapping for Gov-cloud claims
  profile(profile) {
    return {
      id: profile.oid ?? profile.sub,
      email: profile.upn ?? profile.preferred_username ?? profile.email,
      name: profile.name,
    }
  },
})

Problems:

• 15+ lines of boilerplate
• Easy to make mistakes (wrong URL, missing /v2.0, etc.)
• No type safety
• Not discoverable (users don't know this is needed)

Alternative 2: Custom Provider Wrapper
Users create their own provider wrapper around Azure AD:

function AzureGovProvider(options) {
  return AzureADProvider({
    ...options,
    issuer: `https://login.microsoftonline.us/${options.tenantId}/v2.0`,
    // ... more overrides
  })
}

Problems:

• Every user reinvents the wheel
• No shared testing or documentation
• Inconsistent implementations across projects

Alternative 3: Use a Different Library
Switch to MSAL, Passport, or custom OIDC implementation.

Problems:

• Lose NextAuth.js benefits (sessions, callbacks, adapter ecosystem)
• Significant migration effort
• No guarantee other libraries handle Gov clouds better

Prior Art

This PR is based on a production library I built:

• Purpose: GCC-High authentication for Next.js apps
• Status: Deployed in multiple Government agencies
• Testing: 135 unit tests including security scenarios
• Proven Patterns:
  • Cloud-based endpoint derivation
  • Robust claim fallbacks (oid, upn, preferred_username)
  • Strict issuer validation per cloud

Key Learnings from latch:

1. Enum-based cloud selection prevents user errors (vs string input)
2. oid is more stable than sub for user identity across tenants
3. Gov tenants often lack email claim - must fall back to upn
4. Issuer validation is critical - prevents cross-cloud token attacks

Similar Features in Other Ecosystems:

• Microsoft MSAL: Has azureCloudInstance enum (AzurePublic, AzureUsGovernment, AzureGermany, AzureChina)
• Passport-Azure-AD: Accepts identityMetadata URL for different clouds
• AWS Cognito: Supports region parameter for different AWS clouds

Why Now?

1. Growing Demand: More agencies moving to cloud infrastructure
2. FedRAMP Requirements: Gov agencies required to use FedRAMP-approved services
3. Low Risk: Backward compatible, opt-in feature, well-tested design

What Success Looks Like

Before:

// 15+ lines of manual config
// Easy to get wrong
// No documentation

After:

AzureADProvider({
  tenantId: "...",
  cloud: "usgov",  // That's it!
})

Impact:

• Government developers can use NextAuth.js out-of-the-box
• Reduced support burden (common config documented)
• Safer (type-safe enum, correct issuer validation)
• Discoverable (shows up in TypeScript autocomplete)

---

Implementation Confidence

I have prepared:

• ✅ Complete reference implementation (endpoint derivation, profile mapping)
• ✅ Comprehensive test suite (20+ tests covering all clouds)
• ✅ User documentation (Gov portal setup, troubleshooting guide)
• ✅ Working example app (Next.js 15 with GCC-High auth)
• ✅ Technical specification (security considerations, migration guide)

This is a low-risk, high-impact addition that enables a significant user segment while maintaining NextAuth.js's quality standards.

---

Questions for Maintainers

1. API Design: Does the cloud enum approach fit NextAuth.js conventions? (Alternative: authorityHost string with validation)

2. Scope: Should we include Azure China support in initial release? (Can add cloud: "china" enum value, mark as experimental)

3. Documentation: Prefer new "Sovereign Clouds" page or section within existing Azure AD provider docs?

4. Testing: Any specific Gov-cloud scenarios you'd like covered beyond standard OIDC flow?

Proposal

## Summary

I would like to add support for Microsoft Azure Government clouds (GCC-High, DoD) to the Azure AD provider. This will enable 10,000+ government organizations to use NextAuth.js without manual endpoint configuration.

## Problem

The current Azure AD provider assumes Microsoft Public Cloud (`login.microsoftonline.com`). U.S. Government tenants operate in sovereign clouds with different infrastructure:

- **Authority:** `login.microsoftonline.us` (not `.com`)
- **Graph API:** `graph.microsoft.us` or `dod-graph.microsoft.us`
- **Claims:** Often use `upn` instead of `email`

Today, users must manually configure 15+ lines of endpoint overrides and custom profile mapping.

## Proposed Solution

Add a `cloud` option to `AzureADProvider`:

```typescript
AzureADProvider({
  clientId: process.env.AZURE_AD_CLIENT_ID,
  clientSecret: process.env.AZURE_AD_CLIENT_SECRET,
  tenantId: process.env.AZURE_AD_TENANT_ID,
  cloud: "usgov",  // NEW: "public" | "usgov" | "dod"
})

Key Features

Cloud Endpoints:

Cloud	Authority	Graph API
"public" (default)	login.microsoftonline.com	graph.microsoft.com
"usgov" (GCC-High)	login.microsoftonline.us	graph.microsoft.us
"dod" (DoD IL5)	login.microsoftonline.us	dod-graph.microsoft.us

Benefits:

• Zero breaking changes (defaults to "public")
• Type-safe enum prevents misconfiguration
• Auto-derives endpoints based on cloud
• Robust profile mapping with Gov-cloud fallbacks
• Manual overrides still respected

Prior Art

This design is based on a production-tested library I built for GCC-High authentication:

• 135 unit tests
• Deployed in Azure GCC-High
• Proven endpoint derivation patterns

Implementation Plan

I have prepared:

1. ✅ Complete reference implementation
2. ✅ Comprehensive test suite (20+ tests)
3. ✅ User documentation
4. ✅ Working example app (Next.js 15)
5. ✅ Technical specification

Questions for Maintainers

1. Does this approach fit NextAuth.js architecture?
2. Any concerns about adding the cloud option?
3. Should I include China cloud support in the initial implementation?
4. Preference on documentation structure (new page vs section)?

Impact

• Enables 10,000+ Azure Government organizations
• Reduces config complexity (15 lines → 3 lines)
• Maintains backward compatibility
• Type-safe, secure, well-tested

I'm ready to implement this after getting maintainer feedback. Thank you for considering this contribution!