docs(auth): clarify exchange-only polaris-cv wording

Author: vigneshio

CHANGELOG.md

@@ -71,7 +71,7 @@ request adding CHANGELOG notes for breaking (!) changes and possibly other secti
   and a subsequent `bootstrap` would create a second, empty set of tables in the other schema.
   Either remove the setting from the URL, or point it at the schema that already holds your
   Polaris tables.
-- Internal JWTs minted before credentials-generation binding (tokens without the `polaris-cv` claim) can no longer be used as subject tokens in token exchange; they remain valid as bearer tokens until expiry. Clients that keep exchanging long-lived tokens (including during a rolling upgrade, where a not-yet-restarted node may still mint claim-less tokens) will see the exchange rejected with `invalid_grant` once all servers run the new version.
+- Internal JWTs minted before credentials-generation binding (tokens without the `polaris-cv` claim) can no longer be used as subject tokens in token exchange; they remain valid as bearer tokens until expiry. During a rolling upgrade, an old node may still mint claim-less tokens: exchanging such a token on any already-upgraded node fails with `invalid_grant`, so clients can see intermittent exchange failures until the last old node is gone; after that, rejection is consistent.
 
 ### New Features
 

polaris-core/src/main/java/org/apache/polaris/core/entity/PolarisPrincipalSecrets.java

@@ -181,8 +181,10 @@ public boolean matchesSecret(String potentialSecret) {
    * Credentials-generation fingerprint corresponding to the secret that matches {@code
    * potentialSecret}: the main generation when it matches the main secret hash, the secondary
    * generation when it matches the secondary secret hash, or empty when it matches neither. Newly
-   * minted tokens carry this fingerprint in the {@code polaris-cv} claim; credential-generation is
-   * enforced on token exchange, while bearer verify checks only the JWT signature and claims.
+   * minted tokens carry this fingerprint in the {@code polaris-cv} claim. That claim gates
+   * <em>token-exchange</em> eligibility against the current (and secondary) generation; bearer
+   * verify checks only the JWT signature and claims, so a token remains usable as a bearer until
+   * JWT expiry even after its generation is no longer current.
    *
    * <p>Comparisons are constant-time, as in {@link #matchesCredentialsVersion(String)}.
    */

runtime/service/src/main/java/org/apache/polaris/service/auth/internal/broker/JWTBroker.java

@@ -54,11 +54,11 @@ public class JWTBroker implements TokenBroker {
   private static final String CLAIM_KEY_SCOPE = "scope";
 
   /**
-   * Credentials-generation fingerprint bound to the principal's current credentials version (see
-   * {@link PolarisPrincipalSecrets#getCredentialsVersion()}). When secrets are rotated or reset,
-   * the version changes and tokens carrying a prior value are rejected on token exchange. Bearer
-   * verify checks only the JWT signature and claims. The claim name is collision-resistant per RFC
-   * 7519.
+   * Credentials-generation fingerprint carried on newly minted tokens (see {@link
+   * PolarisPrincipalSecrets#getCredentialsVersion()}). When secrets are rotated or reset, the
+   * version changes and tokens carrying a prior value are rejected on <em>token exchange</em> only.
+   * Bearer verify checks only the JWT signature and claims, so those tokens remain usable as
+   * bearers until JWT expiry. The claim name is collision-resistant per RFC 7519.
    */
   @VisibleForTesting static final String CLAIM_KEY_CREDENTIALS_VERSION = "polaris-cv";
 
@@ -195,8 +195,8 @@ public TokenResponse generateFromToken(
       }
       tokenScope = scope;
     }
-    // Keep the subject token's credentials generation so the re-minted token does not outlive the
-    // generation it was exchanged against.
+    // Preserve the subject token's credentials generation on the re-minted token so later exchanges
+    // keep checking the same generation fingerprint.
     String tokenString =
         generateTokenString(
             decodedToken.getPrincipalName(),

runtime/service/src/test/java/org/apache/polaris/service/ratelimiter/RateLimiterFilterTest.java

@@ -30,17 +30,14 @@
 import jakarta.inject.Inject;
 import jakarta.ws.rs.client.Client;
 import jakarta.ws.rs.client.ClientBuilder;
-import jakarta.ws.rs.client.Entity;
 import jakarta.ws.rs.core.MediaType;
-import jakarta.ws.rs.core.MultivaluedHashMap;
 import jakarta.ws.rs.core.Response;
 import jakarta.ws.rs.core.Response.Status;
 import java.util.Map;
 import java.util.Set;
 import java.util.function.Consumer;
 import org.apache.iceberg.rest.responses.ErrorResponse;
 import org.apache.iceberg.rest.responses.ErrorResponseParser;
-import org.apache.iceberg.rest.responses.OAuthTokenResponse;
 import org.apache.polaris.service.events.EventAttributes;
 import org.apache.polaris.service.events.PolarisEvent;
 import org.apache.polaris.service.events.PolarisEventType;
@@ -83,11 +80,6 @@ public Map<String, String> getConfigOverrides() {
           .put("polaris.rate-limiter.token-bucket.type", "default")
           .put("polaris.metrics.tags.environment", "prod")
           .put("polaris.realm-context.realms", "POLARIS,POLARIS2")
-          // Bootstrapping both realms with known credentials so each realm can mint its own
-          // access token. Tokens are bound to per-realm secret hashes and cannot be shared.
-          .put(
-              "polaris.bootstrap.credentials",
-              "POLARIS,test-admin,test-secret;POLARIS2,test-admin2,test-secret2")
           .put("polaris.metrics.realm-id-tag.enable-in-api-metrics", "true")
           .put("polaris.metrics.realm-id-tag.enable-in-http-metrics", "true")
           .put("polaris.authentication.token-broker.type", "symmetric-key")
@@ -146,14 +138,10 @@ public void testRateLimiter() {
       requestAsserter.accept(Status.TOO_MANY_REQUESTS);
     }
 
-    // Ensure that a different realm identifier gets a separate limit. Access tokens are
-    // bound to per-realm principal secrets, so mint a token for POLARIS2 rather than reusing
-    // the POLARIS admin token (which would correctly return 401 after credentials binding).
+    // Ensure that a different realm identifier gets a separate limit
     MockRateLimiter.allowProceed = true;
-    String polaris2Token =
-        obtainAccessTokenForRealm(polarisEndpoints, "POLARIS2", "test-admin2", "test-secret2");
     Consumer<Status> requestAsserter2 =
-        constructRequestAsserter(polarisEndpoints, polaris2Token, "POLARIS2");
+        constructRequestAsserter(polarisEndpoints, adminToken, "POLARIS2");
     requestAsserter2.accept(Status.OK);
   }
 
@@ -255,27 +243,4 @@ private static Consumer<Status> constructRequestAsserter(
       }
     };
   }
-
-  /**
-   * Mints an access token in the given realm using client credentials. Realm must be bootstrapped
-   * with those credentials (see {@link Profile}).
-   */
-  private static String obtainAccessTokenForRealm(
-      PolarisApiEndpoints endpoints, String realm, String clientId, String clientSecret) {
-    MultivaluedHashMap<String, String> form = new MultivaluedHashMap<>();
-    form.add("grant_type", "client_credentials");
-    form.add("client_id", clientId);
-    form.add("client_secret", clientSecret);
-    form.add("scope", "PRINCIPAL_ROLE:ALL");
-    try (Client httpClient = ClientBuilder.newBuilder().build();
-        Response response =
-            httpClient
-                .target(String.format("%s/v1/oauth/tokens", endpoints.catalogApiEndpoint()))
-                .request(MediaType.APPLICATION_JSON_TYPE)
-                .header("Polaris-Realm", realm)
-                .post(Entity.form(form))) {
-      assertThat(response.getStatus()).isEqualTo(Status.OK.getStatusCode());
-      return response.readEntity(OAuthTokenResponse.class).token();
-    }
-  }
 }