feat: OIDC extract claims from OIDC IdToken, UserInfo Endpoint and User attributes

jornfranke · jornfranke · commit 4ef2eadf4218 · 2025-03-02T17:27:55.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Backend: Spring Boot 3.4.3, Spring Modulith 1.3.2, Hibernate 6.6.8.Final
 * Backend: Gradle Plugins: Spring Dependency Plugin 1.1.7, Spotless 7.0.2, CycloneDX 2.1.0, Ben Names Update Plugin 0.52.0
 * Backend: Build tool Gradle 8.12, BouncyCastle 1.80
+* Backend: OIDC: Support extraction of claims from IdToken, EndUser Endpoint and end user attributes. Claims are converted to Granted Authorities (roles) thart can natively be used in Spring for authorizing access
 * Frontend: Angular 19.1.1
 * Container: Remove JDK parameter for generational ZGC as it will be anyway the [only possible in upcoming JDKs](https://openjdk.org/jeps/474).
 
diff --git a/backend/docs/CONFIGURE.md b/backend/docs/CONFIGURE.md
@@ -261,18 +261,26 @@ Example:
 application:
   saml2:
        samlRoleAttributeName: "groups" # the SAML Assertation Attribute that contains the role(s)
-        samlRoleAttributeSeparator: "," # if the SAML Asseration Attribute value contains multiple roles then you can specify the separator (if the roles are in multiple attributes then you can ignore it)
+       samlRoleAttributeSeparator: "," # if the SAML Asseration Attribute value contains multiple roles then you can specify the separator (if the roles are in multiple attributes then you can ignore it)
 ```
 
 You can find a complete example in [](../../config/config-saml2.yml).
 
-## OIDC Role Mapping
-By default OIDC claims are made available as a Spring Authority with the prefix "SCOPE_". You can configure any other prefix as follows.
+## OIDC Claims to Role Mapping
+By default OIDC claims "scope, scp" are made available as a Spring Authority with the prefix "SCOPE_". These come from the [OIDC IdToken](https://openid.net/specs/openid-connect-core-1_0-final.html#StandardClaims). However, often additional claims are needed for Spring Security Authorities (roles), e.g. "groups" in a user directory. Those usually do not come from the OIDC IdToken, but only from the [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0-final.html#UserInfoResponse). You can configure here for both, IdToken and UserInfo endpoint, which claims should be mapped to Spring Security Authorities. Furthermore, you can configure for each claim how they are mapped to authorities. By default, it is assumed that the claims are JSON String arrays, but in case they are string you can define how they are extracted from the String using the claimsSeparatorMap. For example, lets assume the claim "groups" is returned by the UserInfo Endpoint as one String representing a comma-separated list groups. You can define as a separator the "," and the claim is then split accordingly so that you do not have the list of groups as one Spring Security Authority, but multiple representing each one of the groups.
 
+Independent of this you can also map user attributes to Spring Security Authorities.
+
+Finally, you can optionally define a prefix for each claim in the Spring Security Authorities. If you do not want any prefix just specify an empty String.
+```
      oidc:
         mapper: # map jwt claims to Spring Security authorities
-            jwtRoleClaims: ["scope","scp"] # JWT claims that contain authorities
-            authoritiesPrefix: "SCOPE_" # Prefix for Spring Security Authorities
+            jwtIdTokenClaims: ["scope","scp"] # claims from a standard OIDC IdToken https://openid.net/specs/openid-connect-core-1_0-final.html#StandardClaims
+            userClaims: ["groups"] # claims from the UserInfo OIDC Endpoint (https://openid.net/specs/openid-connect-core-1_0-final.html#UserInfoResponse)
+            userAttributes: [] # user attributes to be mapped to Spring Security Authorities
+            claimsSeparatorMap: {"scope": " ", "scp": " ", "groups": ","} # separator if claims are one string, otherwise a JSON array is assumed
+            authoritiesPrefix: "ROLE_" # Prefix for Spring Security Authorities
+```
 ## Web Security Headers
 Web Security Headers are an additional line of defense to enable specific protection mechanisms against attacks (e.g. cross-site scripting) in the browser of the user.
 
diff --git a/backend/src/main/java/eu/zuinnote/example/springwebdemo/configuration/SecurityConfigurationOidc.java b/backend/src/main/java/eu/zuinnote/example/springwebdemo/configuration/SecurityConfigurationOidc.java
@@ -3,13 +3,27 @@
 import static org.springframework.security.config.Customizer.withDefaults;
 
 import eu.zuinnote.example.springwebdemo.configuration.application.ApplicationConfig;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
 import lombok.extern.log4j.Log4j2;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.context.annotation.Profile;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
 import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.core.GrantedAuthority;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
+import org.springframework.security.core.authority.mapping.GrantedAuthoritiesMapper;
+import org.springframework.security.oauth2.core.oidc.OidcIdToken;
+import org.springframework.security.oauth2.core.oidc.OidcUserInfo;
+import org.springframework.security.oauth2.core.oidc.user.OidcUserAuthority;
+import org.springframework.security.oauth2.core.user.OAuth2UserAuthority;
 import org.springframework.security.web.SecurityFilterChain;
 
 @Configuration
@@ -37,4 +51,108 @@ SecurityFilterChain app(HttpSecurity http) throws Exception {
         this.generalSecurityConfiguration.setRequireSecure(http);
         return http.build();
     }
+
+    /*
+     * Custom OIDC claim to Spring GrantedAuthority mapper so that they can be used natively in Spring.
+     *
+     * See: https://docs.spring.io/spring-security/reference/servlet/oauth2/login/advanced.html#oauth2login-advanced-map-authorities
+     *
+     */
+    @Bean
+    public GrantedAuthoritiesMapper userAuthoritiesMapper() {
+        return (authorities) -> {
+            Set<GrantedAuthority> mappedAuthorities = new HashSet<>();
+
+            authorities.forEach(
+                    authority -> {
+                        if (OidcUserAuthority.class.isInstance(authority)) {
+                            OidcUserAuthority oidcUserAuthority = (OidcUserAuthority) authority;
+
+                            OidcIdToken idToken = oidcUserAuthority.getIdToken();
+                            OidcUserInfo userInfo = oidcUserAuthority.getUserInfo();
+
+                            // map all claims from the IdToken
+                            for (String idTokenClaim :
+                                    this.config.getOidc().getMapper().getJwtIdTokenClaims()) {
+                                Object claim = idToken.getClaim(idTokenClaim);
+                                mappedAuthorities.addAll(
+                                        this.parseClaim("IdToken", idTokenClaim, claim));
+                            }
+                            // map all claims from the EndUser Endpoint
+                            for (String endUserEndpointClaim :
+                                    this.config.getOidc().getMapper().getUserClaims()) {
+                                Object claim = userInfo.getClaim(endUserEndpointClaim);
+                                mappedAuthorities.addAll(
+                                        this.parseClaim(
+                                                "EndUser Endpoint", endUserEndpointClaim, claim));
+                            }
+
+                        } else if (OAuth2UserAuthority.class.isInstance(authority)) {
+                            OAuth2UserAuthority oauth2UserAuthority =
+                                    (OAuth2UserAuthority) authority;
+
+                            Map<String, Object> userAttributes =
+                                    oauth2UserAuthority.getAttributes();
+
+                            // Map the attributes found in userAttributes
+                            for (String userAttribute :
+                                    this.config.getOidc().getMapper().getUserAttributes()) {
+                                Object claim = userAttributes.get(userAttribute);
+                                mappedAuthorities.addAll(
+                                        this.parseClaim(
+                                                "EndUser Attributes", userAttribute, claim));
+                            }
+                        }
+                    });
+
+            return mappedAuthorities;
+        };
+    }
+
+    /* Parses a claim and converts it to a set of GrantedAuthority
+     *
+     * @type from where claim comes from (e.g. IdToken, UserInfoEndpoint, UserAtttribute)
+     * @claim name of the claim (e.g. scope)
+     * @claimValue value of the claim
+     *
+     */
+    private Set<GrantedAuthority> parseClaim(String type, String claim, Object claimValue) {
+        Set<GrantedAuthority> result = new HashSet<>();
+        String authorityPrefix = this.config.getOidc().getMapper().getAuthoritiesPrefix();
+        if (claimValue != null) {
+            if (claimValue instanceof String) {
+                HashMap<String, String> separatorMap =
+                        this.config.getOidc().getMapper().getClaimsSeparatorMap();
+                if ((separatorMap != null)
+                        && separatorMap.containsKey(
+                                claim)) { // check if we should parse the a list from the claim
+                    String separator =
+                            this.config.getOidc().getMapper().getClaimsSeparatorMap().get(claim);
+
+                    result.addAll(
+                            Arrays.asList(claimValue.toString().split(separator)).stream()
+                                    .map(s -> authorityPrefix + s)
+                                    .map(SimpleGrantedAuthority::new)
+                                    .collect(Collectors.toCollection(HashSet::new)));
+                } else {
+                    result.add(new SimpleGrantedAuthority(authorityPrefix + claimValue.toString()));
+                }
+
+            } else if (claimValue
+                    instanceof Collection) { // claim is already a list so simply converted them to
+                // GrantedAuthority
+                result.addAll(
+                        ((Collection<?>) claimValue)
+                                .stream()
+                                        .map(Object::toString)
+                                        .map(s -> authorityPrefix + s)
+                                        .map(SimpleGrantedAuthority::new)
+                                        .collect(Collectors.toCollection(HashSet::new)));
+            } else { // unknown type of claim cannot be processed
+                this.log.error(
+                        String.format("Error: Claim %s in %type has an unknown type", claim, type));
+            }
+        }
+        return result;
+    }
 }
diff --git a/backend/src/main/java/eu/zuinnote/example/springwebdemo/configuration/application/oidc/OidcMapper.java b/backend/src/main/java/eu/zuinnote/example/springwebdemo/configuration/application/oidc/OidcMapper.java
@@ -1,12 +1,16 @@
 package eu.zuinnote.example.springwebdemo.configuration.application.oidc;
 
 import java.util.ArrayList;
+import java.util.HashMap;
 import org.springframework.validation.annotation.Validated;
 
 @Validated
 public class OidcMapper {
     private String authoritiesPrefix;
-    private ArrayList<String> jwtRoleClaims;
+    private ArrayList<String> jwtIdTokenClaims;
+    private ArrayList<String> userClaims;
+    private ArrayList<String> userAttributes;
+    private HashMap<String, String> claimsSeparatorMap;
 
     public String getAuthoritiesPrefix() {
         return this.authoritiesPrefix;
@@ -16,11 +20,35 @@ public void setAuthoritiesPrefix(String authoritiesPrefix) {
         this.authoritiesPrefix = authoritiesPrefix;
     }
 
-    public ArrayList<String> getJwtRoleClaims() {
-        return this.jwtRoleClaims;
+    public HashMap<String, String> getClaimsSeparatorMap() {
+        return this.claimsSeparatorMap;
     }
 
-    public void setJwtRoleClaims(ArrayList<String> jwtRoleClaims) {
-        this.jwtRoleClaims = jwtRoleClaims;
+    public void setClaimsSeparatorMap(HashMap<String, String> claimsSeparatorMap) {
+        this.claimsSeparatorMap = claimsSeparatorMap;
+    }
+
+    public ArrayList<String> getJwtIdTokenClaims() {
+        return this.jwtIdTokenClaims;
+    }
+
+    public void setJwtIdTokenClaims(ArrayList<String> jwtIdTokenClaims) {
+        this.jwtIdTokenClaims = jwtIdTokenClaims;
+    }
+
+    public ArrayList<String> getUserClaims() {
+        return this.userClaims;
+    }
+
+    public void setUserClaims(ArrayList<String> userClaims) {
+        this.userClaims = userClaims;
+    }
+
+    public ArrayList<String> getUserAttributes() {
+        return this.userAttributes;
+    }
+
+    public void setUserAttributes(ArrayList<String> userAttributes) {
+        this.userAttributes = userAttributes;
     }
 }
diff --git a/config/config-oidc.yml b/config/config-oidc.yml
@@ -47,8 +47,11 @@ h2: # only for testing purposes
 application:
      oidc:
         mapper: # map jwt claims to Spring Security authorities
-            jwtRoleClaims: ["scope","scp"] # JWT claims that contain authorities
-            authoritiesPrefix: "SCOPE_" # Prefix for Spring Security Authorities
+            jwtIdTokenClaims: ["scope","scp"] # claims from a standard OIDC IdToken https://openid.net/specs/openid-connect-core-1_0-final.html#StandardClaims
+            userClaims: ["groups"] # claims from the UserInfo OIDC Endpoint (https://openid.net/specs/openid-connect-core-1_0-final.html#UserInfoResponse)
+            userAttributes: [] # user attributes to be mapped to Spring Security Authorities
+            claimsSeparatorMap: {"scope": " ", "scp": " ", "groups": ","} # separator if claims are one string, otherwise a JSON array is assumed
+            authoritiesPrefix: "ROLE_" # Prefix for Spring Security Authorities
      https:
         headers:
           permissionPolicy: "accelerometer=(),  autoplay=(), camera=(), cross-origin-isolated=(), display-capture=(),  encrypted-media=(),  fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(),  payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(), usb=(), web-share=(), xr-spatial-tracking=(), clipboard-read=(), clipboard-write=(), gamepad=(),  hid=(), idle-detection=(), serial=(),  window-placement=()"
