Need help creating ApplicationIntegrationToolset with OAuth2.0

[maheshwaritanay]

We want to create an agent that can fetch issues from JIRA but before calling the tool user needs to authenticate/authorize. Once the access token is received it should be refreshed with a TTL of 8hours.

We have setup integration connector but are facing issue when using OAuth. Steps followed so far-

1. created a JIRA app in atlassian developer console
2. Collected clientID and secret
3. Configured redirect uri to http://127.0.0.1:8000/dev-ui/ since we are testing on ADK web UI currently
4. Following is the code as per https://google.github.io/adk-docs/tools/google-cloud/application-integration/#create-an-application-integration-toolset -

connection_name = os.getenv("CONNECTION_NAME", "agent-connector-jira")
connection_project = os.getenv("CONNECTION_PROJECT", "")
connection_location = os.getenv("CONNECTION_LOCATION", "us-east4")

jira_oauth2_config = {
    "type": "oauth2",
    "flows": {
        "authorizationCode": {
            "authorizationUrl": "https://auth.atlassian.com/authorize",
            "tokenUrl": "https://auth.atlassian.com/oauth/token",
            "scopes": {
                "read:jira-work": "Read Jira project and issue data",
                "write:jira-work": "Create and edit Jira issues",
                "read:jira-user": "Read user information",
                "offline_access": "Maintain access to data"
            },
        }
    },
}

# Convert to auth scheme
oauth_scheme = dict_to_auth_scheme(jira_oauth2_config)

# Create auth credential with your Jira OAuth app credentials
auth_credential = AuthCredential(
    auth_type=AuthCredentialTypes.OAUTH2,
    oauth2=OAuth2Auth(
        client_id="",      # From Atlassian Developer Console
        client_secret="", # From Atlassian Developer Console
    ),
)

jira_toolset = ApplicationIntegrationToolset(
    project=connection_project,
    location=connection_location,
    connection=connection_name,
    entity_operations={"Issues": [], "Projects": []},
    tool_name_prefix="jira_issue_manager",
    auth_scheme=oauth_scheme,
    auth_credential=auth_credential
)

root_agent = LlmAgent(
    model="gemini-2.5-pro",
    name="Issue_Management_Agent",
    instruction="""
    You are an agent that helps manage issues in a Jira.
    """,
    tools=[jira_toolset],
)

app = App(
    name="poc_agent_connectors",
    root_agent=root_agent
)

Behavior observed

1. When first request to access tool goes we get an agent message saying "I am sorry, but I need your authorization to access your data. Please authorize me to proceed."
2. Events chain is as follows - UserQuery -> call JiraTool -> adk_request_credential(long running) -> response jiraTool
3. At this point it was not clear how to proceed but after digging around I found authUri in functionCall.args.authConfig.exchangedAuthCredential.oauth2.authUri
4. I just opened it in a separate tab, it prompted me for consent.
5. After granting consent i got an error page
6. But the subsequent query to the Jira tool in adk web UI worked. I could still see the long running tool call for request credential
7. However, when I tried to query next time the tool call got stuck.

Questions

1. I dont think the behavior I observed was intended but I am also not able to find a way to make it work. It would be great if someone could tell me what needs to be fixed in my workflow
2. Need help understanding how to refresh tokens lets say the above works
3. Finally, we are using agent engine for deployment. How would this credential exchange work there

adk version - 1.21.0
WebUI- adk-web
OAuth provider- Atlassian with microsoft login

[wuliang229]

@seanzhougoogle can you take a look and provide some guidance?

[maheshwaritanay]

@seanzhougoogle could you please help

[adk-bot]

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

TLDR: Your observed behavior is very close to the intended workflow. The main issue is that your application (the adk-web UI) needs to capture the full redirect URL after you grant consent and provide it back to the ADK to complete the token exchange. The ADK will handle token refreshes automatically. For agent engine deployments, your client application will be responsible for handling the interactive part of the OAuth flow.

---

Hello! As a helpful agent, I can provide some guidance on using OAuth 2.0 with the ApplicationIntegrationToolset in ADK.

1. Correct Workflow for OAuth 2.0

Your understanding of the OAuth 2.0 flow is mostly correct. The behavior you are observing is expected, but you are missing one final step. Here is a breakdown of the intended workflow:

1. When your agent needs to access a tool that requires OAuth 2.0 authentication, the ADK will return a long-running tool call to adk_request_credential.
2. The arguments of this tool call will contain an authUri. You need to open this URI in a web browser.
3. You will be prompted to grant consent to the permissions requested by your application.
4. After you grant consent, the OAuth provider will redirect your browser to the redirect_uri you configured in your Atlassian developer console. This redirect URI will contain an authorization code as a query parameter.
5. Your application (in this case, the adk-web UI) needs to capture the full redirect URL, including the authorization code.
6. You then need to provide this full redirect URL back to the ADK. The ADK will then exchange the authorization code for an access token and a refresh token.

The issue you are facing is that the adk-web UI is not set up to automatically handle the redirect and provide the authorization code back to the ADK. You will need to manually copy the full redirect URL from your browser's address bar after granting consent and provide it to the ADK.

For more details on the authentication workflow in ADK, you can refer to the ADK documentation on authentication. [1]

2. Token Refresh

The ADK handles token refreshes automatically. When you successfully complete the OAuth 2.0 flow, the ADK will store the access token and the refresh token. When the access token expires, the ADK will automatically use the refresh token to obtain a new access token. You do not need to implement any custom logic for token refreshes.

3. Credential Exchange in Agent Engine

When you deploy your agent to the agent engine, the credential exchange workflow is very similar.

1. Your agent will still return an adk_request_credential tool call when it needs to authenticate.
2. The application that is interacting with your agent engine is responsible for handling this tool call.
3. Your application needs to extract the authUri, present it to the user (e.g., by opening it in a browser), and handle the redirect from the OAuth provider.
4. Your application then needs to call your agent again, providing the full redirect URL with the authorization code.

The key takeaway is that the interactive part of the OAuth 2.0 flow is handled by the client application that is communicating with your agent.

For a more detailed explanation of how to handle authentication in a client application, please see the examples in the ADK documentation. [2][3]

I hope this helps!

---

[1] https://google.github.io/adk-docs/tools-custom/authentication/
[2] https://github.com/google/adk-docs/blob/main/examples/python/snippets/tools/auth/agent_cli.py
[3] https://github.com/google/adk-python/blob/main/contributing/samples/oauth_calendar_agent/README.md