You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@polaris.apache.org by ad...@apache.org on 2026/09/28 11:39:36 UTC

(polaris) branch main updated: Consolidate security augmentors into PolarisSecurityIdentityAugmentor (#5612)

This is an automated email from the ASF dual-hosted git repository.

adutra pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/polaris.git


The following commit(s) were added to refs/heads/main by this push:
     new 07669706df Consolidate security augmentors into PolarisSecurityIdentityAugmentor (#5612)
07669706df is described below

commit 07669706dfefcc817ff0eb30159b212c1eb415aa
Author: Alexandre Dutra <ad...@apache.org>
AuthorDate: Mon Sep 28 13:39:30 2026 +0200

    Consolidate security augmentors into PolarisSecurityIdentityAugmentor (#5612)
    
    Replace the three-augmentor chain (`OidcTenantResolvingAugmentor` ->
    `OidcPolarisCredentialAugmentor`-> `AuthenticatingAugmentor`) with a
    single `PolarisSecurityIdentityAugmentor` that delegates OIDC
    preparation to a new `OidcIdentityPreparer` CDI bean, eliminating the
    implicit priority-based ordering.
---
 ....java => PolarisSecurityIdentityAugmentor.java} |  23 ++--
 ...ialAugmentor.java => OidcIdentityPreparer.java} |  84 +++++++------
 .../external/mapping/DefaultPrincipalMapper.java   |   2 +-
 .../mapping/DefaultPrincipalRolesMapper.java       |   2 +-
 .../tenant/OidcTenantResolvingAugmentor.java       |  75 -----------
 ...a => PolarisSecurityIdentityAugmentorTest.java} |  40 +++++-
 ...ntorTest.java => OidcIdentityPreparerTest.java} | 137 +++++++++------------
 .../external/OidcTenantResolvingAugmentorTest.java |  98 ---------------
 .../mapping/DefaultPrincipalMapperTest.java        |   2 +-
 .../mapping/DefaultPrincipalRolesMapperTest.java   |   2 +-
 .../external-idp/idp-dev-notes.md                  |   7 +-
 11 files changed, 168 insertions(+), 304 deletions(-)

diff --git a/runtime/service/src/main/java/org/apache/polaris/service/auth/AuthenticatingAugmentor.java b/runtime/service/src/main/java/org/apache/polaris/service/auth/PolarisSecurityIdentityAugmentor.java
similarity index 69%
rename from runtime/service/src/main/java/org/apache/polaris/service/auth/AuthenticatingAugmentor.java
rename to runtime/service/src/main/java/org/apache/polaris/service/auth/PolarisSecurityIdentityAugmentor.java
index 0fcc88bad5..c8e8699c9d 100644
--- a/runtime/service/src/main/java/org/apache/polaris/service/auth/AuthenticatingAugmentor.java
+++ b/runtime/service/src/main/java/org/apache/polaris/service/auth/PolarisSecurityIdentityAugmentor.java
@@ -26,24 +26,32 @@ import io.smallrye.mutiny.Uni;
 import jakarta.enterprise.context.ApplicationScoped;
 import jakarta.inject.Inject;
 import org.apache.polaris.core.auth.PolarisPrincipal;
+import org.apache.polaris.service.auth.external.OidcIdentityPreparer;
 
 /**
- * A custom {@link SecurityIdentityAugmentor} that, after Quarkus OIDC or Internal Auth extracted
- * and validated the principal credentials, augments the {@link SecurityIdentity} by authenticating
- * the principal.
+ * A custom {@link SecurityIdentityAugmentor} that augments the already-authenticated {@link
+ * SecurityIdentity} with Polaris-specific requirements.
  *
+ * <p>First, it prepares OIDC identities, if applicable, so that all identities expose a valid
+ * {@link PolarisCredential}; and finally, it invokes the {@link Authenticator} and sets the
+ * produced {@link PolarisPrincipal} as the identity's principal.
+ *
+ * @see OidcIdentityPreparer
  * @see Authenticator
  */
 @ApplicationScoped
-public class AuthenticatingAugmentor implements SecurityIdentityAugmentor {
+public class PolarisSecurityIdentityAugmentor implements SecurityIdentityAugmentor {
 
   public static final int PRIORITY = 1000;
 
   private final Authenticator authenticator;
+  private final OidcIdentityPreparer oidcIdentityPreparer;
 
   @Inject
-  public AuthenticatingAugmentor(Authenticator authenticator) {
+  public PolarisSecurityIdentityAugmentor(
+      Authenticator authenticator, OidcIdentityPreparer oidcIdentityPreparer) {
     this.authenticator = authenticator;
+    this.oidcIdentityPreparer = oidcIdentityPreparer;
   }
 
   @Override
@@ -60,10 +68,11 @@ public class AuthenticatingAugmentor implements SecurityIdentityAugmentor {
   }
 
   private SecurityIdentity authenticatePolarisPrincipal(SecurityIdentity identity) {
-    PolarisPrincipal polarisPrincipal = authenticator.authenticate(identity);
+    SecurityIdentity preparedIdentity = oidcIdentityPreparer.prepare(identity);
+    PolarisPrincipal polarisPrincipal = authenticator.authenticate(preparedIdentity);
     // Do not merge the principal attributes into the security identity's attributes:
     // these must stay separate.
-    return QuarkusSecurityIdentity.builder(identity)
+    return QuarkusSecurityIdentity.builder(preparedIdentity)
         .setAnonymous(false)
         .setPrincipal(polarisPrincipal)
         .addRoles(polarisPrincipal.getRoles())
diff --git a/runtime/service/src/main/java/org/apache/polaris/service/auth/external/OidcPolarisCredentialAugmentor.java b/runtime/service/src/main/java/org/apache/polaris/service/auth/external/OidcIdentityPreparer.java
similarity index 52%
rename from runtime/service/src/main/java/org/apache/polaris/service/auth/external/OidcPolarisCredentialAugmentor.java
rename to runtime/service/src/main/java/org/apache/polaris/service/auth/external/OidcIdentityPreparer.java
index 0ddbaa4268..75416ba45a 100644
--- a/runtime/service/src/main/java/org/apache/polaris/service/auth/external/OidcPolarisCredentialAugmentor.java
+++ b/runtime/service/src/main/java/org/apache/polaris/service/auth/external/OidcIdentityPreparer.java
@@ -18,93 +18,103 @@
  */
 package org.apache.polaris.service.auth.external;
 
-import static org.apache.polaris.service.auth.external.tenant.OidcTenantResolvingAugmentor.getOidcTenantConfig;
-
-import io.quarkus.security.identity.AuthenticationRequestContext;
 import io.quarkus.security.identity.SecurityIdentity;
-import io.quarkus.security.identity.SecurityIdentityAugmentor;
 import io.quarkus.security.runtime.QuarkusSecurityIdentity;
 import io.smallrye.common.annotation.Identifier;
-import io.smallrye.mutiny.Uni;
 import jakarta.enterprise.context.ApplicationScoped;
 import jakarta.enterprise.inject.Any;
 import jakarta.enterprise.inject.Instance;
 import jakarta.inject.Inject;
 import java.util.Set;
-import org.apache.polaris.service.auth.AuthenticatingAugmentor;
 import org.apache.polaris.service.auth.AuthenticationRealmConfiguration;
 import org.apache.polaris.service.auth.CredentialMode;
 import org.apache.polaris.service.auth.PolarisCredential;
 import org.apache.polaris.service.auth.external.mapping.PrincipalMapper;
 import org.apache.polaris.service.auth.external.mapping.PrincipalRolesMapper;
 import org.apache.polaris.service.auth.external.tenant.OidcTenantConfiguration;
+import org.apache.polaris.service.auth.external.tenant.OidcTenantResolver;
 import org.eclipse.microprofile.jwt.JsonWebToken;
 
 /**
- * A {@link SecurityIdentityAugmentor} that maps the access token claims, as provided by the OIDC
- * authentication mechanism, to a {@link PolarisCredential}.
+ * Prepares an OIDC {@link SecurityIdentity} for authentication by resolving the OIDC tenant
+ * configuration and mapping JWT claims to a {@link PolarisCredential}.
+ *
+ * <p>This bean consolidates the OIDC-specific preparation that must happen before {@link
+ * org.apache.polaris.service.auth.Authenticator} is invoked. It:
+ *
+ * <ol>
+ *   <li>Resolves the OIDC tenant configuration via {@link OidcTenantResolver} and attaches it as an
+ *       identity attribute so that {@link
+ *       org.apache.polaris.service.auth.external.mapping.PrincipalMapper} and {@link
+ *       org.apache.polaris.service.auth.external.mapping.PrincipalRolesMapper} implementations can
+ *       access it.
+ *   <li>Maps the JWT claims to a {@link PolarisCredential} and adds it to the identity.
+ * </ol>
+ *
+ * @see org.apache.polaris.service.auth.PolarisSecurityIdentityAugmentor
  */
 @ApplicationScoped
-public class OidcPolarisCredentialAugmentor implements SecurityIdentityAugmentor {
+public class OidcIdentityPreparer {
 
-  // must run before the authenticating augmentor
-  public static final int PRIORITY = AuthenticatingAugmentor.PRIORITY + 100;
+  public static final String TENANT_CONFIG_ATTRIBUTE =
+      "org.apache.polaris.service.auth.TENANT_CONFIG";
 
   private final AuthenticationRealmConfiguration authConfig;
+  private final OidcTenantResolver resolver;
   private final Instance<PrincipalMapper> principalMappers;
   private final Instance<PrincipalRolesMapper> principalRoleMappers;
 
   @Inject
-  public OidcPolarisCredentialAugmentor(
+  public OidcIdentityPreparer(
       AuthenticationRealmConfiguration authConfig,
+      OidcTenantResolver resolver,
       @Any Instance<PrincipalMapper> principalMappers,
       @Any Instance<PrincipalRolesMapper> principalRoleMappers) {
     this.authConfig = authConfig;
+    this.resolver = resolver;
     this.principalMappers = principalMappers;
     this.principalRoleMappers = principalRoleMappers;
   }
 
-  @Override
-  public int priority() {
-    return PRIORITY;
+  public static OidcTenantConfiguration getOidcTenantConfig(SecurityIdentity identity) {
+    return identity.getAttribute(TENANT_CONFIG_ATTRIBUTE);
   }
 
-  @Override
-  public Uni<SecurityIdentity> augment(
-      SecurityIdentity identity, AuthenticationRequestContext context) {
-    if (identity.isAnonymous() || !(identity.getPrincipal() instanceof JsonWebToken)) {
-      return Uni.createFrom().item(identity);
+  /**
+   * Prepares the given identity for authentication. For OIDC identities (where the principal is a
+   * {@link JsonWebToken}), resolves the tenant configuration and maps JWT claims to a {@link
+   * PolarisCredential}. Non-OIDC identities are returned unchanged.
+   */
+  public SecurityIdentity prepare(SecurityIdentity identity) {
+    if (!(identity.getPrincipal() instanceof JsonWebToken)) {
+      return identity;
     }
-    OidcTenantConfiguration config = getOidcTenantConfig(identity);
+    OidcTenantConfiguration config = resolver.resolveConfig(identity);
+    // Add the resolved config as an attribute so mappers can access it via getOidcTenantConfig()
+    SecurityIdentity withConfig =
+        QuarkusSecurityIdentity.builder(identity)
+            .addAttribute(TENANT_CONFIG_ATTRIBUTE, config)
+            .build();
     PrincipalMapper principalMapper =
         principalMappers.select(Identifier.Literal.of(config.principalMapper().type())).get();
-    PrincipalRolesMapper principalRolesMapper =
+    PrincipalRolesMapper rolesMapper =
         principalRoleMappers
             .select(Identifier.Literal.of(config.principalRolesMapper().type()))
             .get();
-    // The mappers may do expensive work, hence we run within a blocking context
-    return context.runBlocking(
-        () -> setPolarisCredential(identity, principalMapper, principalRolesMapper));
-  }
-
-  protected SecurityIdentity setPolarisCredential(
-      SecurityIdentity identity,
-      PrincipalMapper principalMapper,
-      PrincipalRolesMapper rolesMapper) {
-    String principalName = principalMapper.mapPrincipalName(identity).orElse(null);
-    Set<String> principalRoles = rolesMapper.mapPrincipalRoles(identity);
+    String principalName = principalMapper.mapPrincipalName(withConfig).orElse(null);
+    Set<String> principalRoles = rolesMapper.mapPrincipalRoles(withConfig);
     // Note: we build the credential even if it doesn't contain enough data to authenticate;
     // DefaultAuthenticator will reject it later on.
     PolarisCredential credential;
     if (authConfig.credentialMode() == CredentialMode.INTERNAL) {
       Long principalId =
-          principalMapper.mapPrincipalId(identity).stream().boxed().findFirst().orElse(null);
+          principalMapper.mapPrincipalId(withConfig).stream().boxed().findFirst().orElse(null);
       credential = PolarisCredential.of(principalId, principalName, principalRoles);
     } else {
       credential = PolarisCredential.ofExternal(principalName, principalRoles);
     }
-    // Note: we don't change the identity roles here, this will be done later on
-    // by the AuthenticatingAugmentor, which will also validate them.
-    return QuarkusSecurityIdentity.builder(identity).addCredential(credential).build();
+    // Note: we don't change the identity roles here; this is done later by
+    // AuthenticatingAugmentor, which also validates them.
+    return QuarkusSecurityIdentity.builder(withConfig).addCredential(credential).build();
   }
 }
diff --git a/runtime/service/src/main/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalMapper.java b/runtime/service/src/main/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalMapper.java
index 8c7c58ec74..7f5266139d 100644
--- a/runtime/service/src/main/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalMapper.java
+++ b/runtime/service/src/main/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalMapper.java
@@ -18,7 +18,7 @@
  */
 package org.apache.polaris.service.auth.external.mapping;
 
-import static org.apache.polaris.service.auth.external.tenant.OidcTenantResolvingAugmentor.getOidcTenantConfig;
+import static org.apache.polaris.service.auth.external.OidcIdentityPreparer.getOidcTenantConfig;
 
 import io.quarkus.security.identity.SecurityIdentity;
 import io.smallrye.common.annotation.Identifier;
diff --git a/runtime/service/src/main/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalRolesMapper.java b/runtime/service/src/main/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalRolesMapper.java
index 9af58b7a74..d14b3253e6 100644
--- a/runtime/service/src/main/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalRolesMapper.java
+++ b/runtime/service/src/main/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalRolesMapper.java
@@ -18,7 +18,7 @@
  */
 package org.apache.polaris.service.auth.external.mapping;
 
-import static org.apache.polaris.service.auth.external.tenant.OidcTenantResolvingAugmentor.getOidcTenantConfig;
+import static org.apache.polaris.service.auth.external.OidcIdentityPreparer.getOidcTenantConfig;
 
 import io.quarkus.security.identity.SecurityIdentity;
 import io.smallrye.common.annotation.Identifier;
diff --git a/runtime/service/src/main/java/org/apache/polaris/service/auth/external/tenant/OidcTenantResolvingAugmentor.java b/runtime/service/src/main/java/org/apache/polaris/service/auth/external/tenant/OidcTenantResolvingAugmentor.java
deleted file mode 100644
index 10f1900521..0000000000
--- a/runtime/service/src/main/java/org/apache/polaris/service/auth/external/tenant/OidcTenantResolvingAugmentor.java
+++ /dev/null
@@ -1,75 +0,0 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements.  See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership.  The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance
- * with the License.  You may obtain a copy of the License at
- *
- *   http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied.  See the License for the
- * specific language governing permissions and limitations
- * under the License.
- */
-package org.apache.polaris.service.auth.external.tenant;
-
-import io.quarkus.security.identity.AuthenticationRequestContext;
-import io.quarkus.security.identity.SecurityIdentity;
-import io.quarkus.security.identity.SecurityIdentityAugmentor;
-import io.quarkus.security.runtime.QuarkusSecurityIdentity;
-import io.smallrye.mutiny.Uni;
-import jakarta.enterprise.context.ApplicationScoped;
-import jakarta.inject.Inject;
-import org.apache.polaris.service.auth.external.OidcPolarisCredentialAugmentor;
-import org.eclipse.microprofile.jwt.JsonWebToken;
-
-/**
- * A {@link SecurityIdentityAugmentor} that resolves the Polaris OIDC tenant configuration for the
- * given identity and adds it as an attribute to the {@link SecurityIdentity}.
- */
-@ApplicationScoped
-public class OidcTenantResolvingAugmentor implements SecurityIdentityAugmentor {
-
-  public static final String TENANT_CONFIG_ATTRIBUTE =
-      "org.apache.polaris.service.auth.TENANT_CONFIG";
-
-  // must run before OidcPolarisCredentialAugmentor
-  public static final int PRIORITY = OidcPolarisCredentialAugmentor.PRIORITY + 100;
-
-  public static OidcTenantConfiguration getOidcTenantConfig(SecurityIdentity identity) {
-    return identity.getAttribute(TENANT_CONFIG_ATTRIBUTE);
-  }
-
-  private final OidcTenantResolver resolver;
-
-  @Inject
-  public OidcTenantResolvingAugmentor(OidcTenantResolver resolver) {
-    this.resolver = resolver;
-  }
-
-  @Override
-  public int priority() {
-    return PRIORITY;
-  }
-
-  @Override
-  public Uni<SecurityIdentity> augment(
-      SecurityIdentity identity, AuthenticationRequestContext context) {
-    if (identity.isAnonymous() || !(identity.getPrincipal() instanceof JsonWebToken)) {
-      return Uni.createFrom().item(identity);
-    }
-    return Uni.createFrom().item(() -> setOidcTenantConfig(identity));
-  }
-
-  private SecurityIdentity setOidcTenantConfig(SecurityIdentity identity) {
-    var config = resolver.resolveConfig(identity);
-    return QuarkusSecurityIdentity.builder(identity)
-        .addAttribute(TENANT_CONFIG_ATTRIBUTE, config)
-        .build();
-  }
-}
diff --git a/runtime/service/src/test/java/org/apache/polaris/service/auth/AuthenticatingAugmentorTest.java b/runtime/service/src/test/java/org/apache/polaris/service/auth/PolarisSecurityIdentityAugmentorTest.java
similarity index 69%
rename from runtime/service/src/test/java/org/apache/polaris/service/auth/AuthenticatingAugmentorTest.java
rename to runtime/service/src/test/java/org/apache/polaris/service/auth/PolarisSecurityIdentityAugmentorTest.java
index 6b0126f3d6..1e9337681f 100644
--- a/runtime/service/src/test/java/org/apache/polaris/service/auth/AuthenticatingAugmentorTest.java
+++ b/runtime/service/src/test/java/org/apache/polaris/service/auth/PolarisSecurityIdentityAugmentorTest.java
@@ -20,6 +20,7 @@ package org.apache.polaris.service.auth;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.when;
 
@@ -32,18 +33,24 @@ import java.util.Set;
 import org.apache.polaris.core.auth.PolarisPrincipal;
 import org.apache.polaris.core.auth.PolarisPrincipalAttributes;
 import org.apache.polaris.core.collection.ImmutableAttributeMap;
+import org.apache.polaris.service.auth.external.OidcIdentityPreparer;
+import org.eclipse.microprofile.jwt.JsonWebToken;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
-public class AuthenticatingAugmentorTest {
+public class PolarisSecurityIdentityAugmentorTest {
 
-  private AuthenticatingAugmentor augmentor;
+  private PolarisSecurityIdentityAugmentor augmentor;
   private Authenticator authenticator;
+  private OidcIdentityPreparer oidcIdentityPreparer;
 
   @BeforeEach
   public void setup() {
     authenticator = mock(Authenticator.class);
-    augmentor = new AuthenticatingAugmentor(authenticator);
+    oidcIdentityPreparer = mock(OidcIdentityPreparer.class);
+    // By default, the preparer is a pass-through; individual tests override for OIDC identities
+    when(oidcIdentityPreparer.prepare(any())).thenAnswer(i -> i.getArgument(0));
+    augmentor = new PolarisSecurityIdentityAugmentor(authenticator, oidcIdentityPreparer);
   }
 
   @Test
@@ -110,4 +117,31 @@ public class AuthenticatingAugmentorTest {
     // principal attributes should not be merged
     assertThat(result.getAttributes()).containsOnlyKeys("attr1");
   }
+
+  @Test
+  public void testAugmentOidcIdentity() {
+    // Given
+    JsonWebToken oidcPrincipal = mock(JsonWebToken.class);
+    SecurityIdentity identity =
+        QuarkusSecurityIdentity.builder().setPrincipal(oidcPrincipal).build();
+    PolarisCredential credential = mock(PolarisCredential.class);
+    SecurityIdentity preparedIdentity =
+        QuarkusSecurityIdentity.builder()
+            .setPrincipal(oidcPrincipal)
+            .addCredential(credential)
+            .build();
+    PolarisPrincipal polarisPrincipal =
+        PolarisPrincipal.of("user1", ImmutableAttributeMap.builder().build(), Set.of("role1"));
+
+    when(oidcIdentityPreparer.prepare(identity)).thenReturn(preparedIdentity);
+    when(authenticator.authenticate(preparedIdentity)).thenReturn(polarisPrincipal);
+
+    // When
+    SecurityIdentity result =
+        augmentor.augment(identity, Uni.createFrom()::item).await().indefinitely();
+
+    // Then
+    assertThat(result.getPrincipal()).isSameAs(polarisPrincipal);
+    assertThat(result.getRoles()).containsExactlyInAnyOrder("role1");
+  }
 }
diff --git a/runtime/service/src/test/java/org/apache/polaris/service/auth/external/OidcPolarisCredentialAugmentorTest.java b/runtime/service/src/test/java/org/apache/polaris/service/auth/external/OidcIdentityPreparerTest.java
similarity index 51%
rename from runtime/service/src/test/java/org/apache/polaris/service/auth/external/OidcPolarisCredentialAugmentorTest.java
rename to runtime/service/src/test/java/org/apache/polaris/service/auth/external/OidcIdentityPreparerTest.java
index 2e4774a337..2078f004e9 100644
--- a/runtime/service/src/test/java/org/apache/polaris/service/auth/external/OidcPolarisCredentialAugmentorTest.java
+++ b/runtime/service/src/test/java/org/apache/polaris/service/auth/external/OidcIdentityPreparerTest.java
@@ -18,7 +18,7 @@
  */
 package org.apache.polaris.service.auth.external;
 
-import static org.apache.polaris.service.auth.external.tenant.OidcTenantResolvingAugmentor.TENANT_CONFIG_ATTRIBUTE;
+import static org.apache.polaris.service.auth.external.OidcIdentityPreparer.getOidcTenantConfig;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.when;
@@ -26,7 +26,6 @@ import static org.mockito.Mockito.when;
 import io.quarkus.security.identity.SecurityIdentity;
 import io.quarkus.security.runtime.QuarkusSecurityIdentity;
 import io.smallrye.common.annotation.Identifier;
-import io.smallrye.mutiny.Uni;
 import jakarta.enterprise.inject.Instance;
 import java.security.Principal;
 import java.util.Optional;
@@ -35,148 +34,134 @@ import java.util.Set;
 import org.apache.polaris.service.auth.AuthenticationRealmConfiguration;
 import org.apache.polaris.service.auth.CredentialMode;
 import org.apache.polaris.service.auth.PolarisCredential;
+import org.apache.polaris.service.auth.external.mapping.PrincipalMapper;
+import org.apache.polaris.service.auth.external.mapping.PrincipalRolesMapper;
 import org.apache.polaris.service.auth.external.tenant.OidcTenantConfiguration;
-import org.apache.polaris.service.auth.external.tenant.OidcTenantConfiguration.PrincipalMapper;
-import org.apache.polaris.service.auth.external.tenant.OidcTenantConfiguration.PrincipalRolesMapper;
+import org.apache.polaris.service.auth.external.tenant.OidcTenantResolver;
 import org.eclipse.microprofile.jwt.JsonWebToken;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
-class OidcPolarisCredentialAugmentorTest {
+class OidcIdentityPreparerTest {
 
-  private OidcPolarisCredentialAugmentor augmentor;
+  private OidcIdentityPreparer preparer;
+  private OidcTenantResolver resolver;
   private AuthenticationRealmConfiguration authConfig;
-  private org.apache.polaris.service.auth.external.mapping.PrincipalMapper principalMapper;
-  private org.apache.polaris.service.auth.external.mapping.PrincipalRolesMapper
-      principalRolesMapper;
+  private PrincipalMapper principalMapper;
+  private PrincipalRolesMapper principalRolesMapper;
   private OidcTenantConfiguration config;
 
   @BeforeEach
   public void setup() {
-    principalMapper = mock(org.apache.polaris.service.auth.external.mapping.PrincipalMapper.class);
-    principalRolesMapper =
-        mock(org.apache.polaris.service.auth.external.mapping.PrincipalRolesMapper.class);
+    resolver = mock(OidcTenantResolver.class);
+    authConfig = mock(AuthenticationRealmConfiguration.class);
+    principalMapper = mock(PrincipalMapper.class);
+    principalRolesMapper = mock(PrincipalRolesMapper.class);
     config = mock(OidcTenantConfiguration.class);
-    when(config.principalMapper()).thenReturn(mock(PrincipalMapper.class));
-    when(config.principalRolesMapper()).thenReturn(mock(PrincipalRolesMapper.class));
+    when(config.principalMapper()).thenReturn(mock(OidcTenantConfiguration.PrincipalMapper.class));
+    when(config.principalRolesMapper())
+        .thenReturn(mock(OidcTenantConfiguration.PrincipalRolesMapper.class));
     when(config.principalMapper().type()).thenReturn("default");
     when(config.principalRolesMapper().type()).thenReturn("default");
     @SuppressWarnings("unchecked")
-    Instance<org.apache.polaris.service.auth.external.mapping.PrincipalMapper> principalMappers =
-        mock(Instance.class);
+    Instance<PrincipalMapper> principalMappers = mock(Instance.class);
     when(principalMappers.select(Identifier.Literal.of("default"))).thenReturn(principalMappers);
     when(principalMappers.get()).thenReturn(principalMapper);
     @SuppressWarnings("unchecked")
-    Instance<org.apache.polaris.service.auth.external.mapping.PrincipalRolesMapper>
-        principalRoleMappers = mock(Instance.class);
+    Instance<PrincipalRolesMapper> principalRoleMappers = mock(Instance.class);
     when(principalRoleMappers.select(Identifier.Literal.of("default")))
         .thenReturn(principalRoleMappers);
     when(principalRoleMappers.get()).thenReturn(principalRolesMapper);
-    authConfig = mock(AuthenticationRealmConfiguration.class);
-    augmentor =
-        new OidcPolarisCredentialAugmentor(authConfig, principalMappers, principalRoleMappers);
+    preparer =
+        new OidcIdentityPreparer(authConfig, resolver, principalMappers, principalRoleMappers);
   }
 
   @Test
-  public void testAugmentAnonymousIdentity() {
-    // Given
-    SecurityIdentity anonymousIdentity =
-        QuarkusSecurityIdentity.builder().setAnonymous(true).build();
-
-    // When
-    Uni<SecurityIdentity> result = augmentor.augment(anonymousIdentity, null);
-
-    // Then
-    assertThat(result.await().indefinitely()).isSameAs(anonymousIdentity);
-  }
-
-  @Test
-  public void testAugmentNonOidcPrincipal() {
+  public void testPrepareNonOidcIdentity() {
     // Given
     Principal nonOidcPrincipal = mock(Principal.class);
     SecurityIdentity identity =
         QuarkusSecurityIdentity.builder().setPrincipal(nonOidcPrincipal).build();
 
     // When
-    Uni<SecurityIdentity> result = augmentor.augment(identity, null);
+    SecurityIdentity result = preparer.prepare(identity);
 
-    // Then
-    assertThat(result.await().indefinitely()).isSameAs(identity);
+    // Then: identity is returned unchanged
+    assertThat(result).isSameAs(identity);
   }
 
   @Test
-  public void testAugmentOidcInternalPrincipal() {
+  public void testPrepareInternalPrincipal() {
     // Given
     when(authConfig.credentialMode()).thenReturn(CredentialMode.INTERNAL);
     JsonWebToken oidcPrincipal = mock(JsonWebToken.class);
     SecurityIdentity identity =
-        QuarkusSecurityIdentity.builder()
-            .setPrincipal(oidcPrincipal)
-            .addRole("ROLE1")
-            .addAttribute(TENANT_CONFIG_ATTRIBUTE, config)
-            .build();
-    when(principalMapper.mapPrincipalId(identity)).thenReturn(OptionalLong.of(123L));
-    when(principalMapper.mapPrincipalName(identity)).thenReturn(Optional.of("root"));
-    when(principalRolesMapper.mapPrincipalRoles(identity)).thenReturn(Set.of("MAPPED_ROLE1"));
+        QuarkusSecurityIdentity.builder().setPrincipal(oidcPrincipal).addRole("ROLE1").build();
+    when(resolver.resolveConfig(identity)).thenReturn(config);
+
+    // The resolver is called with the original identity; mappers are called with the identity
+    // that has the config attribute set. Use argument matchers to capture the prepared identity.
+    when(principalMapper.mapPrincipalId(
+            org.mockito.ArgumentMatchers.argThat(id -> config.equals(getOidcTenantConfig(id)))))
+        .thenReturn(OptionalLong.of(123L));
+    when(principalMapper.mapPrincipalName(
+            org.mockito.ArgumentMatchers.argThat(id -> config.equals(getOidcTenantConfig(id)))))
+        .thenReturn(Optional.of("root"));
+    when(principalRolesMapper.mapPrincipalRoles(
+            org.mockito.ArgumentMatchers.argThat(id -> config.equals(getOidcTenantConfig(id)))))
+        .thenReturn(Set.of("MAPPED_ROLE1"));
 
     // When
-    SecurityIdentity result =
-        augmentor.augment(identity, Uni.createFrom()::item).await().indefinitely();
+    SecurityIdentity result = preparer.prepare(identity);
 
     // Then
-    assertThat(result).isNotNull();
     assertThat(result.getPrincipal()).isSameAs(oidcPrincipal);
+    assertThat(getOidcTenantConfig(result)).isSameAs(config);
     assertThat(result.getCredential(PolarisCredential.class))
         .isEqualTo(PolarisCredential.of(123L, "root", Set.of("MAPPED_ROLE1")));
-    // the identity roles should not change, since this is done by the ActiveRolesAugmentor
+    // roles are not changed here; that is done by PolarisSecurityIdentityAugmentor
     assertThat(result.getRoles()).containsExactlyInAnyOrder("ROLE1");
   }
 
   @Test
-  public void testAugmentOidcExternalPrincipal() {
+  public void testPrepareExternalPrincipal() {
     // Given
     when(authConfig.credentialMode()).thenReturn(CredentialMode.EXTERNAL);
     JsonWebToken oidcPrincipal = mock(JsonWebToken.class);
     SecurityIdentity identity =
-        QuarkusSecurityIdentity.builder()
-            .setPrincipal(oidcPrincipal)
-            .addRole("ROLE1")
-            .addAttribute(TENANT_CONFIG_ATTRIBUTE, config)
-            .build();
-    when(principalMapper.mapPrincipalName(identity)).thenReturn(Optional.of("alice"));
-    when(principalRolesMapper.mapPrincipalRoles(identity)).thenReturn(Set.of("MAPPED_ROLE1"));
+        QuarkusSecurityIdentity.builder().setPrincipal(oidcPrincipal).addRole("ROLE1").build();
+    when(resolver.resolveConfig(identity)).thenReturn(config);
+    when(principalMapper.mapPrincipalName(org.mockito.ArgumentMatchers.any()))
+        .thenReturn(Optional.of("alice"));
+    when(principalRolesMapper.mapPrincipalRoles(org.mockito.ArgumentMatchers.any()))
+        .thenReturn(Set.of("MAPPED_ROLE1"));
 
     // When
-    SecurityIdentity result =
-        augmentor.augment(identity, Uni.createFrom()::item).await().indefinitely();
+    SecurityIdentity result = preparer.prepare(identity);
 
     // Then
-    assertThat(result).isNotNull();
     assertThat(result.getPrincipal()).isSameAs(oidcPrincipal);
     assertThat(result.getCredential(PolarisCredential.class))
         .isEqualTo(PolarisCredential.ofExternal("alice", Set.of("MAPPED_ROLE1")));
-    // the identity roles should not change, since this is done by the ActiveRolesAugmentor
     assertThat(result.getRoles()).containsExactlyInAnyOrder("ROLE1");
   }
 
   @Test
-  public void testAugmentOidcExternalPrincipalWithoutName() {
+  public void testPrepareExternalPrincipalWithoutName() {
     // Given: external mode but the principal mapper cannot resolve a name
     when(authConfig.credentialMode()).thenReturn(CredentialMode.EXTERNAL);
     JsonWebToken oidcPrincipal = mock(JsonWebToken.class);
     SecurityIdentity identity =
-        QuarkusSecurityIdentity.builder()
-            .setPrincipal(oidcPrincipal)
-            .addRole("ROLE1")
-            .addAttribute(TENANT_CONFIG_ATTRIBUTE, config)
-            .build();
-    when(principalMapper.mapPrincipalName(identity)).thenReturn(Optional.empty());
-    when(principalRolesMapper.mapPrincipalRoles(identity)).thenReturn(Set.of("MAPPED_ROLE1"));
-
-    // When: the augmentor builds a credential with a null name (no NPE from the builder); it is
-    // DefaultAuthenticator that later rejects the missing name.
-    SecurityIdentity result =
-        augmentor.augment(identity, Uni.createFrom()::item).await().indefinitely();
+        QuarkusSecurityIdentity.builder().setPrincipal(oidcPrincipal).build();
+    when(resolver.resolveConfig(identity)).thenReturn(config);
+    when(principalMapper.mapPrincipalName(org.mockito.ArgumentMatchers.any()))
+        .thenReturn(Optional.empty());
+    when(principalRolesMapper.mapPrincipalRoles(org.mockito.ArgumentMatchers.any()))
+        .thenReturn(Set.of("MAPPED_ROLE1"));
+
+    // When: the preparer builds a credential with a null name; DefaultAuthenticator rejects it
+    // later
+    SecurityIdentity result = preparer.prepare(identity);
 
     // Then
     assertThat(result.getCredential(PolarisCredential.class))
diff --git a/runtime/service/src/test/java/org/apache/polaris/service/auth/external/OidcTenantResolvingAugmentorTest.java b/runtime/service/src/test/java/org/apache/polaris/service/auth/external/OidcTenantResolvingAugmentorTest.java
deleted file mode 100644
index 1668cc520c..0000000000
--- a/runtime/service/src/test/java/org/apache/polaris/service/auth/external/OidcTenantResolvingAugmentorTest.java
+++ /dev/null
@@ -1,98 +0,0 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements.  See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership.  The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance
- * with the License.  You may obtain a copy of the License at
- *
- *   http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied.  See the License for the
- * specific language governing permissions and limitations
- * under the License.
- */
-package org.apache.polaris.service.auth.external;
-
-import static org.apache.polaris.service.auth.external.tenant.OidcTenantResolvingAugmentor.getOidcTenantConfig;
-import static org.assertj.core.api.Assertions.assertThat;
-import static org.mockito.Mockito.mock;
-import static org.mockito.Mockito.when;
-
-import io.quarkus.security.identity.SecurityIdentity;
-import io.quarkus.security.runtime.QuarkusSecurityIdentity;
-import io.smallrye.mutiny.Uni;
-import java.security.Principal;
-import org.apache.polaris.service.auth.external.tenant.OidcTenantConfiguration;
-import org.apache.polaris.service.auth.external.tenant.OidcTenantResolver;
-import org.apache.polaris.service.auth.external.tenant.OidcTenantResolvingAugmentor;
-import org.eclipse.microprofile.jwt.JsonWebToken;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-
-class OidcTenantResolvingAugmentorTest {
-
-  private OidcTenantResolvingAugmentor augmentor;
-  private OidcTenantResolver resolver;
-
-  @BeforeEach
-  public void setup() {
-    resolver = mock(OidcTenantResolver.class);
-    augmentor = new OidcTenantResolvingAugmentor(resolver);
-  }
-
-  @Test
-  public void testAugmentAnonymousIdentity() {
-    // Given
-    SecurityIdentity anonymousIdentity =
-        QuarkusSecurityIdentity.builder().setAnonymous(true).build();
-
-    // When
-    Uni<SecurityIdentity> result = augmentor.augment(anonymousIdentity, null);
-
-    // Then
-    assertThat(result.await().indefinitely()).isSameAs(anonymousIdentity);
-  }
-
-  @Test
-  public void testAugmentNonOidcPrincipal() {
-    // Given
-    Principal nonOidcPrincipal = mock(Principal.class);
-    SecurityIdentity identity =
-        QuarkusSecurityIdentity.builder().setPrincipal(nonOidcPrincipal).build();
-
-    // When
-    Uni<SecurityIdentity> result = augmentor.augment(identity, null);
-
-    // Then
-    assertThat(result.await().indefinitely()).isSameAs(identity);
-  }
-
-  @Test
-  public void testAugmentOidcPrincipal() {
-    // Given
-    JsonWebToken oidcPrincipal = mock(JsonWebToken.class);
-    SecurityIdentity identity =
-        QuarkusSecurityIdentity.builder()
-            .setPrincipal(oidcPrincipal)
-            .addRole("PRINCIPAL_ROLE:ALL")
-            .build();
-
-    OidcTenantConfiguration config = mock(OidcTenantConfiguration.class);
-    when(resolver.resolveConfig(identity)).thenReturn(config);
-
-    // When
-    SecurityIdentity result =
-        augmentor.augment(identity, Uni.createFrom()::item).await().indefinitely();
-
-    // Then
-    assertThat(result).isNotNull();
-    assertThat(result.getPrincipal()).isSameAs(oidcPrincipal);
-    assertThat(result.getRoles()).containsExactlyInAnyOrder("PRINCIPAL_ROLE:ALL");
-    assertThat(getOidcTenantConfig(result)).isSameAs(config);
-  }
-}
diff --git a/runtime/service/src/test/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalMapperTest.java b/runtime/service/src/test/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalMapperTest.java
index 537f2d9488..6224f1c7cf 100644
--- a/runtime/service/src/test/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalMapperTest.java
+++ b/runtime/service/src/test/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalMapperTest.java
@@ -18,7 +18,7 @@
  */
 package org.apache.polaris.service.auth.external.mapping;
 
-import static org.apache.polaris.service.auth.external.tenant.OidcTenantResolvingAugmentor.TENANT_CONFIG_ATTRIBUTE;
+import static org.apache.polaris.service.auth.external.OidcIdentityPreparer.TENANT_CONFIG_ATTRIBUTE;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
diff --git a/runtime/service/src/test/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalRolesMapperTest.java b/runtime/service/src/test/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalRolesMapperTest.java
index c016ed8eee..c368318063 100644
--- a/runtime/service/src/test/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalRolesMapperTest.java
+++ b/runtime/service/src/test/java/org/apache/polaris/service/auth/external/mapping/DefaultPrincipalRolesMapperTest.java
@@ -18,7 +18,7 @@
  */
 package org.apache.polaris.service.auth.external.mapping;
 
-import static org.apache.polaris.service.auth.external.tenant.OidcTenantResolvingAugmentor.TENANT_CONFIG_ATTRIBUTE;
+import static org.apache.polaris.service.auth.external.OidcIdentityPreparer.TENANT_CONFIG_ATTRIBUTE;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.mock;
diff --git a/site/content/in-dev/unreleased/managing-security/external-idp/idp-dev-notes.md b/site/content/in-dev/unreleased/managing-security/external-idp/idp-dev-notes.md
index 3539dec564..f56ca46cd3 100644
--- a/site/content/in-dev/unreleased/managing-security/external-idp/idp-dev-notes.md
+++ b/site/content/in-dev/unreleased/managing-security/external-idp/idp-dev-notes.md
@@ -51,14 +51,13 @@ See [Token Broker description]({{< relref "../external-idp#token-broker" >}}) fo
 1. [`InternalAuthenticationMechanism`](https://github.com/apache/polaris/blob/main/runtime/service/src/main/java/org/apache/polaris/service/auth/internal/InternalAuthenticationMechanism.java) parses the auth header.
 2. Uses [`TokenBroker`](https://github.com/apache/polaris/blob/main/runtime/service/src/main/java/org/apache/polaris/service/auth/TokenBroker.java) to decode the token.
 3. Builds [`InternalAuthenticationRequest`](https://github.com/apache/polaris/blob/main/runtime/service/src/main/java/org/apache/polaris/service/auth/internal/InternalAuthenticationRequest.java) and generates `SecurityIdentity` (Quarkus).
-4. `Authenticator.authenticate()` validates the credential, resolves the principal and principal roles, then creates the `PolarisPrincipal`.
+4. [`PolarisSecurityIdentityAugmentor`](https://github.com/apache/polaris/blob/main/runtime/service/src/main/java/org/apache/polaris/service/auth/PolarisSecurityIdentityAugmentor.java) invokes `Authenticator.authenticate()`, which validates the credential, resolves the principal and principal roles, then creates the `PolarisPrincipal`.
 
 ### External Authentication
 
 1. `OidcAuthenticationMechanism` (Quarkus) processes the auth header.
-2. [`OidcTenantResolvingAugmentor`](https://github.com/apache/polaris/blob/main/runtime/service/src/main/java/org/apache/polaris/service/auth/external/tenant/OidcTenantResolvingAugmentor.java) selects the OIDC tenant.
-3. [`OidcPolarisCredentialAugmentor`](https://github.com/apache/polaris/blob/main/runtime/service/src/main/java/org/apache/polaris/service/auth/external/OidcPolarisCredentialAugmentor.java) extracts JWT claims.
-4. `Authenticator.authenticate()` validates the claims, resolves the principal and principal roles, then creates the `PolarisPrincipal`.
+2. [`PolarisSecurityIdentityAugmentor`](https://github.com/apache/polaris/blob/main/runtime/service/src/main/java/org/apache/polaris/service/auth/PolarisSecurityIdentityAugmentor.java) delegates to [`OidcIdentityPreparer`](https://github.com/apache/polaris/blob/main/runtime/service/src/main/java/org/apache/polaris/service/auth/external/OidcIdentityPreparer.java), which resolves the OIDC tenant and extracts JWT claims into a `PolarisCredential`.
+3. `PolarisSecurityIdentityAugmentor` then invokes `Authenticator.authenticate()`, which validates the claims, resolves the principal and principal roles, then creates the `PolarisPrincipal`.
 
 When [external principals]({{< relref "../external-idp#external-principals" >}}) are enabled for
 the realm, step 4 differs: `DefaultAuthenticator` builds the `PolarisPrincipal` directly from the