Handling Session Idle Timeout and Re-authentication in MCP OAuth2 Flow

[guilmour]

Hey, everyone!

I'm working on an agent that connects to an MCP server using an OAuth2 flow (via browser popup).

Currently, the first authentication works fine and I have implemented a header_provider to handle the access_token refresh logic before each MCP call. This works fine for standard token rotation. However, I’ve hit a roadblock regarding the "Session Idle Timeout" on the Authorization Server.

But, when the session idle limit is reached, both the access_token and the refresh_token are invalidated. At this point, I guess, I would like to make the agent to re-initiate the full authorization flow (opening the browser popup again) using ask_request_credential.

So my question is:

How can I "call" ask_request_credential again to make the user authenticate?

I am currently testing this using the ADK web interface. Any insights or examples on handling this "hard" session expiration would be greatly appreciated!

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: You don't call ask_request_credential directly. Instead, your header_provider or tool logic should catch the exception that occurs when the refresh token fails, clear the invalid credentials from tool_context.state, and then call tool_context.request_credential(). This signals the ADK to restart the authentication flow.

---

Hello! That's an excellent question about handling the complete expiration of an OAuth2 session.

Based on the ADK's design, the key is to correctly handle the error when the token refresh fails. When the session idle timeout is reached and the refresh token is invalidated, your attempt to refresh it will result in an exception (e.g., google.auth.exceptions.RefreshError).

Your tool or header_provider should be designed to handle this specific scenario. Here’s the recommended flow:

1. Detect Refresh Failure: In your logic that attempts to refresh the token, add a try...except block to catch the RefreshError or a similar exception that indicates the refresh token is no longer valid.

2. Clear Invalid State: Inside the except block, the first step is to remove the now-useless credentials from the session state. This prevents the agent from trying to use them again. You can do this with tool_context.state.pop(YOUR_CREDENTIAL_KEY).

3. Request New Credentials: After clearing the state, call tool_context.request_credential(YOUR_AUTH_CONFIG). This is the crucial step. This function tells the ADK framework that authentication is required. The ADK will then stop the current tool execution and emit a new FunctionCall event for adk_request_credential.

Your client application (the ADK web interface) will receive this event and should be configured to handle it by re-initiating the user-facing authentication process, such as opening the browser popup for the user to log in again.

This pattern ensures that the authentication state is correctly managed, allowing the agent to gracefully recover from a total session expiration and prompt the user for re-authentication. A very similar flow is used internally in ADK's unit tests to verify this exact behavior [9].

[guilmour]

@adk-bot how can i get the auth information stored given a context for checking?

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: When your API call fails due to an invalid session, catch the error within your tool function. In the error handler, clear the invalid token from tool_context.state and call tool_context.request_credential() to restart the authentication flow.

---

Hey @guilmour,

That's a great question about handling session expiry. Your intuition to use the header_provider to detect the issue is on the right track, but the re-authentication itself is triggered from within the tool's execution context.

The ADK is designed so that you don't call ask_request_credential directly. Instead, you signal to the ADK framework that credentials are required, and the framework then orchestrates the process of asking the user.

The way to signal this is by using tool_context.request_credential(). [1] When your tool's logic determines that the current tokens are invalid (e.g., by catching a 401 Unauthorized error from your MCP server), you can call this method.

Here is a conceptual workflow for your tool:

1. Your header_provider attempts to add the access_token to a request. If the refresh token is also invalid, the provider might not be able to get a new token.
2. Your API client makes a call and receives a 401 Unauthorized error because the token is invalid or missing.
3. Your tool code, which called the API client, should have a try...except block to catch this specific authorization error.
4. In the except block, you should:
   a. Clear the now-invalid tokens from tool_context.state to avoid using them again.
   b. Call tool_context.request_credential(AUTH_CONFIG), where AUTH_CONFIG is the same authentication configuration you used initially.

This call will stop the current tool execution and instruct the client (the ADK web interface in your case) to restart the authentication flow. Once the user re-authenticates, the ADK will re-run the tool, and this time the credentials in tool_context.state will be fresh.

Here’s a simplified pseudo-code example of what your tool might look like:

from google.adk.tools import ToolContext

# Assume MY_API_AUTH_CONFIG and TOKEN_CACHE_KEY are defined
def my_tool_function(tool_context: ToolContext, ...):
    try:
        # Your tool logic that makes an API call.
        # This call will fail if the session has expired.
        mcp_server_client.make_api_call(...)

    except ApiUnauthorizedError: # Replace with the actual exception your client raises for a 401
        # The session has expired. Time to re-authenticate.

        # 1. Clear the invalid cached tokens.
        print("Session expired. Clearing cached tokens.")
        tool_context.state.pop(TOKEN_CACHE_KEY, None)

        # 2. Request new credentials from the user.
        print("Requesting new user authentication.")
        tool_context.request_credential(MY_API_AUTH_CONFIG)

        # You can optionally return a message to the user.
        return {"status": "Your session has expired. Please log in again to continue."}

This approach ensures that the re-authentication is handled gracefully within the ADK's stateful execution model. You can find more details about the ToolContext and its capabilities in the official documentation. [2]

Hope this helps you solve the roadblock!

---

[1] https://google.github.io/adk-docs/tools-custom/authentication/
[2] https://google.github.io/adk-docs/context/