| name | google-agents-cli-adk-auth |
| description | This skill should be used when the user wants to "configure 3-legged OAuth for an ADK agent", "build a custom UI proxy handling ADK credentials", "intercept adk_request_credential", "implement agent identity auth manager", or "set up OAuth credentials:retrieve or credentials:finalize".
|
| metadata | {"author":"carlosmscabral","license":"Apache-2.0","version":"1.0.0","validation_date":"2026-07-16T00:00:00.000Z"} |
ADK 3-Legged OAuth & Auth Manager Playbook
This operational playbook serves as a specialized AI Skill for downstream coding agents and developers building decoupled frontends or middle-tier API proxies that interact with custom Agent Development Kit (ADK) agents requiring 3-Legged OAuth (3LO) via the GCP Agent Identity Auth Manager.
When to Use This Skill
Positive Triggers
- Configuring 3-legged OAuth (3LO) for ADK agents.
- Integrating GCP Agent Identity auth manager (
agentidentitycredentials.googleapis.com / V2 API).
- Intercepting
adk_request_credential function calls in middle-tier API proxies.
- Managing stateless consent nonces and OAuth callback finalization (
credentials:retrieve / credentials:finalize).
Negative Triggers (When NOT to Use)
- Standard REST SSE stream parsing, UI component rendering, or basic FastAPI proxy endpoint response models without OAuth interception -> Delegate to
google-agents-cli-adk-frontend.
📅 Effective Date & Version Warning
[!IMPORTANT]
Validation Date: July 16, 2026
This playbook leverages Alpha/Beta features of GCP Agent Identity and the ADK. Since these services are actively evolving, keep a close watch on API endpoints and schemas.
🌐 API Evolution & Consolidation
When developing against the Auth Manager, you will encounter two sets of APIs. Always prioritize the newer V2 API format:
- Modern V2 API (Recommended):
- Domain:
agentidentitycredentials.googleapis.com
- Resource Terminology:
authProviders
- Format:
projects/{project}/locations/{location}/authProviders/{provider}
- Legacy V1 API (Fallback / Deployed Environment Caveat):
- Domain:
iamconnectorcredentials.googleapis.com
- Resource Terminology:
connectors
- Format:
projects/{project}/locations/{location}/connectors/{connector}
[!WARNING]
While older cloud environments might still expect retrieve payloads on the legacy /connectors/ paths, all new integrations should aim for the unified /authProviders/ namespaces.
🔄 The 3LO Handshake Architecture
When an ADK Agent needs user consent to execute an MCP tool, it emits a special function call: adk_request_credential. A custom UI application or its middle-tier proxy must intercept this call and process it through one of two branches:
flowchart TD
A[User Prompt] --> B[Frontend Proxy -> Reasoning Engine]
B --> C{Agent returns adk_request_credential?}
C -- No --> D[Pipes text stream to UI]
C -- Yes --> E[Frontend Proxy calls credentials:retrieve]
E --> F{Is user already authorized?}
F -- Case A: No, authUri returned --> G[Proxy embeds auth_uri in stream]
G --> H[UI opens Google Login Popup]
H --> I[User grants consent]
I --> J[Callback validates & finalizes credentials]
J --> K[UI re-triggers user prompt]
F -- Case B: Yes, token returned directly --> L[Proxy extracts token]
L --> M[Proxy formats function_response payload]
M --> N[Proxy POSTs function_response to Reasoning Engine]
N --> O[Stream resumed seamlessly! No Popup!]
🛠️ Step-by-Step Skill Implementations
To implement this flow perfectly, read the detailed reference materials and use our proven code samples:
- GCP Console & Auth Provider Setup
- Interception (Standard FastAPI Middleware Proxy)
- Resumption Payload Structure
- Active Debugging & Troubleshooting
