Skip to content

Commit 9511479

Browse files
google-genai-botcopybara-github
authored andcommitted
fix(openapi): handle HTTP 401 in RestApiTool and recover stale OAuth2 credentials
Fixes #7085 Credit to Philipp Horstenkamp, who reported the issue and first fixed it in PR #7087. That fix recovers a conversation started after the token went bad, but leaves the rejected credential in place for one already in progress, which is the half this CL adds; three of its negative tests are carried over here. Previously, when an OAuth2 API call returned HTTP 401 because an access token expired or was revoked, RestApiTool reported the error but left the stale credential in session state, permanently blocking subsequent tool calls. This change introduces automated recovery in ToolAuthHandler: - Reactive refresh: If a refresh token is present, automatically refreshes the access token and retries the API call once. Preserves rotated refresh tokens and prevents clobbering existing tokens during refresh. - User re-authorization: If refresh fails or is unavailable, evicts the stale credential and requests re-authorization for interactive OAuth2 flows. - Concurrency & recursion guard: Added claim_recovery() context manager to serialize recovery per credential across concurrent calls and bound retry recursion. - Budget limits: Caps re-authorization requests and reactive refreshes per credential to prevent infinite recovery loops when an API persistently returns 401. Non-401 responses refill the recovery budgets. PiperOrigin-RevId: 982498006
1 parent 0add163 commit 9511479

5 files changed

Lines changed: 2958 additions & 20 deletions

File tree

‎src/google/adk/tools/openapi_tool/openapi_spec_parser/__init__.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,11 @@
1717
from .openapi_spec_parser import ParsedOperation
1818
from .openapi_toolset import OpenAPIToolset
1919
from .operation_parser import OperationParser
20-
from .rest_api_tool import AuthPreparationState
2120
from .rest_api_tool import RestApiTool
2221
from .rest_api_tool import snake_to_lower_camel
22+
from .tool_auth_handler import AuthPreparationState
2323
from .tool_auth_handler import ToolAuthHandler
24+
from .tool_auth_handler import UnauthorizedRecoveryState
2425

2526
__all__ = [
2627
'OpenApiSpecParser',
@@ -32,4 +33,5 @@
3233
'snake_to_lower_camel',
3334
'AuthPreparationState',
3435
'ToolAuthHandler',
36+
'UnauthorizedRecoveryState',
3537
]

‎src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py‎

Lines changed: 70 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,6 @@
2121
from typing import Dict
2222
from typing import Final
2323
from typing import List
24-
from typing import Literal
2524
from typing import Optional
2625
from typing import Tuple
2726
from typing import Union
@@ -52,6 +51,7 @@
5251
from .openapi_spec_parser import OperationEndpoint
5352
from .openapi_spec_parser import ParsedOperation
5453
from .operation_parser import OperationParser
54+
from .tool_auth_handler import AuthPreparationState as AuthPreparationState
5555
from .tool_auth_handler import ToolAuthHandler
5656

5757
logger = logging.getLogger("google_adk." + __name__)
@@ -75,8 +75,6 @@ def snake_to_lower_camel(snake_case_string: str):
7575
])
7676

7777

78-
AuthPreparationState = Literal["pending", "done"]
79-
8078
HttpxClientFactory = Callable[[], httpx.AsyncClient]
8179
"""Type alias for a zero-argument factory returning an ``httpx.AsyncClient``.
8280
@@ -522,11 +520,13 @@ async def call(
522520
523521
Args:
524522
args: Keyword arguments representing the operation parameters.
525-
tool_context: The tool context (not used here, but required by the
526-
interface).
523+
tool_context: The tool context. Supplies the credential store used to
524+
prepare authentication, and on an HTTP 401 it carries the recovery
525+
attempt and the guard that bounds the retry.
527526
528527
Returns:
529-
The API response as a dictionary.
528+
The API response as a dictionary. HTTP and authorization failures are
529+
reported as an "error" entry rather than raised.
530530
"""
531531
# Prepare auth credentials for the API call
532532
tool_auth_handler = ToolAuthHandler.from_tool_context(
@@ -609,6 +609,32 @@ async def call(
609609
response.status_code,
610610
)
611611

612+
# A 401 must carry a WWW-Authenticate challenge, so key the recovery on
613+
# the challenge rather than on the status code alone. RFC 6750 pairs
614+
# insufficient_scope with 403, but a fair number of APIs return it as a
615+
# 401; recovering from those would evict a working credential and
616+
# ask the user again for the same scopes that just failed, since the
617+
# request is rebuilt from the same auth scheme. A server that omits the
618+
# challenge leaves nothing to key on and keeps the benefit of the doubt.
619+
token_rejected = False
620+
if response.status_code == 401:
621+
www_authenticate = response.headers.get("www-authenticate", "").lower()
622+
token_rejected = (
623+
"invalid_token" in www_authenticate or not www_authenticate
624+
)
625+
626+
# A 401 of any flavour means the request was not authenticated, so none of
627+
# them are evidence that the credential works -- not even one whose
628+
# challenge avoids naming the token, which may simply be a server asking
629+
# for a different scheme entirely. Every other status did get past the
630+
# authentication gate, so each refills the recovery budgets exactly as a
631+
# 200 does: counting only 2xx would let one bad argument from the model, or
632+
# one server-side 500, strand a working credential with its budgets spent.
633+
# Placed above the decode for the same reason, since a response the API
634+
# meant as a success but did not encode as JSON still counts.
635+
if response.status_code != 401:
636+
tool_auth_handler.note_successful_call()
637+
612638
# Parse API response
613639
try:
614640
response.raise_for_status() # Raise HTTPStatusError for bad responses
@@ -621,6 +647,44 @@ async def call(
621647
response.status_code,
622648
error_details,
623649
)
650+
if token_rejected and auth_credential and tool_context:
651+
# The claim covers the retry below, not just the recovery call: the
652+
# retried call builds its own handler, which must find the claim taken
653+
# so that a persistently failing endpoint cannot recurse.
654+
with tool_auth_handler.claim_recovery() as claimed:
655+
if claimed:
656+
recovery = await tool_auth_handler.handle_unauthorized_error()
657+
if recovery == "refreshed":
658+
self._logger.info(
659+
"Successfully refreshed OAuth2 token for tool %s after 401."
660+
" Retrying call.",
661+
self.name,
662+
)
663+
return await self.call(args=args, tool_context=tool_context)
664+
665+
if recovery == "reauth_requested":
666+
return {
667+
"pending": True,
668+
"message": "Needs your authorization to access your data.",
669+
}
670+
671+
if recovery == "reauth_limit_reached":
672+
# Distinct from the generic error below, which invites the model
673+
# to retry: re-authorizing has already been tried for this
674+
# credential and did not help, so the useful next step is to tell
675+
# the user rather than to call the tool again.
676+
return {
677+
"error": (
678+
f"Tool {self.name} execution failed. The user already"
679+
" re-authorized this connection and the API still"
680+
" rejected the credential, so retrying will not help."
681+
" Report this to the user and suggest checking the"
682+
" application's access or permission settings."
683+
f" Status Code: {response.status_code}, {error_details}"
684+
)
685+
}
686+
# "failed": fall through to the generic error below.
687+
624688
return {
625689
"error": (
626690
f"Tool {self.name} execution failed. Analyze this execution error"

0 commit comments

Comments
 (0)