Azure AD / Entra ID Integration

Azure App Registration

Role: BizFirstGO.Admin    — Display name: "BizFirstGO Admin"
Role: BizFirstGO.Manager  — Display name: "BizFirstGO Manager"
Role: BizFirstGO.User     — Display name: "BizFirstGO User"
Role: BizFirstGO.Viewer   — Display name: "BizFirstGO Viewer"

Azure AD Token Structure

// Decoded Azure AD access token
{
  "iss": "https://login.microsoftonline.com/{aad-tenant-id}/v2.0",
  "sub": "A1bC2-dEfG3-hIjK4-lMnO5",  // OID (Object ID) — stable user identifier
  "oid": "A1bC2-dEfG3-hIjK4-lMnO5",  // same as sub in v2 tokens
  "tid": "aad-tenant-id",             // Azure AD tenant ID
  "aud": "api://bizfirstgo",
  "upn": "jane.smith@company.onmicrosoft.com",
  "name": "Jane Smith",
  "email": "jane.smith@company.com",
  "roles": ["BizFirstGO.Admin", "BizFirstGO.Manager"],  // App roles
  "groups": [                                              // Security group GUIDs (if <200 groups)
    "a1b2c3d4-...", "e5f6g7h8-..."
  ]
}

BizFirstGO Federation Configuration

POST /passport/admin/tenants/{tenantId}/federation
{
  "providerId":    "azure-ad",
  "displayName":   "Microsoft Entra ID",
  "issuer":        "https://login.microsoftonline.com/{aad-tenant-id}/v2.0",
  "jwksUri":       "https://login.microsoftonline.com/{aad-tenant-id}/discovery/v2.0/keys",
  "audience":      "api://bizfirstgo",
  "tenantIdConfig":{
    "source":     "static",
    "value":      "tenant-abc"   // or use "claim" source with "tid" claim + mapping table
  },
  "userIdClaim":   "oid",        // Object ID — more stable than "sub" for Azure AD
  "emailClaim":    "email",
  "rolesClaim":    "roles",      // App roles preferred over group GUIDs
  "roleMapping": {
    "BizFirstGO.Admin":   "admin",
    "BizFirstGO.Manager": "manager",
    "BizFirstGO.User":    "user",
    "BizFirstGO.Viewer":  "viewer"
  }
}

Groups Overage Handling

Azure AD includes a maximum of 200 groups in JWT tokens. When a user has more than 200 groups, the token includes an overage indicator (_claim_names: { groups: "src1" }) instead of the groups list. BizFirstGO's Azure AD provider handles this automatically by calling Microsoft Graph.

// Overage token structure
{
  "_claim_names": { "groups": "src1" },
  "_claim_sources": {
    "src1": {
      "endpoint": "https://graph.microsoft.com/v1.0/users/{oid}/getMemberObjects"
    }
  }
}

// BizFirstGO Azure AD provider — automatic overage handling
public sealed class AzureADTokenProvider : IExternalTokenProvider
{
    // When groups overage is detected, fall back to Graph API
    private async Task<IList<string>> GetGroupsWithOverageAsync(
        string userId, string accessToken, CancellationToken ct)
    {
        var graphClient = new GraphServiceClient(/* ... */);
        var groups = await graphClient.Users[userId]
            .TransitiveMemberOf
            .GetAsync(ct: ct);

        return groups?.Value?
            .OfType<Group>()
            .Select(g => g.Id ?? "")
            .ToList() ?? [];
    }
}