Document Groups field design decision

Add concise documentation explaining why Identity.Groups is intentionally
not populated by OIDCIncomingAuthenticator. This clarifies that group
extraction is an authorization concern handled via the Claims map, as
different OIDC providers use different claim names.

Author: jhrozek

pkg/vmcp/auth/auth.go

@@ -85,6 +85,10 @@ type Identity struct {
 	Email string
 
 	// Groups are the groups this identity belongs to.
+	//
+	// NOTE: This field is intentionally NOT populated by OIDCIncomingAuthenticator.
+	// Authorization logic MUST extract groups from the Claims map, as group claim
+	// names vary by provider (e.g., "groups", "roles", "cognito:groups").
 	Groups []string
 
 	// Claims contains additional claims from the auth token.

pkg/vmcp/auth/incoming_oidc.go

@@ -106,12 +106,13 @@ func (o *OIDCIncomingAuthenticator) Middleware() func(http.Handler) http.Handler
 }
 
 // claimsToIdentity converts JWT claims to an Identity structure.
-// It extracts only the universal JWT fields (sub, name, email) and stores
-// all claims in the Claims map. Groups extraction is left to authorization
-// logic that can interpret provider-specific claim structures.
 //
-// Returns an error if the required 'sub' claim is missing or invalid, as mandated
-// by OpenID Connect Core 1.0 specification section 5.1.
+// Groups are intentionally NOT extracted here because:
+// - OIDC providers use different claim names ("groups", "roles", etc.)
+// - Group extraction is an authorization concern, not authentication
+// - Authorization policies access groups via the Claims map
+//
+// Returns an error if the required 'sub' claim is missing or invalid.
 func claimsToIdentity(claims jwt.MapClaims) (*Identity, error) {
 	identity := &Identity{
 		Claims: make(map[string]any),