feat(jwt-bearer): Add support for JWT Bearer grants

Fixes #208.

This change introduces support for JWT Bearer grants (RFC 7523).

The Auth Manager already has support fur JWT client auth, also introduced by RFC 7523.

In order to clarify the configuration, the client auth part of RFC 7523 has been relocated from `rest.auth.oauth2.client-assertion.jwt.*` to `rest.auth.oauth2.client-auth.jwt.*`.

Author: adutra

docs/README.md

@@ -52,12 +52,34 @@ The Dremio AuthManager for Apache Iceberg supports several client authentication
 [Client Authentication](./client-authentication.md) section for more details on how to configure
 client authentication.
 
-## Impersonation & Delegation
+## Grant Types
+
+The Dremio AuthManager for Apache Iceberg supports several OAuth2 grant types:
+
+* Client Credentials Grant ([RFC 6749, Section 4.4](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4))
+* Authorization Code Grant ([RFC 6749, Section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1))
+* Device Authorization Grant ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628))
+* [Token Exchange Grant](./token-exchange.md) ([RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693))
+* [JWT Bearer Grant](./jwt-bearer.md) ([RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523))
+
+The Dremio AuthManager also supports the Resource Owner Password Credentials Grant 
+([RFC 6749, Section 4.3](https://datatracker.ietf.org/doc/html/rfc6749#section-4.3)), but this grant 
+type is deprecated and should be avoided if possible.
+
+See the [Configuration](./configuration.md) section for more details on how to configure grant 
+types.
+
+### Impersonation & Delegation
 
 The Dremio AuthManager for Apache Iceberg supports impersonation and delegation using the token
 exchange grant type. See the [Token Exchange](./token-exchange.md) section for more details on how
 to configure impersonation and delegation.
 
+### Assertion Grants
+
+The Dremio AuthManager for Apache Iceberg supports JWT assertion grants with static or dynamic
+assertions. See the [JWT Bearer Grant](./jwt-bearer.md) section for more details.
+
 ## Migration From Iceberg's Built-In OAuth2 `AuthManager`
 
 Migrating from Iceberg's built-in OAuth2 `AuthManager` to the Dremio AuthManager for Apache Iceberg

docs/client-authentication.md

@@ -89,7 +89,7 @@ Example configuration:
 rest.auth.oauth2.client-auth=client_secret_jwt
 rest.auth.oauth2.client-id=my-client
 rest.auth.oauth2.client-secret=my-secret
-rest.auth.oauth2.client-assertion.jwt.algorithm=HMAC_SHA256
+rest.auth.oauth2.client-auth.jwt.algorithm=HMAC_SHA256
 ```
 
 #### `private_key_jwt`
@@ -101,11 +101,11 @@ Example configuration:
 ```properties
 rest.auth.oauth2.client-auth=private_key_jwt
 rest.auth.oauth2.client-id=my-client
-rest.auth.oauth2.client-assertion.jwt.algorithm=RSA_SHA256
-rest.auth.oauth2.client-assertion.jwt.private-key=/path/to/private_key.pem
+rest.auth.oauth2.client-auth.jwt.algorithm=RSA_SHA256
+rest.auth.oauth2.client-auth.jwt.private-key=/path/to/private_key.pem
 ```
 
-When using this method, the private key file must be provided using the `rest.auth.oauth2.client-assertion.jwt.private-key` property. 
+When using this method, the private key file must be provided using the `rest.auth.oauth2.client-auth.jwt.private-key` property. 
 
 The file must be in PEM format. It may contain multiple objects; the first private key encountered
 in the file is used.
@@ -134,16 +134,16 @@ The JWT assertion includes the following claims:
 Each of these claims (except `iat`) can be customized using the following configuration properties:
 
 ```properties
-rest.auth.oauth2.client-assertion.jwt.issuer=my-issuer
-rest.auth.oauth2.client-assertion.jwt.subject=my-subject
-rest.auth.oauth2.client-assertion.jwt.audience=https://example.com/token
-rest.auth.oauth2.client-assertion.jwt.token-lifespan=PT10M
+rest.auth.oauth2.client-auth.jwt.issuer=my-issuer
+rest.auth.oauth2.client-auth.jwt.subject=my-subject
+rest.auth.oauth2.client-auth.jwt.audience=https://example.com/token
+rest.auth.oauth2.client-auth.jwt.token-lifespan=PT10M
 ```
 
-The signing algorithm can be specified using the `rest.auth.oauth2.client-assertion.jwt.algorithm` property. The default is `HMAC_SHA512` for `client_secret_jwt` and `RSA_SHA512` for `private_key_jwt` (algorithm names are case-insensitive). Example:
+The signing algorithm can be specified using the `rest.auth.oauth2.client-auth.jwt.algorithm` property. The default is `HMAC_SHA512` for `client_secret_jwt` and `RSA_SHA512` for `private_key_jwt` (algorithm names are case-insensitive). Example:
 
 ```properties
-rest.auth.oauth2.client-assertion.jwt.algorithm=HMAC_SHA384
+rest.auth.oauth2.client-auth.jwt.algorithm=HMAC_SHA384
 ```
 
 Supported algorithms are:
@@ -165,8 +165,8 @@ For `private_key_jwt`:
 | `RSA_SHA512` | `RS512`, `SHA512withRSA`   |
 
 
-And finally, extra claims can be added to the JWT assertion using the `rest.auth.oauth2.client-assertion.jwt.extra-claims.*` prefix property. Example:
+And finally, extra claims can be added to the JWT assertion using the `rest.auth.oauth2.client-auth.jwt.extra-claims.*` prefix property. Example:
 
 ```properties
-rest.auth.oauth2.client-assertion.jwt.extra-claims.my-claim=my-value
+rest.auth.oauth2.client-auth.jwt.extra-claims.my-claim=my-value
 ```

docs/configuration.md

@@ -103,6 +103,7 @@ The grant type to use when authenticating against the OAuth2 server. Valid value
 - `authorization_code`
 - `urn:ietf:params:oauth:grant-type:device_code`
 - `urn:ietf:params:oauth:grant-type:token-exchange`
+- `urn:ietf:params:oauth:grant-type:jwt-bearer`
 
 Optional, defaults to `client_credentials`.
 
@@ -393,43 +394,65 @@ The logical name of the target service(s) where the client intends to use the re
 
 Optional. Can be a single value or a comma-separated list of values.
 
-## Client Assertion Settings
+## Jwt Bearer Settings
+
+Configuration properties for the JWT bearer grant as specified in [RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523).
+
+The assertion can be supplied statically or fetched dynamically using a nested OAuth2 configuration.
+
+### `rest.auth.oauth2.jwt-bearer.assertion`
+
+The assertion to exchange.
+
+If this value is present, the assertion is used as-is. If this value is not present, the assertion may be read from the file specified by `rest.auth.oauth2.jwt-bearer.assertion-file`, or dynamically fetched using the configuration provided under the `rest.auth.oauth2.jwt-bearer.assertion` prefix.
+
+### `rest.auth.oauth2.jwt-bearer.assertion-file`
+
+Path to a file containing the assertion. The file content is read and trimmed to obtain the assertion value. Ignored if `rest.auth.oauth2.jwt-bearer.assertion` is set.
+
+### `rest.auth.oauth2.jwt-bearer.assertion.*`
+
+The configuration to use for fetching the assertion dynamically.
+
+This is a prefix property; any property that can be set under the `rest.auth.oauth2.` prefix can also be set under this prefix.
+
+## Jwt Client Auth Settings
 
 Configuration properties for JWT client assertion as specified in [JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://datatracker.ietf.org/doc/html/rfc7523).
 
 These properties allow the client to authenticate using the `client_secret_jwt` or `private_key_jwt` authentication methods.
 
-### `rest.auth.oauth2.client-assertion.jwt.issuer`
+### `rest.auth.oauth2.client-auth.jwt.issuer`
 
 The issuer of the client assertion JWT. Optional. The default is the client ID.
 
-### `rest.auth.oauth2.client-assertion.jwt.subject`
+### `rest.auth.oauth2.client-auth.jwt.subject`
 
 The subject of the client assertion JWT. Optional. The default is the client ID.
 
-### `rest.auth.oauth2.client-assertion.jwt.audience`
+### `rest.auth.oauth2.client-auth.jwt.audience`
 
 The audience of the client assertion JWT. Optional. The default is the token endpoint. Can be a single audience or a comma-separated list of audiences.
 
-### `rest.auth.oauth2.client-assertion.jwt.token-lifespan`
+### `rest.auth.oauth2.client-auth.jwt.token-lifespan`
 
 The expiration time of the client assertion JWT. Optional. The default is 5 minutes.
 
-### `rest.auth.oauth2.client-assertion.jwt.algorithm`
+### `rest.auth.oauth2.client-auth.jwt.algorithm`
 
 The signing algorithm to use for the client assertion JWT. Optional. The default is `HS512` if the authentication method is `client_secret_jwt`, or `RS512` if the authentication method is `private_key_jwt`.
 
 Algorithm names must match the "alg" Param Value as described in [RFC 7518 Section 3.1](https://datatracker.ietf.org/doc/html/rfc7518#section-3.1).
 
-### `rest.auth.oauth2.client-assertion.jwt.key-id`
+### `rest.auth.oauth2.client-auth.jwt.key-id`
 
 The key ID (kid) to include in the JWT header. Optional.
 
 If specified, this will be included in the "kid" header parameter of the JWT assertion. This is useful when the authorization server needs to identify which key to use for verification from a set of keys.
 
 This setting is only supported when using the `private_key_jwt` authentication method. It is ignored when using `client_secret_jwt`.
 
-### `rest.auth.oauth2.client-assertion.jwt.private-key`
+### `rest.auth.oauth2.client-auth.jwt.private-key`
 
 The path on the local filesystem to the private key to use for signing the client assertion JWT. Required if the authentication method is `private_key_jwt`.
 
@@ -443,7 +466,7 @@ Supported key formats are:
 
 Only unencrypted keys are supported currently.
 
-### `rest.auth.oauth2.client-assertion.jwt.extra-claims.*`
+### `rest.auth.oauth2.client-auth.jwt.extra-claims.*`
 
 Extra claims to include in the client assertion JWT. This is a prefix property, and multiple values can be set, each with a different key and value.
 

docs/jwt-bearer.md

@@ -0,0 +1,87 @@
+<!--
+Copyright (C) 2025 Dremio Corporation
+
+Licensed 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.
+-->
+# Dremio AuthManager for Apache Iceberg - JWT Bearer Grant
+
+## Overview
+
+The Dremio AuthManager for Apache Iceberg supports the
+[JWT Bearer Grant](https://datatracker.ietf.org/doc/html/rfc7523).
+
+Assertions can be provided in two methods:
+
+* Static assertions: assertions acquired externally and directly included in the configuration.
+* Dynamic assertions: assertions are fetched dynamically by the AuthManager, using the same or
+  different credentials and possibly a different IDP.
+
+### Using Static Assertions
+
+Static assertions are provided using the following properties:
+
+* `rest.auth.oauth2.jwt-bearer.assertion`: the inline assertion value.
+* `rest.auth.oauth2.jwt-bearer.assertion-file`: path to a file whose content (read and
+  trimmed) is used as the assertion; ignored if `assertion` is set.
+
+The assertion is taken from the inline `assertion` if set, otherwise from the file at
+`assertion-file` if set, otherwise from dynamic configuration under `assertion.*`.
+
+Here is an example of using a static assertion:
+
+```properties
+rest.auth.type=com.dremio.iceberg.authmgr.oauth2.OAuth2Manager
+
+rest.auth.oauth2.issuer-url=https://$IDP/realms/main
+rest.auth.oauth2.grant-type=urn:ietf:params:oauth:grant-type:jwt-bearer
+rest.auth.oauth2.client-id=Client1
+rest.auth.oauth2.client-secret=$CLIENT1_SECRET
+rest.auth.oauth2.scope=catalog1
+
+rest.auth.oauth2.jwt-bearer.assertion=$ASSERTION
+```
+
+### Using Dynamic Assertions
+
+To enable dynamic fetching of assertions, the `rest.auth.oauth2.jwt-bearer.assertion` and
+`rest.auth.oauth2.jwt-bearer.assertion-file` properties must _not_ be set.
+
+Then, details for fetching the assertion must be provided under:
+
+* `rest.auth.oauth2.jwt-bearer.assertion.*`
+
+Any property that can be set under the `rest.auth.oauth2.` prefix can also be set under this
+prefix, and will be used to configure a secondary agent for fetching the assertion.
+
+```properties
+rest.auth.type=com.dremio.iceberg.authmgr.oauth2.OAuth2Manager
+
+rest.auth.oauth2.issuer-url=https://$PRIMARY_IDP/realms/primary
+rest.auth.oauth2.grant-type=urn:ietf:params:oauth:grant-type:jwt-bearer
+rest.auth.oauth2.client-id=Client1
+rest.auth.oauth2.client-secret=$CLIENT1_SECRET
+rest.auth.oauth2.scope=catalog1
+
+rest.auth.oauth2.jwt-bearer.assertion.issuer-url=https://$SECONDARY_IDP/realms/secondary
+rest.auth.oauth2.jwt-bearer.assertion.grant-type=authorization_code
+rest.auth.oauth2.jwt-bearer.assertion.client-id=Client2
+rest.auth.oauth2.jwt-bearer.assertion.client-secret=$CLIENT2_SECRET
+rest.auth.oauth2.jwt-bearer.assertion.scope=catalog2
+```
+
+For Microsoft Entra ID on-behalf-of requests, configure the assertion using one of the above
+methods and add vendor-specific parameters with `rest.auth.oauth2.extra-params.*`, for example:
+
+```properties
+rest.auth.oauth2.extra-params.requested_token_use=on_behalf_of
+```

docs/token-exchange.md

@@ -160,7 +160,7 @@ rest.auth.oauth2.token-exchange.actor-token.grant-type=client_credentials
 rest.auth.oauth2.token-exchange.actor-token.scope=catalog3
 rest.auth.oauth2.token-exchange.actor-token.client-id=Client3
 rest.auth.oauth2.token-exchange.actor-token.client-auth=private_key_jwt
-rest.auth.oauth2.token-exchange.actor-token.client-assertion.jwt.private-key=/path/to/private_key.pem
+rest.auth.oauth2.token-exchange.actor-token.client-auth.jwt.private-key=/path/to/private_key.pem
 ```
 
 In this example:

oauth2/core/src/docs/java/com/dremio/iceberg/authmgr/oauth2/docs/DocumentationGenerator.java

@@ -62,6 +62,7 @@ public class DocumentationGenerator {
     refs.put("GrantType#AUTHORIZATION_CODE", "authorization_code");
     refs.put("GrantType#REFRESH_TOKEN", "refresh_token");
     refs.put("GrantType#DEVICE_CODE", "urn:ietf:params:oauth:grant-type:device_code");
+    refs.put("GrantType#JWT_BEARER", "urn:ietf:params:oauth:grant-type:jwt-bearer");
     refs.put("GrantType#TOKEN_EXCHANGE", "urn:ietf:params:oauth:grant-type:token-exchange");
     refs.put("JWSAlgorithm#HS512", "HS512");
     refs.put("JWSAlgorithm#RS512", "RS512");
@@ -229,7 +230,14 @@ private String resolveReference(Section section, String ref, String text) {
         String className = section.configClass.getPackageName() + "." + parts[0];
         String fieldName = parts[1];
         JavaClass classRef = builder.getClassByName(className);
+        if (classRef == null) {
+          throw new IllegalArgumentException("Unresolved documentation reference: " + ref);
+        }
         Section refSection = sections.get(classRef.getFullyQualifiedName());
+        if (refSection == null) {
+          throw new IllegalArgumentException(
+              "Unsupported external documentation reference: " + ref);
+        }
         refTarget = refSection.refs.get(fieldName);
       }
     }