feat(oauth2): populate groups claim in client_credentials tokens

Add a ClientCredentialsClaims sub-struct to the Client definition,
allowing static clients to declare identity claims (starting with
groups) that are included in tokens issued via client_credentials.

This keeps the Client struct focused on application-level concerns
(ID, secret, redirect URIs) while providing a dedicated home for
identity attributes needed by RBAC-aware consumers.

Configuration example:

    staticClients:
      - id: my-service
        secret: "..."
        clientCredentialsClaims:
          groups:
            - admin-group

When the groups scope is requested in a client_credentials grant,
the groups from clientCredentialsClaims are included in the token.
If clientCredentialsClaims is not set, behavior is unchanged.

Fixes #4690

Signed-off-by: Carles Arnal <carlesarnal92@gmail.com>

Author: carlesarnal

server/handlers.go

@@ -1880,12 +1880,16 @@ func (s *Server) handleClientCredentialsGrant(w http.ResponseWriter, r *http.Req
 		UserID: client.ID,
 	}
 
-	// Only populate Username/PreferredUsername when the profile scope is requested.
+	// Populate optional claims based on requested scopes.
 	for _, scope := range scopes {
-		if scope == scopeProfile {
+		switch scope {
+		case scopeProfile:
 			claims.Username = client.Name
 			claims.PreferredUsername = client.Name
-			break
+		case scopeGroups:
+			if client.ClientCredentialsClaims != nil {
+				claims.Groups = client.ClientCredentialsClaims.Groups
+			}
 		}
 	}
 

server/handlers_test.go

@@ -1068,14 +1068,16 @@ func TestHandlePasswordLoginWithSkipApproval(t *testing.T) {
 
 func TestHandleClientCredentials(t *testing.T) {
 	tests := []struct {
-		name          string
-		clientID      string
-		clientSecret  string
-		scopes        string
-		wantCode      int
-		wantAccessTok bool
-		wantIDToken   bool
-		wantUsername  string
+		name                    string
+		clientID                string
+		clientSecret            string
+		clientCredentialsClaims *storage.ClientCredentialsClaims
+		scopes                  string
+		wantCode                int
+		wantAccessTok           bool
+		wantIDToken             bool
+		wantUsername            string
+		wantGroups             []string
 	}{
 		{
 			name:          "Basic grant, no scopes",
@@ -1115,6 +1117,28 @@ func TestHandleClientCredentials(t *testing.T) {
 			wantIDToken:   true,
 			wantUsername:  "Test Client",
 		},
+		{
+			name:          "With groups scope and clientCredentialsClaims groups populated",
+			clientID:      "test",
+			clientSecret:  "barfoo",
+			clientCredentialsClaims: &storage.ClientCredentialsClaims{
+				Groups: []string{"admin-group", "dev-group"},
+			},
+			scopes:        "openid groups",
+			wantCode:      200,
+			wantAccessTok: true,
+			wantIDToken:   true,
+			wantGroups:   []string{"admin-group", "dev-group"},
+		},
+		{
+			name:          "With groups scope but no clientCredentialsClaims configured",
+			clientID:      "test",
+			clientSecret:  "barfoo",
+			scopes:        "openid groups",
+			wantCode:      200,
+			wantAccessTok: true,
+			wantIDToken:   true,
+		},
 		{
 			name:         "Invalid client secret",
 			clientID:     "test",
@@ -1155,10 +1179,11 @@ func TestHandleClientCredentials(t *testing.T) {
 
 			// Create a confidential client for testing.
 			err := s.storage.CreateClient(ctx, storage.Client{
-				ID:           "test",
-				Secret:       "barfoo",
-				RedirectURIs: []string{"https://example.com/callback"},
-				Name:         "Test Client",
+				ID:                     "test",
+				Secret:                 "barfoo",
+				RedirectURIs:           []string{"https://example.com/callback"},
+				Name:                   "Test Client",
+				ClientCredentialsClaims: tc.clientCredentialsClaims,
 			})
 			require.NoError(t, err)
 
@@ -1214,8 +1239,9 @@ func TestHandleClientCredentials(t *testing.T) {
 					require.Equal(t, tc.clientID, sub.UserId)
 
 					var claims struct {
-						Name              string `json:"name"`
-						PreferredUsername string `json:"preferred_username"`
+						Name              string   `json:"name"`
+						PreferredUsername string   `json:"preferred_username"`
+						Groups           []string `json:"groups"`
 					}
 					require.NoError(t, idToken.Claims(&claims))
 
@@ -1226,6 +1252,12 @@ func TestHandleClientCredentials(t *testing.T) {
 						require.Empty(t, claims.Name)
 						require.Empty(t, claims.PreferredUsername)
 					}
+
+					if tc.wantGroups != nil {
+						require.Equal(t, tc.wantGroups, claims.Groups)
+					} else {
+						require.Empty(t, claims.Groups)
+					}
 				} else {
 					require.Empty(t, resp.IDToken)
 				}

storage/storage.go

@@ -191,6 +191,18 @@ type Client struct {
 	// MFAChain is an ordered list of MFA authenticator IDs that a user must complete
 	// during login. Empty means no MFA required.
 	MFAChain []string `json:"mfaChain"`
+
+	// ClientCredentialsClaims holds identity claims used when issuing tokens via the
+	// client_credentials grant. Kept separate from core Client fields to avoid mixing
+	// application identity (ID, secret, redirect URIs) with user-like identity attributes.
+	ClientCredentialsClaims *ClientCredentialsClaims `json:"clientCredentialsClaims,omitempty"`
+}
+
+// ClientCredentialsClaims contains claims that are included in tokens issued via
+// the client_credentials grant. This is scoped to client_credentials to keep the
+// Client struct focused on application-level concerns.
+type ClientCredentialsClaims struct {
+	Groups []string `json:"groups,omitempty"`
 }
 
 // Claims represents the ID Token claims supported by the server.