feat(auth): map OpenID groups claim (#3999)

* feat(auth): map OpenID groups claim

Signed-off-by: Akash Kumar <meakash7902@gmail.com>

* fix(auth): refine OIDC claim mapping logs

Signed-off-by: Akash Kumar <meakash7902@gmail.com>

* refactor(auth): collapse OIDC username fallback into nested if

Reuse the empty-username branch for the email fallback so the value is
checked once and the failure path lives next to the recovery attempt.

Signed-off-by: Akash Kumar <meakash7902@gmail.com>

* refactor(auth): consolidate OIDC claim extraction into authn.go

Move getOpenIDClaimMapping, getOpenIDUsername, and appendOpenIDGroups
out of routes.go into authn.go alongside a new extractOpenIDIdentity
helper that owns the username/groups extraction flow. This keeps the
HTTP callback in routes.go thin and groups OIDC plumbing with the rest
of the authentication code.

Also:
- Filter nil and empty entries consistently across the []any, []string,
  and string branches of appendOpenIDGroups, with new test cases
  covering []any{nil, ""} and []string{"admin","",...}.
- Surface a Warn log when an operator-configured username claim is
  missing/empty so the fallback to email isn't silent.
- Rename openid_claim_mapping_internal_test.go to authn_internal_test.go
  and drop the build tags that aren't needed for the internal tests.

Signed-off-by: Akash Kumar <meakash7902@gmail.com>

---------

Signed-off-by: Akash Kumar <meakash7902@gmail.com>

Author: AkashKumar7902

examples/README.md

@@ -440,7 +440,11 @@ zot can be configured to use dex with:
             "clientsecret": "ZXhhbXBsZS1hcHAtc2VjcmV0",
             "keypath": "",
             "issuer": "http://127.0.0.1:5556/dex",
-            "scopes": ["openid", "profile", "email", "groups"]
+            "scopes": ["openid", "profile", "email", "groups"],
+            "claimMapping": {
+              "username": "preferred_username",
+              "groups": "groups"
+            }
           }
         }
       }
@@ -450,6 +454,8 @@ zot can be configured to use dex with:
 
 To login using openid dex provider use http://127.0.0.1:8080/zot/auth/login?provider=oidc
 
+`claimMapping.username` defaults to `email`, and `claimMapping.groups` defaults to `groups`.
+
 NOTE: Social login is not supported by command line tools, or other software responsible for pushing/pulling
 images to/from zot.
 Given this limitation, if openif authentication is enabled in the configuration, API keys are also enabled

examples/config-openid-claim-mapping.json

@@ -20,7 +20,8 @@
             "credentialsFile": "examples/config-openid-oidc-credentials.json",
             "scopes": ["openid", "profile", "email", "groups"],
             "claimMapping": {
-              "username": "preferred_username"
+              "username": "preferred_username",
+              "groups": "groups"
             }
           }
         }

pkg/api/authn.go

@@ -1106,6 +1106,161 @@ func saveUserLoggedSession(cookieStore sessions.Store, response http.ResponseWri
 	return nil
 }
 
+const (
+	defaultUsernameClaim = "email"
+	defaultGroupsClaim   = "groups"
+)
+
+// getOpenIDClaimMapping resolves the username and groups claim names for a given provider.
+// The third return value reports whether the username claim was explicitly configured
+// (false means the default "email" claim is being used as a fallback).
+func getOpenIDClaimMapping(authConfig *config.AuthConfig, providerName string) (string, string, bool) {
+	usernameClaim := defaultUsernameClaim
+	groupsClaim := defaultGroupsClaim
+	usernameConfigured := false
+
+	if authConfig == nil || authConfig.OpenID == nil || providerName == "" {
+		return usernameClaim, groupsClaim, usernameConfigured
+	}
+
+	providerConfig, ok := authConfig.OpenID.Providers[providerName]
+	if !ok || providerConfig.ClaimMapping == nil {
+		return usernameClaim, groupsClaim, usernameConfigured
+	}
+
+	if providerConfig.ClaimMapping.Username != "" {
+		usernameClaim = providerConfig.ClaimMapping.Username
+		usernameConfigured = true
+	}
+
+	if providerConfig.ClaimMapping.Groups != "" {
+		groupsClaim = providerConfig.ClaimMapping.Groups
+	}
+
+	return usernameClaim, groupsClaim, usernameConfigured
+}
+
+func getOpenIDUsername(info *oidc.UserInfo, claimName string) string {
+	if info == nil {
+		return ""
+	}
+
+	switch claimName {
+	case "preferred_username":
+		return info.PreferredUsername
+	case defaultUsernameClaim:
+		return info.UserInfoEmail.Email
+	case "sub":
+		return info.Subject
+	case "name":
+		return info.Name
+	default:
+		if val, ok := info.Claims[claimName].(string); ok {
+			return val
+		}
+	}
+
+	return ""
+}
+
+func appendOpenIDGroups(groups []string, claims map[string]any, claimName string) ([]string, bool) {
+	switch val := claims[claimName].(type) {
+	case []any:
+		for _, group := range val {
+			if group == nil {
+				continue
+			}
+
+			if str := fmt.Sprint(group); str != "" {
+				groups = append(groups, str)
+			}
+		}
+
+		return groups, true
+	case []string:
+		for _, group := range val {
+			if group != "" {
+				groups = append(groups, group)
+			}
+		}
+
+		return groups, true
+	case string:
+		if val != "" {
+			groups = append(groups, val)
+		}
+
+		return groups, true
+	}
+
+	return groups, false
+}
+
+// extractOpenIDIdentity resolves the username and groups for an OIDC callback
+// based on the provider's configured claim mapping. It returns the resolved
+// username, the deduplicated/sorted groups, and a boolean reporting whether
+// the username could be resolved at all (false means callers should reject).
+func extractOpenIDIdentity(logger log.Logger, authConfig *config.AuthConfig, providerName string,
+	info *oidc.UserInfo, idTokenClaims map[string]any,
+) (string, []string, bool) {
+	usernameClaim, groupsClaim, usernameConfigured := getOpenIDClaimMapping(authConfig, providerName)
+
+	username := getOpenIDUsername(info, usernameClaim)
+
+	if username == "" && usernameConfigured {
+		configuredClaim := usernameClaim
+		usernameClaim = defaultUsernameClaim
+		usernameConfigured = false
+		username = getOpenIDUsername(info, usernameClaim)
+
+		logger.Warn().
+			Str("provider", providerName).
+			Str("claim", configuredClaim).
+			Msg("configured username claim missing or empty, falling back to email")
+	}
+
+	if username == "" {
+		return "", nil, false
+	}
+
+	if usernameConfigured {
+		logger.Debug().
+			Str("provider", providerName).
+			Str("claim", usernameClaim).
+			Str("username", username).
+			Msg("extracted username from configured claim")
+	} else {
+		logger.Debug().
+			Str("provider", providerName).
+			Str("username", username).
+			Msg("using email as username (fallback)")
+	}
+
+	var (
+		groups      []string
+		groupsFound bool
+	)
+
+	if info != nil {
+		groups, groupsFound = appendOpenIDGroups(groups, info.Claims, groupsClaim)
+		if !groupsFound {
+			logger.Info().Msgf("failed to find any %q claim for user %s in UserInfo", groupsClaim, username)
+		}
+	}
+
+	if idTokenClaims != nil {
+		groups, groupsFound = appendOpenIDGroups(groups, idTokenClaims, groupsClaim)
+		if !groupsFound {
+			logger.Info().Msgf("failed to find any %q claim for user %s in IDTokenClaimsToken", groupsClaim, username)
+		}
+	}
+
+	slices.Sort(groups)
+	groups = slices.Compact(groups)
+
+	return username, groups, true
+}
+
 // OAuth2Callback is the callback logic where openid/oauth2 will redirect back to our app.
 func OAuth2Callback(ctlr *Controller, w http.ResponseWriter, r *http.Request, state, email, provider string,
 	groups []string,