feat: make admin elevation scope configurable (#5816)

* feat: make admin elevation scope configurable

The admin elevation in the oauth2 auth libs (ownership bypass in
AuthorizationServiceImpl and the participant-context existence-skip in
ServicePrincipalAuthenticationFilter) was hardcoded to `management-api:admin`.
Add a `String... adminScopes` constructor to both (the no-arg / single-arg
constructors keep the `management-api:admin` default), so downstream APIs with
their own scope namespace (e.g. IdentityHub's `identity-api:admin` /
`issuer-admin-api:admin`) can confer elevation within their namespace. Fully
backward-compatible.

Signed-off-by: Paul Latzelsperger <paul.latzelsperger@beardyinc.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* update version file

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: paullatzelsperger

extensions/common/api/management-api-configuration/src/main/resources/management-api-version.json

@@ -14,7 +14,7 @@
   {
     "version": "5.0.0-beta",
     "urlPath": "/v5beta",
-    "lastUpdated": "2026-06-11T09:00:00Z",
+    "lastUpdated": "2026-06-11T16:00:00Z",
     "maturity": "beta"
   }
 ]

extensions/common/auth/auth-authentication-oauth2-lib/src/main/java/org/eclipse/edc/api/authentication/filter/ServicePrincipalAuthenticationFilter.java

@@ -20,13 +20,15 @@
 import jakarta.ws.rs.container.ContainerRequestFilter;
 import jakarta.ws.rs.core.Response;
 import jakarta.ws.rs.core.SecurityContext;
+import org.eclipse.edc.api.auth.spi.ManagementApiScopes;
 import org.eclipse.edc.api.auth.spi.ParticipantPrincipal;
 import org.eclipse.edc.api.auth.spi.ScopeMatcher;
 import org.eclipse.edc.participantcontext.spi.service.ParticipantContextService;
 import org.eclipse.edc.spi.iam.ClaimToken;
 import org.eclipse.edc.spi.result.Result;
 
 import java.security.Principal;
+import java.util.List;
 
 import static org.eclipse.edc.api.authentication.filter.Constants.REQUEST_PROPERTY_CLAIMS;
 import static org.eclipse.edc.jwt.spi.JwtRegisteredClaimNames.SCOPE;
@@ -42,9 +44,22 @@ public class ServicePrincipalAuthenticationFilter implements ContainerRequestFil
 
     private final ParticipantContextService participantContextService;
     private final ScopeMatcher scopeMatcher = new ScopeMatcher();
+    private final List<String> adminScopes;
 
     public ServicePrincipalAuthenticationFilter(ParticipantContextService participantContextService) {
+        this(participantContextService, ManagementApiScopes.ADMIN);
+    }
+
+    /**
+     * Creates a filter whose admin elevation is conferred by the supplied scopes.
+     *
+     * @param adminScopes the scopes that convey admin elevation. A token whose granted scope satisfies any of these is
+     *                    treated as an (elevated) service account, so its {@code sub} need not reference an existing
+     *                    participant context. Defaults to {@link ManagementApiScopes#ADMIN}.
+     */
+    public ServicePrincipalAuthenticationFilter(ParticipantContextService participantContextService, String... adminScopes) {
         this.participantContextService = participantContextService;
+        this.adminScopes = List.of(adminScopes);
     }
 
     @Override
@@ -102,7 +117,7 @@ public String getAuthenticationScheme() {
      */
     private Result<Void> isAuthorized(String scope, String subject) {
 
-        if (scopeMatcher.isAdmin(scope)) {
+        if (isAdmin(scope)) {
             return Result.success();
         }
         if (subject == null) {
@@ -113,4 +128,8 @@ private Result<Void> isAuthorized(String scope, String subject) {
         }
         return Result.success();
     }
+
+    private boolean isAdmin(String grantedScopes) {
+        return adminScopes.stream().anyMatch(adminScope -> scopeMatcher.isSatisfiedBy(adminScope, grantedScopes));
+    }
 }

extensions/common/auth/auth-authentication-oauth2-lib/src/test/java/org/eclipse/edc/api/authentication/filter/ServicePrincipalAuthenticationFilterTest.java

@@ -100,6 +100,38 @@ void filter_adminSubjectNotParticipantContext_isAllowed() {
         verify(request).setSecurityContext(argThat(sc -> sc.getUserPrincipal() instanceof ParticipantPrincipal));
     }
 
+    @Test
+    void filter_customAdminScope_skipsExistenceCheck() {
+        // a filter configured with a custom admin scope treats that scope (not management-api:admin) as elevated
+        var customFilter = new ServicePrincipalAuthenticationFilter(participantContextService, "identity-api:admin");
+        when(participantContextService.getParticipantContext(anyString())).thenReturn(ServiceResult.notFound("not a participant context"));
+        var request = mock(ContainerRequestContext.class);
+        when(request.getProperty(REQUEST_PROPERTY_CLAIMS)).thenReturn(ClaimToken.Builder.newInstance()
+                .claim(SCOPE, "identity-api:admin")
+                .claim(SUBJECT, "some-service-account")
+                .build());
+
+        customFilter.filter(request);
+
+        verify(request).setSecurityContext(argThat(sc -> sc.getUserPrincipal() instanceof ParticipantPrincipal));
+    }
+
+    @Test
+    void filter_customAdminScope_managementAdminNotElevated() {
+        // with a custom admin scope configured, a management-api:admin token is not elevated, so its subject must exist
+        var customFilter = new ServicePrincipalAuthenticationFilter(participantContextService, "identity-api:admin");
+        when(participantContextService.getParticipantContext(anyString())).thenReturn(ServiceResult.notFound("not a participant context"));
+        var request = mock(ContainerRequestContext.class);
+        when(request.getProperty(REQUEST_PROPERTY_CLAIMS)).thenReturn(ClaimToken.Builder.newInstance()
+                .claim(SCOPE, ManagementApiScopes.ADMIN)
+                .claim(SUBJECT, "some-service-account")
+                .build());
+
+        customFilter.filter(request);
+
+        verify(request).abortWith(argThat(response -> response.getStatus() == Response.Status.UNAUTHORIZED.getStatusCode()));
+    }
+
     @Test
     void filter_claimsNotPresent() {
         var request = mock(ContainerRequestContext.class);

extensions/common/auth/auth-authorization-oauth2-lib/src/main/java/org/eclipse/edc/api/authorization/service/AuthorizationServiceImpl.java

@@ -16,19 +16,37 @@
 
 import jakarta.ws.rs.core.SecurityContext;
 import org.eclipse.edc.api.auth.spi.AuthorizationService;
+import org.eclipse.edc.api.auth.spi.ManagementApiScopes;
 import org.eclipse.edc.api.auth.spi.ParticipantPrincipal;
 import org.eclipse.edc.api.auth.spi.ScopeMatcher;
 import org.eclipse.edc.participantcontext.spi.types.ParticipantResource;
 import org.eclipse.edc.spi.result.ServiceResult;
 
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 import java.util.function.BiFunction;
 
 public class AuthorizationServiceImpl implements AuthorizationService {
     private final Map<Class<?>, BiFunction<String, String, ParticipantResource>> resourceLookupFunctions = new HashMap<>();
     private final ScopeMatcher scopeMatcher = new ScopeMatcher();
+    private final List<String> adminScopes;
+
+    public AuthorizationServiceImpl() {
+        this(ManagementApiScopes.ADMIN);
+    }
+
+    /**
+     * Creates a service whose cross-participant (admin) elevation is conferred by the supplied scopes.
+     *
+     * @param adminScopes the scopes that convey cross-participant (admin) elevation. A principal whose granted scope
+     *                    satisfies any of these bypasses the resource-ownership check. Defaults to
+     *                    {@link ManagementApiScopes#ADMIN} when the no-arg constructor is used.
+     */
+    public AuthorizationServiceImpl(String... adminScopes) {
+        this.adminScopes = List.of(adminScopes);
+    }
 
     @Override
     public ServiceResult<Void> authorize(SecurityContext securityContext, String resourceOwnerId, String resourceId, Class<? extends ParticipantResource> resourceClass) {
@@ -49,8 +67,8 @@ public ServiceResult<Void> authorize(SecurityContext securityContext, String res
             return ServiceResult.notFound("No Resource of type '%s' with ID '%s' was found for owner '%s'.".formatted(resourceClass, resourceId, resourceOwnerId));
         }
 
-        // a principal holding the admin scope is elevated and may access resources across participant contexts
-        if (principal instanceof ParticipantPrincipal participantPrincipal && scopeMatcher.isAdmin(participantPrincipal.scope())) {
+        // a principal holding an admin scope is elevated and may access resources across participant contexts
+        if (principal instanceof ParticipantPrincipal participantPrincipal && isAdmin(participantPrincipal.scope())) {
             return ServiceResult.success();
         }
 
@@ -63,6 +81,10 @@ public ServiceResult<Void> authorize(SecurityContext securityContext, String res
 
     }
 
+    private boolean isAdmin(String grantedScopes) {
+        return adminScopes.stream().anyMatch(adminScope -> scopeMatcher.isSatisfiedBy(adminScope, grantedScopes));
+    }
+
     @Override
     public void addLookupFunction(Class<?> resourceClass, BiFunction<String, String, ParticipantResource> lookupFunction) {
         resourceLookupFunctions.put(resourceClass, lookupFunction);

extensions/common/auth/auth-authorization-oauth2-lib/src/test/java/org/eclipse/edc/api/authorization/service/AuthorizationServiceImplTest.java

@@ -123,6 +123,42 @@ public String getParticipantContextId() {
                 .satisfies(f -> assertThat(f.getReason()).isEqualTo(ServiceFailure.Reason.UNAUTHORIZED));
     }
 
+    @Test
+    void authorize_whenCustomAdminScope_bypassesOwnership() {
+        var service = new AuthorizationServiceImpl("identity-api:admin");
+        service.addLookupFunction(TestResource.class, (owner, id) -> new AbstractParticipantResource() {
+            @Override
+            public String getParticipantContextId() {
+                return "owner-id";
+            }
+        });
+        var principal = new ParticipantPrincipal("a-different-principal", "identity-api:admin");
+        var securityContext = mock(SecurityContext.class);
+        when(securityContext.getUserPrincipal()).thenReturn(principal);
+
+        assertThat(service.authorize(securityContext, "owner-id", "test-resource-id", TestResource.class))
+                .isSucceeded();
+    }
+
+    @Test
+    void authorize_whenCustomAdminScope_managementAdminDoesNotElevate() {
+        // with a custom admin scope configured, the default management-api:admin no longer elevates
+        var service = new AuthorizationServiceImpl("identity-api:admin");
+        service.addLookupFunction(TestResource.class, (owner, id) -> new AbstractParticipantResource() {
+            @Override
+            public String getParticipantContextId() {
+                return "owner-id";
+            }
+        });
+        var principal = new ParticipantPrincipal("a-different-principal", "management-api:admin");
+        var securityContext = mock(SecurityContext.class);
+        when(securityContext.getUserPrincipal()).thenReturn(principal);
+
+        assertThat(service.authorize(securityContext, "owner-id", "test-resource-id", TestResource.class))
+                .isFailed()
+                .satisfies(f -> assertThat(f.getReason()).isEqualTo(ServiceFailure.Reason.UNAUTHORIZED));
+    }
+
     @Test
     void authorize_whenNoOwner() {
         authorizationService.addLookupFunction(TestResource.class, (owner, id) -> new AbstractParticipantResource() {

spi/common/auth-spi/src/main/java/org/eclipse/edc/api/auth/spi/ScopeMatcher.java

@@ -14,6 +14,8 @@
 
 package org.eclipse.edc.api.auth.spi;
 
+import org.eclipse.edc.spi.result.AbstractResult;
+
 import java.util.Arrays;
 import java.util.List;
 
@@ -54,8 +56,8 @@ private List<Scope> parse(String grantedScopes) {
         return Arrays.stream(grantedScopes.trim().split(SCOPE_SEPARATOR))
                 .filter(s -> !s.isBlank())
                 .map(Scope::parse)
-                .filter(result -> result.succeeded())
-                .map(result -> result.getContent())
+                .filter(AbstractResult::succeeded)
+                .map(AbstractResult::getContent)
                 .toList();
     }
 }