Introduce selective multi-valued claim handling in JWT and UserInfo based on claim metadata

components/org.wso2.carbon.identity.oauth.endpoint/src/main/java/org/wso2/carbon/identity/oauth/endpoint/user/impl/UserInfoUserStoreClaimRetriever.java

@@ -18,14 +18,17 @@
 package org.wso2.carbon.identity.oauth.endpoint.user.impl;
 
 import org.apache.commons.collections.MapUtils;
+import org.wso2.carbon.context.PrivilegedCarbonContext;
 import org.wso2.carbon.identity.application.common.model.ClaimMapping;
 import org.wso2.carbon.identity.core.util.IdentityCoreConstants;
 import org.wso2.carbon.identity.oauth.config.OAuthServerConfiguration;
 import org.wso2.carbon.identity.oauth.endpoint.util.ClaimUtil;
 import org.wso2.carbon.identity.oauth.user.UserInfoClaimRetriever;
+import org.wso2.carbon.identity.oauth2.util.OAuth2Util;
 
 import java.util.HashMap;
 import java.util.Map;
+import java.util.Set;
 
 /**
  * Retrieving claims from the user store for the given claims dialect
@@ -37,6 +40,13 @@ public Map<String, Object> getClaimsMap(Map<ClaimMapping, String> userAttributes
 
         Map<String, Object> claims = new HashMap<String, Object>();
         if (MapUtils.isNotEmpty(userAttributes)) {
+            // When ConvertOnlyMultiValuedClaimsToArray is enabled, resolve local claim URIs flagged multi-valued.
+            // A null set means the feature is off or the lookup failed, so legacy behaviour applies.
+            Set<String> multiValuedLocalClaimUris = null;
+            if (OAuthServerConfiguration.getInstance().getConvertOnlyMultiValuedClaimsToArray()) {
+                String tenantDomain = PrivilegedCarbonContext.getThreadLocalCarbonContext().getTenantDomain();
+                multiValuedLocalClaimUris = OAuth2Util.getMultiValuedLocalClaimUris(tenantDomain);
+            }
             for (Map.Entry<ClaimMapping, String> entry : userAttributes.entrySet()) {
 
                 if (entry.getKey().getRemoteClaim() == null || IdentityCoreConstants.MULTI_ATTRIBUTE_SEPARATOR.equals(
@@ -45,10 +55,13 @@ public Map<String, Object> getClaimsMap(Map<ClaimMapping, String> userAttributes
                 }
                 String claimValue = entry.getValue();
                 String claimUri = entry.getKey().getRemoteClaim().getClaimUri();
+                String localClaimUri = entry.getKey().getLocalClaim() != null ?
+                        entry.getKey().getLocalClaim().getClaimUri() : null;
                 boolean isMultiValueSupportEnabledForUserinfoResponse = OAuthServerConfiguration.getInstance()
                         .getUserInfoMultiValueSupportEnabled();
                 if (isMultiValueSupportEnabledForUserinfoResponse &&
-                        ClaimUtil.isMultiValuedAttribute(claimUri, claimValue)) {
+                        ClaimUtil.isMultiValuedAttribute(claimUri, localClaimUri, claimValue,
+                                multiValuedLocalClaimUris)) {
                     String[] attributeValues = ClaimUtil.processMultiValuedAttribute(claimValue);
                     claims.put(claimUri, attributeValues);
                 } else {

components/org.wso2.carbon.identity.oauth.endpoint/src/main/java/org/wso2/carbon/identity/oauth/endpoint/util/ClaimUtil.java

@@ -69,6 +69,7 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.regex.Pattern;
 
 import static org.apache.commons.collections.MapUtils.isEmpty;
@@ -264,6 +265,12 @@ public static Map<String, Object> getClaimsFromUserStore(String authorizedUserNa
                             userId, realm, claimURIList, isImpersonatedUser);
                 }
 
+                // When ConvertOnlyMultiValuedClaimsToArray is enabled, resolve (once) local claim URIs flagged
+                // multi-valued. A null set means the feature is off or the lookup failed, so legacy behaviour applies.
+                Set<String> multiValuedLocalClaimUris = null;
+                if (OAuthServerConfiguration.getInstance().getConvertOnlyMultiValuedClaimsToArray()) {
+                    multiValuedLocalClaimUris = OAuth2Util.getMultiValuedLocalClaimUris(spTenantDomain);
+                }
                 if (isNotEmpty(userClaims)) {
                     for (Map.Entry<String, String> entry : userClaims.entrySet()) {
                         //set local2sp role mappings
@@ -289,7 +296,8 @@ public static Map<String, Object> getClaimsFromUserStore(String authorizedUserNa
                             boolean isMultiValueSupportEnabledForUserinfoResponse = OAuthServerConfiguration
                                     .getInstance().getUserInfoMultiValueSupportEnabled();
                             if (isMultiValueSupportEnabledForUserinfoResponse &&
-                                    isMultiValuedAttribute(oidcClaimUri, claimValue)) {
+                                    isMultiValuedAttribute(oidcClaimUri, entry.getKey(), claimValue,
+                                            multiValuedLocalClaimUris)) {
                                 String[] attributeValues = processMultiValuedAttribute(claimValue);
                                 mappedAppClaims.put(oidcClaimUri, attributeValues);
                             } else {
@@ -575,6 +583,34 @@ public static boolean isMultiValuedAttribute(String claimUri, String claimValue)
         return StringUtils.contains(claimValue, FrameworkUtils.getMultiAttributeSeparator());
     }
 
+    /**
+     * Checks whether a user value is multivalued or not, honouring selective multi-valued claim handling.
+     * When {@code multiValuedLocalClaimUris} is non-null (i.e. the {@code ConvertOnlyMultiValuedClaimsToArray}
+     * configuration is enabled and the claim metadata was resolved), only claims whose local claim URI is flagged
+     * as multi-valued in claim metadata are treated as arrays. The {@code groups} claim is always treated as an
+     * array. A null set falls back to the legacy separator-based behaviour.
+     *
+     * @param claimUri                  OIDC dialect claim URI (short name).
+     * @param localClaimUri             Local claim URI mapped to the OIDC claim.
+     * @param claimValue                Claim value.
+     * @param multiValuedLocalClaimUris Set of local claim URIs flagged as multi-valued, or {@code null} for legacy
+     *                                  behaviour.
+     * @return Whether the claim should be emitted as a multi-valued (array) attribute.
+     */
+    public static boolean isMultiValuedAttribute(String claimUri, String localClaimUri, String claimValue,
+                                                 Set<String> multiValuedLocalClaimUris) {
+
+        /* To format the groups claim to always return as an array, we should consider single
+        group as multi value attribute. */
+        if (GROUPS.equals(claimUri)) {
+            return true;
+        }
+        if (multiValuedLocalClaimUris != null) {
+            return multiValuedLocalClaimUris.contains(localClaimUri);
+        }
+        return StringUtils.contains(claimValue, FrameworkUtils.getMultiAttributeSeparator());
+    }
+
     /**
      * Split multivalued attribute string value by attribute separator.
      *

components/org.wso2.carbon.identity.oauth.endpoint/src/test/java/org/wso2/carbon/identity/oauth/endpoint/util/ClaimUtilTest.java

@@ -66,8 +66,10 @@
 import java.lang.reflect.Field;
 import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.anyBoolean;
@@ -562,6 +564,56 @@ public void testGetServiceProviderMappedUserRoles(List<String> locallyMappedUser
         Assert.assertEquals(returned, expected, "Invalid returned value");
     }
 
+    private static final String GROUPS_CLAIM_URI = "groups";
+    private static final String GIVEN_NAME_OIDC_URI = "given_name";
+    private static final String GIVEN_NAME_LOCAL_URI = "http://wso2.org/claims/givenname";
+    private static final String MULTI_TEST_OIDC_URI = "multi_test";
+    private static final String MULTI_TEST_LOCAL_URI = "http://wso2.org/claims/multiTest";
+
+    @DataProvider(name = "selectiveMultiValuedAttributeProvider")
+    public Object[][] selectiveMultiValuedAttributeProvider() {
+
+        Set<String> multiValuedLocalClaimUris = new HashSet<>();
+        multiValuedLocalClaimUris.add(MULTI_TEST_LOCAL_URI);
+
+        return new Object[][]{
+                // claimUri, localClaimUri, claimValue, multiValuedLocalClaimUris (null = legacy), expectedMultiValued.
+
+                // Scenario (d): groups is always treated as an array, regardless of flag/value.
+                {GROUPS_CLAIM_URI, "http://wso2.org/claims/groups", "admin", null, true},
+                {GROUPS_CLAIM_URI, "http://wso2.org/claims/groups", "admin", multiValuedLocalClaimUris, true},
+
+                // Scenario (c): flag ON + claim flagged multiValued=true -> array, even without separator.
+                {MULTI_TEST_OIDC_URI, MULTI_TEST_LOCAL_URI, "a", multiValuedLocalClaimUris, true},
+                {MULTI_TEST_OIDC_URI, MULTI_TEST_LOCAL_URI, "a,b,c,d", multiValuedLocalClaimUris, true},
+
+                // Scenario (b): flag ON + claim flagged multiValued=false with comma value -> plain string (no array).
+                {GIVEN_NAME_OIDC_URI, GIVEN_NAME_LOCAL_URI, "a,b,c,d", multiValuedLocalClaimUris, false},
+                // Flag ON + non-flagged claim, no separator -> still not an array.
+                {GIVEN_NAME_OIDC_URI, GIVEN_NAME_LOCAL_URI, "a", multiValuedLocalClaimUris, false},
+
+                // Scenario (a): flag OFF (null set) -> legacy comma-split behaviour preserved.
+                {GIVEN_NAME_OIDC_URI, GIVEN_NAME_LOCAL_URI, "a,b,c,d", null, true},
+                {GIVEN_NAME_OIDC_URI, GIVEN_NAME_LOCAL_URI, "a", null, false},
+                // Legacy fallback applies to a flagged claim's local URI when the set is null (flag off).
+                {MULTI_TEST_OIDC_URI, MULTI_TEST_LOCAL_URI, "a", null, false},
+        };
+    }
+
+    @Test(dataProvider = "selectiveMultiValuedAttributeProvider")
+    public void testIsMultiValuedAttributeSelective(String claimUri, String localClaimUri, String claimValue,
+                                                    Set<String> multiValuedLocalClaimUris, boolean expected) {
+
+        try (MockedStatic<FrameworkUtils> frameworkUtils = mockStatic(FrameworkUtils.class)) {
+            frameworkUtils.when(FrameworkUtils::getMultiAttributeSeparator).thenReturn(CLAIM_SEPARATOR);
+            boolean actual = ClaimUtil.isMultiValuedAttribute(claimUri, localClaimUri, claimValue,
+                    multiValuedLocalClaimUris);
+            Assert.assertEquals(actual, expected,
+                    "Unexpected multi-valued resolution for claim '" + claimUri + "' (local '" + localClaimUri +
+                            "') with value '" + claimValue + "' and selectiveSet=" + multiValuedLocalClaimUris);
+        }
+    }
+
     @Test
     public void testResolveRoleClaimForImpersonatedSubOrgUser() throws Exception {
 

components/org.wso2.carbon.identity.oauth/src/main/java/org/wso2/carbon/identity/oauth/config/OAuthServerConfiguration.java

@@ -246,6 +246,7 @@ public class OAuthServerConfiguration {
     private List<String> supportedIdTokenEncryptionMethods = new ArrayList<>();
     private String userInfoJWTSignatureAlgorithm = "SHA256withRSA";
     private boolean userInfoMultiValueSupportEnabled = true;
+    private boolean convertOnlyMultiValuedClaimsToArray = false;
     private boolean userInfoRemoveInternalPrefixFromRoles = false;
     private boolean isReturnOnlyAppAssociatedRolesInUserInfo = false;
     private boolean isReturnOnlyAppAssociatedRolesInJWTToken = false;
@@ -1826,6 +1827,18 @@ public boolean getUserInfoMultiValueSupportEnabled() {
         return userInfoMultiValueSupportEnabled;
     }
 
+    /**
+     * Returns whether only claims flagged as multi-valued in claim metadata should be converted to a JSON array
+     * when building JWT access tokens and ID tokens. When disabled (default), the legacy behaviour applies where
+     * any claim value containing the multi attribute separator is split into an array.
+     *
+     * @return True if only multi-valued claims (per claim metadata) should be converted to an array.
+     */
+    public boolean getConvertOnlyMultiValuedClaimsToArray() {
+
+        return convertOnlyMultiValuedClaimsToArray;
+    }
+
     /**
      * Returns whether Internal prefix should be removed from the roles claim of the userinfo response.
      *
@@ -3934,6 +3947,13 @@ private void parseOpenIDConnectConfig(OMElement oauthConfigElem) {
                         userInfoMultiValueSupportEnabledElem.getText().trim());
             }
 
+            OMElement convertOnlyMultiValuedClaimsToArrayElem = openIDConnectConfigElem.getFirstChildWithName(
+                    getQNameWithIdentityNS(ConfigElements.OPENID_CONNECT_CONVERT_ONLY_MULTI_VALUED_CLAIMS_TO_ARRAY));
+            if (convertOnlyMultiValuedClaimsToArrayElem != null) {
+                convertOnlyMultiValuedClaimsToArray = Boolean.parseBoolean(
+                        convertOnlyMultiValuedClaimsToArrayElem.getText().trim());
+            }
+
             OMElement userInfoResponseRemoveInternalPrefixFromRoles = openIDConnectConfigElem.getFirstChildWithName(
                     getQNameWithIdentityNS(ConfigElements.OPENID_CONNECT_USERINFO_REMOVE_INTERNAL_PREFIX_FROM_ROLES));
             if (userInfoResponseRemoveInternalPrefixFromRoles != null) {
@@ -4681,6 +4701,8 @@ private class ConfigElements {
         public static final String OPENID_CONNECT_USERINFO_JWT_SIGNATURE_ALGORITHM = "UserInfoJWTSignatureAlgorithm";
         public static final String OPENID_CONNECT_USERINFO_MULTI_VALUE_SUPPORT_ENABLED =
                 "UserInfoMultiValueSupportEnabled";
+        public static final String OPENID_CONNECT_CONVERT_ONLY_MULTI_VALUED_CLAIMS_TO_ARRAY =
+                "ConvertOnlyMultiValuedClaimsToArray";
         public static final String OPENID_CONNECT_USERINFO_REMOVE_INTERNAL_PREFIX_FROM_ROLES =
                 "UserInfoRemoveInternalPrefixFromRoles";
         private static final String OPENID_CONNECT_RETURN_APP_ROLES_IN_USERINFO =

components/org.wso2.carbon.identity.oauth/src/main/java/org/wso2/carbon/identity/oauth2/util/OAuth2Util.java

@@ -93,6 +93,8 @@
 import org.wso2.carbon.identity.claim.metadata.mgt.ClaimMetadataManagementService;
 import org.wso2.carbon.identity.claim.metadata.mgt.exception.ClaimMetadataException;
 import org.wso2.carbon.identity.claim.metadata.mgt.model.ExternalClaim;
+import org.wso2.carbon.identity.claim.metadata.mgt.model.LocalClaim;
+import org.wso2.carbon.identity.claim.metadata.mgt.util.ClaimConstants;
 import org.wso2.carbon.identity.consent.server.configs.mgt.exceptions.ConsentServerConfigsMgtException;
 import org.wso2.carbon.identity.consent.server.configs.mgt.services.ConsentServerConfigsManagementService;
 import org.wso2.carbon.identity.core.IdentityKeyStoreResolver;
@@ -2320,6 +2322,41 @@ public static void initiateOIDCScopes(int tenantId) {
         }
     }
 
+    /**
+     * Build the set of local claim URIs that are flagged as multi-valued in claim metadata for the given tenant.
+     * Used when the {@code ConvertOnlyMultiValuedClaimsToArray} configuration is enabled so that only claims
+     * explicitly flagged as multi-valued are emitted as arrays (e.g. in the UserInfo response).
+     *
+     * @param tenantDomain Tenant domain to resolve claim metadata for.
+     * @return Set of local claim URIs flagged as multi-valued, or {@code null} if the metadata could not be
+     * resolved (so that callers fall back to legacy separator-based multi-valued claim handling).
+     */
+    public static Set<String> getMultiValuedLocalClaimUris(String tenantDomain) {
+
+        try {
+            ClaimMetadataManagementService claimMetadataManagementService =
+                    OAuth2ServiceComponentHolder.getInstance().getClaimMetadataManagementService();
+            if (claimMetadataManagementService == null) {
+                if (log.isDebugEnabled()) {
+                    log.debug("ClaimMetadataManagementService is not available. Falling back to legacy multi-valued " +
+                            "claim handling for tenant domain: " + tenantDomain);
+                }
+                return null;
+            }
+            Set<String> multiValuedLocalClaimUris = new HashSet<>();
+            for (LocalClaim localClaim : claimMetadataManagementService.getLocalClaims(tenantDomain)) {
+                if (Boolean.parseBoolean(localClaim.getClaimProperty(ClaimConstants.MULTI_VALUED_PROPERTY))) {
+                    multiValuedLocalClaimUris.add(localClaim.getClaimURI());
+                }
+            }
+            return multiValuedLocalClaimUris;
+        } catch (ClaimMetadataException e) {
+            log.error("Error while retrieving claim metadata to determine multi-valued claims for tenant domain: " +
+                    tenantDomain + ". Falling back to legacy multi-valued claim handling.", e);
+            return null;
+        }
+    }
+
     public static List<String> getOIDCScopes(String tenantDomain) {
 
         List<String> scopes = new ArrayList<>();