[DO NOT MERGE] Core, REST, OAuth2: AuthManager v2 (MVP)

**Do not review this PR unless you are curious to get an early preview of Auth Manager v2 :-)**

This PR encompasses the full scope of the AuthManager v2 effort, except support for human-to-machine grants (Authorization Code and Device Code), which will be introduced in a subsequent update. Cf. Auth Manager v2 [design document].

The goal is to provide complete overview of the planned changes for the curious reader. This PR is not meant to be merged as-is: smaller, incremental PRs will be opened later to introduce these changes gradually.

**Key features of the new implementation:**

- **Standards-compliant OAuth2/OIDC support** with proper client authentication methods (`client_secret_basic`, `client_secret_post`, `none`)
- **OpenID Connect Discovery** for automatic endpoint resolution via `issuer-url`
- **Token Exchange** support (RFC 8693) and **Refresh Token** flows
- **Custom token endpoint parameters** (e.g. Auth0 `audience` via `rest.auth.oauth2.extra-params.*`)
- **Automatic background token refresh**
- **Automatic migration** of legacy property names with deprecation warnings at runtime

**Architecture:**

- `oauth2/` — Core classes: `OAuth2Manager`, `OAuth2Session`, `OAuth2Runtime`, `OAuth2Config`
- `oauth2/config/` — Configuration model: `BasicConfig`, `TokenExchangeConfig`, `TokenRefreshConfig`, `ConfigMigrator`, `ConfigValidator`
- `oauth2/flow/` — OAuth2 grant flows: `ClientCredentialsFlow`, `RefreshTokenFlow`, `TokenExchangeFlow`, `EndpointProvider`
- `oauth2/client/` — Low-level `OAuth2Client` for HTTP token requests
- `oauth2/http/` — `RESTClientAdapter` bridging Iceberg's `RESTClient` to the OAuth2 client

**Deprecations:**

- `org.apache.iceberg.rest.auth.OAuth2Manager` — deprecated, removal planned for 1.14.0
- `org.apache.iceberg.rest.auth.OAuth2Properties` — deprecated in favor of `OAuth2Config`
- `org.apache.iceberg.rest.auth.OAuth2Util` — deprecated in favor of the new `OAuth2Manager`

Other deprecations affect the REST layer (error handlers, etc.).

**Docs:**

Adds an OAuth2 configuration reference page (auto-generated from code) and a migration guide.

**Tests:**

~11,000 lines of new tests including unit tests for all components with MockServer, and Keycloak-based integration tests.

[design document]:https://docs.google.com/document/d/1Hxw-t8Maa7wZFmrlSujm7LRawKsFP3Q31tET_3aRnQU/edit

Author: adutra

.github/workflows/java-ci.yml

@@ -109,7 +109,7 @@ jobs:
       with:
         distribution: zulu
         java-version: ${{ matrix.jvm }}
-    - run: ./gradlew -DallModules build -x test -x javadoc -x integrationTest
+    - run: ./gradlew -DallModules build -x test -x javadoc -x integrationTest -x intTest
 
   build-javadoc:
     runs-on: ubuntu-24.04

build.gradle

@@ -357,9 +357,43 @@ project(':iceberg-common') {
 }
 
 project(':iceberg-core') {
+  apply plugin: 'java-test-fixtures'
+  apply plugin: 'jvm-test-suite'
+
   test {
     useJUnitPlatform()
   }
+
+  testing {
+    suites {
+      intTest(JvmTestSuite) {
+        useJUnitJupiter()
+        dependencies {
+          implementation project()
+          implementation testFixtures(project())
+        }
+        check.dependsOn intTest
+        targets {
+          all {
+            testTask.configure {
+              shouldRunAfter(test)
+              mustRunAfter(test)
+            }
+          }
+        }
+      }
+    }
+  }
+
+  configurations {
+    docs {
+      description = 'Dependencies for generating configuration documentation'
+      canBeResolved = true
+      canBeConsumed = false
+      visible = false
+    }
+  }
+
   dependencies {
     api project(':iceberg-api')
     implementation project(':iceberg-common')
@@ -384,11 +418,16 @@ project(':iceberg-core') {
       exclude group: 'org.slf4j', module: 'slf4j-log4j12'
     }
 
+    // OAuth2
+    implementation libs.nimbus.oauth2.oidc.sdk
+    implementation libs.nimbus.jose.jwt
+
     testImplementation libs.jetty.servlet
     testImplementation libs.jakarta.servlet
     testImplementation libs.jetty.server
     testImplementation libs.mockserver.netty
     testImplementation libs.mockserver.client.java
+    testImplementation libs.bouncycastle.bcpkix
     testImplementation libs.sqlite.jdbc
     testImplementation libs.derby.core
     testImplementation libs.derby.tools
@@ -398,7 +437,108 @@ project(':iceberg-core') {
       exclude group: 'junit'
     }
     testImplementation libs.awaitility
+
+    testFixturesApi libs.junit.jupiter
+    testFixturesApi libs.junit.pioneer
+    testFixturesApi libs.assertj.core
+    testFixturesApi libs.mockito.core
+
+    testFixturesApi libs.httpcomponents.httpclient5
+    testFixturesApi libs.nimbus.oauth2.oidc.sdk
+    testFixturesApi libs.nimbus.jose.jwt
+
+    testFixturesApi libs.mockserver.netty
+    testFixturesApi libs.mockserver.client.java
+
+    testFixturesApi libs.testcontainers
+    testFixturesApi libs.testcontainers.junit.jupiter
+    testFixturesApi libs.testcontainers.keycloak
+
+    testFixturesApi libs.keycloak.admin.client
+
+    testFixturesImplementation project(path: ':iceberg-bundled-guava', configuration: 'shadow')
+
+    testFixturesAnnotationProcessor libs.immutables.value
+    testFixturesCompileOnly libs.immutables.value
+
+    intTestImplementation project(path: ':iceberg-api', configuration: 'testArtifacts') // for CatalogTests
+    intTestImplementation project(path: ':iceberg-core', configuration: 'testArtifacts') // for CatalogTests
+    intTestImplementation project(path: ':iceberg-bundled-guava', configuration: 'shadow')
+
+    intTestImplementation libs.jetty.servlet
+    intTestImplementation libs.jakarta.servlet
+    intTestImplementation libs.jetty.server
+
+    docs 'com.thoughtworks.qdox:qdox:2.2.0'
+    docs project(path: ':iceberg-bundled-guava', configuration: 'shadow')
   }
+
+  sourceSets {
+    docs {
+      java {
+        srcDir 'src/docs/java'
+      }
+      resources {
+        srcDir 'src/docs/resources'
+      }
+      compileClasspath += configurations.docs
+      runtimeClasspath += configurations.docs
+    }
+  }
+
+  tasks.named('processDocsResources', ProcessResources).configure {
+    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+  }
+
+  tasks.register('generateOAuth2Docs', JavaExec) {
+    group = 'documentation'
+    description = 'Generates REST OAuth2 configuration documentation from OAuth2Config'
+    mainClass.set('org.apache.iceberg.rest.auth.oauth2.docs.OAuth2DocumentationGenerator')
+    classpath = sourceSets.docs.runtimeClasspath
+
+    def inputFile = project.file('src/main/java/org/apache/iceberg/rest/auth/oauth2/OAuth2Config.java')
+    def outputFile = rootProject.file('docs/docs/oauth2-configuration.md')
+
+    inputs.files(inputFile)
+    outputs.file(outputFile)
+
+    args(inputFile.absolutePath, outputFile.absolutePath)
+
+    doFirst { outputFile.parentFile.mkdirs() }
+  }
+
+  assemble.dependsOn('generateOAuth2Docs')
+
+  tasks.register('checkOAuth2Docs', JavaExec) {
+    group = 'verification'
+    description = 'Checks that the OAuth2 configuration documentation is up to date'
+    mainClass.set('org.apache.iceberg.rest.auth.oauth2.docs.OAuth2DocumentationGenerator')
+    classpath = sourceSets.docs.runtimeClasspath
+    mustRunAfter('generateOAuth2Docs')
+
+    def inputFile = project.file('src/main/java/org/apache/iceberg/rest/auth/oauth2/OAuth2Config.java')
+    def committedFile = rootProject.file('docs/docs/oauth2-configuration.md')
+    def tempFile = project.layout.buildDirectory.file('generated-docs/oauth2-configuration.md')
+
+    inputs.files(inputFile, committedFile)
+    outputs.file(tempFile)
+
+    args(inputFile.absolutePath, tempFile.get().asFile.absolutePath)
+
+    doFirst { tempFile.get().asFile.parentFile.mkdirs() }
+
+    doLast {
+      def expected = tempFile.get().asFile.text
+      def actual = committedFile.text
+      if (expected != actual) {
+        throw new GradleException(
+          "OAuth2 configuration documentation is out of date. " +
+          "Please run './gradlew :iceberg-core:generateOAuth2Docs' to update it.")
+      }
+    }
+  }
+
+  check.dependsOn('checkOAuth2Docs')
 }
 
 project(':iceberg-data') {