feat: support Azure AD groups claims overflow via Microsoft Graph API (#27397)

Signed-off-by: Christian Artin <gravufo@gmail.com>

Author: gravufo

docs/operator-manual/user-management/microsoft.md

@@ -124,6 +124,93 @@
 
    Refer to [operator-manual/argocd-rbac-cm.yaml](https://github.com/argoproj/argo-cd/blob/master/docs/operator-manual/argocd-rbac-cm.yaml) for all of the available variables.
 
+## Azure AD Groups Overflow Resolution (200+ Groups)
+
+### Overview
+
+Azure AD / Entra ID access tokens can contain a maximum of 200 groups. When a user belongs to more
+than 200 groups, Azure AD sets overflow indicators (`_claim_names` and `_claim_sources`) in the ID
+token instead of including the `groups` claim. This causes users to have no group-based RBAC
+permissions in Argo CD.
+
+Argo CD can automatically detect this overflow and resolve it by calling the Microsoft Graph API to
+fetch the complete list of group memberships.
+
+### Prerequisites
+
+1. The Azure AD app registration must have the **User.Read** delegated permission. This is granted by
+   default when following the [Setup permissions](#setup-permissions-for-entra-id-application) steps
+   above. Azure AD automatically includes approved permissions in the access token's `scp` claim
+   without needing to explicitly request them in `requestedScopes`.
+
+### Configuration
+
+Add the following to your `argocd-cm` ConfigMap under `oidc.config`:
+
+```yaml
+oidc.config: |
+  name: Azure
+  issuer: https://login.microsoftonline.com/{tenant_id}/v2.0
+  clientID: {client_id}
+  clientSecret: $oidc.azure.clientSecret
+  requestedScopes:
+    - openid
+    - profile
+    - email
+  azure:
+    enableUserGroupOverageClaim: true
+```
+
+### Configuration Options
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `enableUserGroupOverageClaim` | `false` | Enable automatic overflow resolution via Graph API |
+| `graphApiEndpoint` | `https://graph.microsoft.com/v1.0` | Graph API base URL (override for sovereign clouds) |
+| `userGroupOverageClaimCacheExpiration` | Token expiry | Cache duration for resolved groups (e.g., `10m`) |
+
+#### Sovereign Clouds
+
+For Azure Government, Azure China, or other sovereign clouds, override the Graph API endpoint:
+
+```yaml
+azure:
+  enableUserGroupOverageClaim: true
+  graphApiEndpoint: https://graph.microsoft.us/v1.0  # Azure Government
+```
+
+### How It Works
+
+1. **Detection**: Argo CD checks the ID token for overflow indicators (`_claim_names` and
+   `_claim_sources`).
+2. **Scope Check**: Verifies the access token contains the `User.Read` scope.
+3. **Graph API Call**: Calls `POST /me/getMemberGroups` to fetch all group IDs (up to 2048).
+   Only security-enabled groups are returned (not distribution lists), which is appropriate
+   for RBAC evaluation.
+4. **Caching**: Encrypts and caches the resolved groups for the duration of the token or a
+   configured expiration.
+5. **RBAC Integration**: The resolved group IDs are added to the user's claims for RBAC evaluation.
+
+### Troubleshooting
+
+| Symptom | Cause | Solution |
+|---------|-------|----------|
+| User still has 0 groups despite 200+ memberships | Feature not enabled | Set `enableUserGroupOverageClaim: true` |
+| Logs show "access token missing User.Read scope" | Missing permission | Verify the **User.Read** delegated permission is granted on the app registration in Azure AD |
+| Logs show "insufficient permissions for Graph API" | App permission denied | Verify app permissions in Azure AD |
+| Logs show "no access token cached" | Token expired | User must re-authenticate |
+
+> [!WARNING]
+> This feature depends on the Microsoft Graph API being reachable at authentication time. If the
+> Graph API is unavailable (network issues, outage, etc.), users with 200+ group memberships will
+> be unable to authenticate until service is restored. Users with fewer than 200 groups are
+> unaffected since their groups are included directly in the ID token.
+>
+> Graph API failures (missing scope, permission denied, network errors) will cause authentication
+> to fail with a 401 Unauthorized response. This is consistent with how the UserInfo endpoint
+> behaves. Only enable this feature if you need group-based RBAC for users with 200+ groups, and
+> ensure the prerequisites above are met to avoid authentication issues.
+
 ## Entra ID SAML Enterprise App Auth using Dex
 ### Configure a new Entra ID Enterprise App
 

server/server.go

@@ -1599,7 +1599,7 @@ func (server *ArgoCDServer) getClaims(ctx context.Context) (jwt.Claims, string,
 	finalClaims := claims
 	oidcConfig := server.settings.OIDCConfig()
 	if oidcConfig != nil || server.settings.IsDexConfigured() {
-		updatedClaims, err := server.ssoClientApp.SetGroupsFromUserInfo(ctx, claims, util_session.SessionManagerClaimsIssuer)
+		updatedClaims, err := server.ssoClientApp.SetGroupsClaimFromEndpoint(ctx, claims, util_session.SessionManagerClaimsIssuer)
 		if err != nil {
 			return claims, "", status.Errorf(codes.Unauthenticated, "invalid session: %v", err)
 		}

util/oidc/oidc.go

@@ -580,6 +580,15 @@ func (a *ClientApp) HandleCallback(w http.ResponseWriter, r *http.Request) {
 	}
 	// save the accessToken in memory for later use
 	sub := jwtutil.StringField(claims, "sub")
+
+	// Invalidate cached groups from previous sessions so a fresh login picks up updated memberships
+	if err := a.clientCache.Delete(FormatUserInfoResponseCacheKey(sub)); err != nil {
+		log.Warnf("failed to invalidate UserInfo cache for %s: %v", sub, err)
+	}
+	if err := a.clientCache.Delete(FormatAzureGroupsOverageResponseCacheKey(sub)); err != nil {
+		log.Warnf("failed to invalidate Azure groups overage cache for %s: %v", sub, err)
+	}
+
 	err = a.SetValueInEncryptedCache(ctx, FormatAccessTokenCacheKey(sub), []byte(token.AccessToken), GetTokenExpiration(claims))
 	if err != nil {
 		claimsJSON, _ := json.Marshal(claims)
@@ -882,12 +891,14 @@ func createClaimsAuthenticationRequestParameter(requestedClaims map[string]*oidc
 	return oauth2.SetAuthURLParam("claims", string(claimsRequestRAW)), nil
 }
 
-// SetGroupsFromUserInfo takes a claims object and adds groups claim from userinfo endpoint if available
-// This is required by some SSO implementations as they don't provide the groups claim in the ID token
-// If querying the UserInfo endpoint fails, we return an error to indicate the session is invalid
-// we assume that everywhere in argocd jwt.MapClaims is used as type for interface jwt.Claims
-// otherwise this would cause a panic
-func (a *ClientApp) SetGroupsFromUserInfo(ctx context.Context, claims jwt.Claims, sessionManagerClaimsIssuer string) (jwt.MapClaims, error) {
+// SetGroupsClaimFromEndpoint takes a claims object and adds groups claim from either:
+// - the UserInfo endpoint if enabled
+// - the Microsoft Graph API if Azure groups overage claim is detected and enabled
+// This is required by some SSO implementations as they don't provide the groups claim in the ID token.
+// If querying the endpoint fails, we return an error to indicate the session is invalid.
+// We assume that everywhere in argocd jwt.MapClaims is used as type for interface jwt.Claims
+// otherwise this would cause a panic.
+func (a *ClientApp) SetGroupsClaimFromEndpoint(ctx context.Context, claims jwt.Claims, sessionManagerClaimsIssuer string) (jwt.MapClaims, error) {
 	var groupClaims jwt.MapClaims
 	var ok bool
 	if groupClaims, ok = claims.(jwt.MapClaims); !ok {
@@ -897,19 +908,37 @@ func (a *ClientApp) SetGroupsFromUserInfo(ctx context.Context, claims jwt.Claims
 			}
 		}
 	}
+
 	iss := jwtutil.StringField(groupClaims, "iss")
-	if iss != sessionManagerClaimsIssuer && a.settings.UserInfoGroupsEnabled() && a.settings.UserInfoPath() != "" {
-		userInfo, unauthorized, err := a.GetUserInfo(ctx, groupClaims, a.settings.IssuerURL(), a.settings.UserInfoBaseURL(), a.settings.UserInfoPath())
-		if unauthorized {
-			return groupClaims, fmt.Errorf("error while quering userinfo endpoint: %w", err)
-		}
-		if err != nil {
-			return groupClaims, fmt.Errorf("error fetching user info endpoint: %w", err)
+	if iss != sessionManagerClaimsIssuer {
+		// Path 1: UserInfo endpoint — mutually exclusive with Path 2 (Azure overage).
+		// For Entra ID, UserInfo returns the same data as the ID token, so both are never needed.
+		if a.settings.UserInfoGroupsEnabled() && a.settings.UserInfoPath() != "" {
+			userInfo, unauthorized, err := a.GetUserInfo(ctx, groupClaims, a.settings.IssuerURL(), a.settings.UserInfoBaseURL(), a.settings.UserInfoPath())
+			if unauthorized {
+				return groupClaims, fmt.Errorf("error while querying userinfo endpoint: %w", err)
+			}
+			if err != nil {
+				return groupClaims, fmt.Errorf("error fetching user info endpoint: %w", err)
+			}
+			if groupClaims["sub"] != userInfo["sub"] {
+				return groupClaims, errors.New("subject of claims from user info endpoint didn't match subject of idToken, see https://openid.net/specs/openid-connect-core-1_0.html#UserInfo")
+			}
+			groupClaims["groups"] = userInfo["groups"]
+			return groupClaims, nil
 		}
-		if groupClaims["sub"] != userInfo["sub"] {
-			return groupClaims, errors.New("subject of claims from user info endpoint didn't match subject of idToken, see https://openid.net/specs/openid-connect-core-1_0.html#UserInfo")
+
+		// Path 2: Azure AD groups overage claim resolution via Microsoft Graph API
+		if a.settings.AzureUserGroupOverageClaimEnabled() && a.settings.AzureGraphAPIEndpoint() != "" {
+			groups, err := a.GetUserGroupsFromAzureOverageClaim(ctx, groupClaims, a.settings.AzureGraphAPIEndpoint())
+			if err != nil {
+				return groupClaims, fmt.Errorf("error fetching groups from Azure overage claim: %w", err)
+			}
+			if len(groups) > 0 {
+				groupClaims["groups"] = groups
+			}
+			return groupClaims, nil
 		}
-		groupClaims["groups"] = userInfo["groups"]
 	}
 
 	return groupClaims, nil