Add use_id_token_as_bearer to OAuth Resource Metadata and bump version to 0.1.21

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

Author: rustyconover

docs/api/oauth.md

@@ -47,7 +47,7 @@ with http_connect(MyService, "https://api.example.com") as svc:
 ## How It Works
 
 1. Server serves `/.well-known/oauth-protected-resource` (RFC 9728)
-2. 401 responses include `WWW-Authenticate: Bearer resource_metadata="..."` (and optionally `client_id="..."`, `client_secret="..."`)
+2. 401 responses include `WWW-Authenticate: Bearer resource_metadata="..."` (and optionally `client_id="..."`, `client_secret="..."`, `use_id_token_as_bearer="true"`)
 3. Client fetches metadata to discover authorization server(s)
 4. Client authenticates with the AS and sends Bearer token
 
@@ -57,17 +57,18 @@ If a client doesn't know the server's auth requirements upfront, it can
 discover them from a 401 response:
 
 ```python
-from vgi_rpc.http import parse_resource_metadata_url, parse_client_id, parse_client_secret, fetch_oauth_metadata
+from vgi_rpc.http import parse_resource_metadata_url, parse_client_id, parse_client_secret, parse_use_id_token_as_bearer, fetch_oauth_metadata
 
 # 1. Make a request that returns 401
 resp = client.post("/vgi/my_method", ...)
 
-# 2. Parse the metadata URL, optional client_id and client_secret from WWW-Authenticate header
+# 2. Parse the metadata URL, optional client_id, client_secret, and use_id_token_as_bearer from WWW-Authenticate header
 www_auth = resp.headers["www-authenticate"]
 metadata_url = parse_resource_metadata_url(www_auth)
 # "https://api.example.com/.well-known/oauth-protected-resource/vgi"
 client_id = parse_client_id(www_auth)  # e.g. "my-app" or None
 client_secret = parse_client_secret(www_auth)  # e.g. "my-secret" or None
+use_id_token = parse_use_id_token_as_bearer(www_auth)  # True or False
 
 # 3. Fetch the metadata
 meta = fetch_oauth_metadata(metadata_url)
@@ -94,6 +95,7 @@ Pass to `make_wsgi_app(oauth_resource_metadata=...)` to enable OAuth discovery.
 | `resource_tos_uri` | `str \| None` | No | URL to terms of service |
 | `client_id` | `str \| None` | No | OAuth client_id for auth server *(custom extension, not in RFC 9728)* |
 | `client_secret` | `str \| None` | No | OAuth client_secret for auth server *(custom extension, not in RFC 9728)*. Intended for public/PKCE clients (e.g. Google OAuth) where the secret is not truly confidential. |
+| `use_id_token_as_bearer` | `bool` | No | When `True`, clients should use the OIDC `id_token` as the Bearer token instead of `access_token` *(custom extension, not in RFC 9728)* |
 
 Raises `ValueError` if `resource` is empty or `authorization_servers` is empty.
 
@@ -303,18 +305,31 @@ client_secret = parse_client_secret('Bearer resource_metadata="https://...", cli
 
 Returns `None` if the header doesn't contain `client_secret`.
 
+## parse_use_id_token_as_bearer()
+
+Extract the `use_id_token_as_bearer` flag from a `WWW-Authenticate` header. Custom extension (not in RFC 9728).
+
+```python
+from vgi_rpc.http import parse_use_id_token_as_bearer
+
+use_id_token = parse_use_id_token_as_bearer('Bearer resource_metadata="https://...", use_id_token_as_bearer="true"')
+# True
+```
+
+Returns `False` if the header doesn't contain `use_id_token_as_bearer`.
+
 ## OAuthResourceMetadataResponse
 
 Frozen dataclass returned by `http_oauth_metadata()` and `fetch_oauth_metadata()`.
-Same fields as `OAuthResourceMetadata` (the server-side config class), including `client_id` and `client_secret`.
+Same fields as `OAuthResourceMetadata` (the server-side config class), including `client_id`, `client_secret`, and `use_id_token_as_bearer`.
 
 ## Standards Compliance
 
 - [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) — OAuth 2.0 Protected Resource Metadata
 - [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414) — OAuth 2.0 Authorization Server Metadata
 - [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750) — Bearer Token Usage
 - Compatible with MCP's OAuth implementation
-- **Custom extensions**: `client_id` and `client_secret` fields on `OAuthResourceMetadata` / `OAuthResourceMetadataResponse` and in `WWW-Authenticate` headers are not defined in RFC 9728
+- **Custom extensions**: `client_id`, `client_secret`, and `use_id_token_as_bearer` fields on `OAuthResourceMetadata` / `OAuthResourceMetadataResponse` and in `WWW-Authenticate` headers are not defined in RFC 9728
 
 ## Installation
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-rpc"
-version = "0.1.20"
+version = "0.1.21"
 description = "Vector Gateway Interface - RPC framework based on Apache Arrow"
 readme = "README.md"
 requires-python = ">=3.13"

tests/test_oauth.py

@@ -28,6 +28,7 @@
     parse_client_id,
     parse_client_secret,
     parse_resource_metadata_url,
+    parse_use_id_token_as_bearer,
 )
 
 # ---------------------------------------------------------------------------
@@ -127,6 +128,7 @@ def authenticate(req: falcon.Request) -> AuthContext:
 _METADATA_WITH_CLIENT_SECRET = dataclasses.replace(
     _METADATA, client_id="my-client-id", client_secret="my-client-secret"
 )
+_METADATA_WITH_ID_TOKEN = dataclasses.replace(_METADATA, use_id_token_as_bearer=True)
 
 
 # ---------------------------------------------------------------------------
@@ -467,6 +469,81 @@ def test_client_discovery_round_trip_with_client_secret(self) -> None:
         assert meta is not None
         assert meta.client_secret == "my-client-secret"
 
+    def test_use_id_token_as_bearer_in_well_known_json_when_true(self) -> None:
+        """use_id_token_as_bearer appears in well-known JSON when True."""
+        server = RpcServer(_EchoService, _EchoImpl())
+        client = make_sync_client(server, signing_key=b"k", oauth_resource_metadata=_METADATA_WITH_ID_TOKEN)
+        resp = client.get("/.well-known/oauth-protected-resource")
+        body = json.loads(resp.content)
+        assert body["use_id_token_as_bearer"] is True
+
+    def test_use_id_token_as_bearer_absent_from_well_known_json_when_false(self) -> None:
+        """use_id_token_as_bearer absent from well-known JSON when False."""
+        d = _METADATA.to_json_dict()
+        assert "use_id_token_as_bearer" not in d
+
+    def test_use_id_token_as_bearer_in_www_authenticate(self) -> None:
+        """use_id_token_as_bearer appears in WWW-Authenticate header when True."""
+        _priv, pub = _make_rsa_key()
+        auth_fn = _make_local_auth(pub)
+        server = RpcServer(_EchoService, _EchoImpl())
+        client = make_sync_client(
+            server,
+            signing_key=b"k",
+            authenticate=auth_fn,
+            oauth_resource_metadata=_METADATA_WITH_ID_TOKEN,
+        )
+        resp = client.post(
+            "/vgi/echo",
+            content=b"garbage",
+            headers={"Content-Type": "application/octet-stream"},
+        )
+        assert resp.status_code == 401
+        www_auth = resp.headers.get("www-authenticate", "")
+        assert 'use_id_token_as_bearer="true"' in www_auth
+
+    def test_use_id_token_as_bearer_absent_from_www_authenticate(self) -> None:
+        """use_id_token_as_bearer absent from WWW-Authenticate when False."""
+        _priv, pub = _make_rsa_key()
+        auth_fn = _make_local_auth(pub)
+        server = RpcServer(_EchoService, _EchoImpl())
+        client = make_sync_client(
+            server,
+            signing_key=b"k",
+            authenticate=auth_fn,
+            oauth_resource_metadata=_METADATA,
+        )
+        resp = client.post(
+            "/vgi/echo",
+            content=b"garbage",
+            headers={"Content-Type": "application/octet-stream"},
+        )
+        assert resp.status_code == 401
+        www_auth = resp.headers.get("www-authenticate", "")
+        assert "use_id_token_as_bearer" not in www_auth
+
+    def test_parse_use_id_token_as_bearer_extracts_value(self) -> None:
+        """parse_use_id_token_as_bearer() extracts value from header."""
+        header = (
+            'Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource/vgi"'
+            ', use_id_token_as_bearer="true"'
+        )
+        assert parse_use_id_token_as_bearer(header) is True
+
+    def test_parse_use_id_token_as_bearer_returns_false_when_absent(self) -> None:
+        """parse_use_id_token_as_bearer() returns False when not present."""
+        assert parse_use_id_token_as_bearer("Bearer") is False
+        assert parse_use_id_token_as_bearer('Bearer resource_metadata="https://example.com"') is False
+        assert parse_use_id_token_as_bearer("") is False
+
+    def test_client_discovery_round_trip_with_use_id_token_as_bearer(self) -> None:
+        """Client discovers use_id_token_as_bearer set on server."""
+        server = RpcServer(_EchoService, _EchoImpl())
+        client = make_sync_client(server, signing_key=b"k", oauth_resource_metadata=_METADATA_WITH_ID_TOKEN)
+        meta = http_oauth_metadata(client=client)
+        assert meta is not None
+        assert meta.use_id_token_as_bearer is True
+
     def test_401_discovery_flow(self) -> None:
         """Full 401-based discovery: get 401, parse header, fetch metadata."""
         _priv, pub = _make_rsa_key()

vgi_rpc/http/__init__.py

@@ -39,6 +39,7 @@
     parse_client_id,
     parse_client_secret,
     parse_resource_metadata_url,
+    parse_use_id_token_as_bearer,
     request_upload_urls,
 )
 from vgi_rpc.http._common import (
@@ -94,6 +95,7 @@
     "parse_client_id",
     "parse_client_secret",
     "parse_resource_metadata_url",
+    "parse_use_id_token_as_bearer",
     "make_wsgi_app",
     "serve_http",
     "request_upload_urls",

vgi_rpc/http/_client.py

@@ -952,6 +952,9 @@ class OAuthResourceMetadataResponse:
             authorization server.  Custom extension (not in RFC 9728).
         client_secret: OAuth client_secret to use when authenticating with the
             authorization server.  Custom extension (not in RFC 9728).
+        use_id_token_as_bearer: When ``True``, the client should use the
+            OIDC ``id_token`` as the Bearer token instead of the
+            ``access_token``.  Custom extension (not in RFC 9728).
 
     """
 
@@ -966,6 +969,7 @@ class OAuthResourceMetadataResponse:
     resource_tos_uri: str | None = None
     client_id: str | None = None
     client_secret: str | None = None
+    use_id_token_as_bearer: bool = False
 
 
 def http_oauth_metadata(
@@ -1019,6 +1023,7 @@ def http_oauth_metadata(
 _RESOURCE_METADATA_RE = re.compile(r'resource_metadata="([^"]+)"')
 _CLIENT_ID_RE = re.compile(r'client_id="([^"]+)"')
 _CLIENT_SECRET_RE = re.compile(r'client_secret="([^"]+)"')
+_USE_ID_TOKEN_RE = re.compile(r'use_id_token_as_bearer="([^"]+)"')
 
 
 def parse_resource_metadata_url(www_authenticate: str) -> str | None:
@@ -1076,6 +1081,25 @@ def parse_client_secret(www_authenticate: str) -> str | None:
     return match.group(1) if match else None
 
 
+def parse_use_id_token_as_bearer(www_authenticate: str) -> bool:
+    """Extract the ``use_id_token_as_bearer`` flag from a ``WWW-Authenticate`` header.
+
+    Parses a ``Bearer`` challenge and returns ``True`` if the
+    ``use_id_token_as_bearer`` parameter is present with value ``"true"``.
+    This is a custom extension (not defined in RFC 9728).
+
+    Args:
+        www_authenticate: The ``WWW-Authenticate`` header value.
+
+    Returns:
+        ``True`` if the header contains ``use_id_token_as_bearer="true"``,
+        ``False`` otherwise.
+
+    """
+    match = _USE_ID_TOKEN_RE.search(www_authenticate)
+    return match.group(1) == "true" if match else False
+
+
 def _parse_metadata_json(body: dict[str, Any]) -> OAuthResourceMetadataResponse:
     """Parse a JSON dict into an ``OAuthResourceMetadataResponse``.
 
@@ -1101,6 +1125,7 @@ def _parse_metadata_json(body: dict[str, Any]) -> OAuthResourceMetadataResponse:
         resource_tos_uri=body.get("resource_tos_uri"),
         client_id=body.get("client_id"),
         client_secret=body.get("client_secret"),
+        use_id_token_as_bearer=body.get("use_id_token_as_bearer", False),
     )
 
 

vgi_rpc/http/_oauth.py

@@ -48,6 +48,9 @@ class OAuthResourceMetadata:
         client_secret: OAuth client_secret that clients should use when
             authenticating with the authorization server.  Custom
             extension (not defined in RFC 9728).
+        use_id_token_as_bearer: When ``True``, tells clients to use the
+            OIDC ``id_token`` as the Bearer token instead of the
+            ``access_token``.  Custom extension (not defined in RFC 9728).
 
     Raises:
         ValueError: If *resource* is empty or *authorization_servers* is empty.
@@ -65,6 +68,7 @@ class OAuthResourceMetadata:
     resource_tos_uri: str | None = None
     client_id: str | None = None
     client_secret: str | None = None
+    use_id_token_as_bearer: bool = False
 
     def __post_init__(self) -> None:
         """Validate required fields."""
@@ -114,6 +118,8 @@ def to_json_dict(self) -> dict[str, object]:
             d["client_id"] = self.client_id
         if self.client_secret is not None:
             d["client_secret"] = self.client_secret
+        if self.use_id_token_as_bearer:
+            d["use_id_token_as_bearer"] = True
         return d
 
 
@@ -164,4 +170,6 @@ def _build_www_authenticate(metadata: OAuthResourceMetadata, prefix: str = "/vgi
     # as a "public" secret for native/SPA apps, not a truly confidential value.
     if metadata.client_secret is not None:
         challenge += f', client_secret="{metadata.client_secret}"'
+    if metadata.use_id_token_as_bearer:
+        challenge += ', use_id_token_as_bearer="true"'
     return challenge