feat(ve_identity): Add Identity Service integration with OAuth2, API Key and Workload authentication by loveyana · Pull Request #263 · volcengine/veadk-python

loveyana · 2025-10-27T11:55:56Z

This commit introduces a comprehensive integration with Identity Service, enabling ADK agents to securely manage authentication and credentials.

Key Features

1. Unified Authentication Framework

Three Authentication Types:
- OAuth2 (M2M and USER_FEDERATION flows)
- API Key authentication
- Workload access token authentication
Flexible Configuration: Simple factory functions (api_key_auth(), oauth2_auth(), workload_auth()) for easy setup

2. Tool Integration

VeIdentityFunctionTool: Funtion tool wrapper with built-in Identity authentication
VeIdentityMcpTool: MCP tool wrapper with built-in Identity authentication
VeIdentityMcpToolset: Complete MCP toolset management with automatic credential handling

3. Authentication Processing

AuthRequestProcessor: Handles OAuth2 flows in agent conversations with support for:
- Custom OAuth2 auth pollers
- Callback URL handling
- Token polling with configurable timeout
- Mock auth poller for testing
Auth Mixins: Reusable authentication logic (VeIdentityAuthMixin, ApiKeyAuthMixin, OAuth2AuthMixin, WorkloadAuthMixin) to avoid code duplication

4. Token Management

WorkloadTokenManager: Manages workload access tokens with:
- Automatic caching in session state
- Token expiration handling
- Support for JWT, user ID, and workload-only authentication modes
- Automatic token refresh

5. Identity Client

IdentityClient: Low-level async client for VolcEngine Identity Service API with:
- OAuth2 credential provider management
- API key credential provider management
- Workload token retrieval
- OAuth2 token and API key fetching
- Dynamic Client Registration (DCR) support

6. Data Models

OAuth2TokenResponse: Structured response for OAuth2 token requests
WorkloadToken: Workload token with expiration tracking
OAuth2AuthPoller: Abstract base for custom token polling implementations
DCR Models: Support for RFC 7591 Dynamic Client Registration Protocol
Authorization Server Metadata: RFC 8414 compliant metadata handling

7. Utility Functions

is_pending_auth_event(): Detect pending authentication requests in ADK events
get_function_call_id(): Extract function call IDs from auth events
get_function_call_auth_config(): Extract auth configuration from events
generate_headers(): Convert credentials to HTTP authentication headers

…Key, and Workload authentication This commit introduces a comprehensive integration with Identity Service, enabling ADK agents to securely manage authentication and credentials. ## Key Features ### 1. Unified Authentication Framework - **Three Authentication Types**: - OAuth2 (M2M and USER_FEDERATION flows) - API Key authentication - Workload access token authentication - **Flexible Configuration**: Simple factory functions (`api_key_auth()`, `oauth2_auth()`, `workload_auth()`) for easy setup ### 2. Tool Integration - **VeIdentityFunctionTool**: Funtion tool wrapper with built-in Identity authentication - **VeIdentityMcpTool**: MCP tool wrapper with built-in Identity authentication - **VeIdentityMcpToolset**: Complete MCP toolset management with automatic credential handling ### 3. Authentication Processing - **AuthRequestProcessor**: Handles OAuth2 flows in agent conversations with support for: - Custom OAuth2 auth pollers - Callback URL handling - Token polling with configurable timeout - Mock auth poller for testing - **Auth Mixins**: Reusable authentication logic (`VeIdentityAuthMixin`, `ApiKeyAuthMixin`, `OAuth2AuthMixin`, `WorkloadAuthMixin`) to avoid code duplication ### 4. Token Management - **WorkloadTokenManager**: Manages workload access tokens with: - Automatic caching in session state - Token expiration handling - Support for JWT, user ID, and workload-only authentication modes - Automatic token refresh ### 5. Identity Client - **IdentityClient**: Low-level async client for VolcEngine Identity Service API with: - OAuth2 credential provider management - API key credential provider management - Workload token retrieval - OAuth2 token and API key fetching - Dynamic Client Registration (DCR) support ### 6. Data Models - **OAuth2TokenResponse**: Structured response for OAuth2 token requests - **WorkloadToken**: Workload token with expiration tracking - **OAuth2AuthPoller**: Abstract base for custom token polling implementations - **DCR Models**: Support for RFC 7591 Dynamic Client Registration Protocol - **Authorization Server Metadata**: RFC 8414 compliant metadata handling ### 7. Utility Functions - **is_pending_auth_event()**: Detect pending authentication requests in ADK events - **get_function_call_id()**: Extract function call IDs from auth events - **get_function_call_auth_config()**: Extract auth configuration from events - **generate_headers()**: Convert credentials to HTTP authentication headers

cuericlee

Add more unit test case for public methods.

cuericlee

add usage of 3 type auth as docs of identity into https://github.com/volcengine/veadk-python/tree/main/docs/content

Copilot

Pull Request Overview

This PR introduces a comprehensive Identity Service integration for ADK agents, enabling secure authentication and credential management through three authentication methods: OAuth2, API Key, and Workload access tokens.

Key Changes:

Unified authentication framework with factory functions for easy configuration
Tool wrappers (VeIdentityFunctionTool, VeIdentityMcpTool, VeIdentityMcpToolset) with built-in authentication
OAuth2 flow handling with configurable polling and callback support
Token management with automatic caching and expiration handling

Reviewed Changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
`utils.py`	Utility functions for authentication event detection and credential header generation
`token_manager.py`	Workload token lifecycle management with session state caching
`models.py`	Data models for OAuth2, DCR, and workload tokens with validation
`mcp_toolset.py`	MCP toolset wrapper with automatic credential handling and session management
`mcp_tool.py`	Individual MCP tool wrapper with Identity authentication support
`identity_client.py`	Low-level async client for VolcEngine Identity Service API operations
`function_tool.py`	Function tool wrapper that injects credentials into wrapped functions
`auth_processor.py`	OAuth2 authentication flow processor for agent conversations
`auth_mixins.py`	Reusable authentication mixins to avoid code duplication across tool types
`auth_config.py`	Authentication configuration classes with validation and factory functions
`__init__.py`	Module exports and public API surface

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

veadk/integrations/ve_identity/token_manager.py

veadk/integrations/ve_identity/models.py

veadk/integrations/ve_identity/auth_mixins.py

- Fix Non-standard docstrings - Remove veadk prefix in logger

…resh Add unit tests for ve_identity auth_config, function_tool, mcp_tool, and mcp_toolset modules. Updated IdentityClient credential refresh logic to support fallback to VeFaaS IAM credentials if environment variables are not set, improving robustness in cloud environments.

Introduces documentation for Agent Identity authentication, including product overview, API Key outbound, OAuth2 M2M outbound, and OAuth2 USER_FEDERATION outbound.

Added VeIdentityConfig to global settings and improved region handling for Agent Identity authentication. Updated configuration files and environment variable documentation.

cuericlee · 2025-10-30T02:12:53Z

docs/content/91.auth/2.api-key-outbound.md

+export VOLCENGINE_SESSION_TOKEN="your-session-token"  # 可选
+```
+
+在 VeFaaS 环境中，Agent Identity 会自动从 `/var/run/secrets/iam/credential` 读取凭证。


update comment

cuericlee · 2025-10-30T02:41:01Z

docs/content/91.auth/3.oauth2-m2m-outbound.md

+
+### 方式一：使用内置 Vendor（推荐）
+
+选择提供商类型：**Google**、**GitHub** 或 **Coze**，填写：


add Lark as provider, Lark, Coze, Google, Github

cuericlee · 2025-10-30T02:42:01Z

docs/content/91.auth/3.oauth2-m2m-outbound.md

+### 方式二：使用 OIDC 配置
+
+选择提供商类型为 **自定义**，填写：
+- 发行者 URL：OIDC 提供商的 Discovery URL（如 `https://accounts.google.com/.well-known/openid-configuration`）


Use identity OIDC of Lark/Coze instead

Neither of them supports oidc

cuericlee · 2025-10-30T02:45:22Z

docs/content/91.auth/3.oauth2-m2m-outbound.md

+)
+toolset = VeIdentityMcpToolset(
+    auth_config=auth_config,
+    connection_params=StdioServerParameters(


Using StreambleSSE and MCPServer of https://ecs.mcp.volcbiz.com/cloud_assistant/mcp instead to support existing OAuth MCPServer.

veadk/agent.py

cuericlee · 2025-10-30T02:51:31Z

veadk/agent.py

        collect_runtime_data: bool = False,
        eval_set_id: str = "",
        save_session_to_memory: bool = False,
+        auth_request_processor: AuthRequestProcessor = AuthRequestProcessor(),


@yaozheng-fang check if this additional field impact existing agent.run?

veadk/integrations/ve_identity/mcp_toolset.py

Updated OAuth2-related classes and functions to make 'auth_flow' and 'scopes' parameters optional, allowing control plane defaults to be used if not provided.

cuericlee

/lgtm

…modules Eliminated unnecessary logger.info statements from IdentityClient and WorkloadTokenManager to reduce log verbosity and improve clarity. No changes to core logic or functionality.

…dentity dependency ## Problem Agent class had a hard dependency on Agent Identity's AuthRequestProcessor, causing all agents to depend on Agent Identity even when authentication is not needed. This violates the Dependency Inversion Principle and could break existing agents. ## Solution Introduce an abstract processor layer following the Dependency Inversion Principle: 1. Created `veadk/processors/` package with: - `BaseRunProcessor`: Abstract base class for runtime processors - `NoOpRunProcessor`: Default no-op implementation 2. Modified `veadk/agent.py`: - Added `run_processor: Optional[BaseRunProcessor]` field - Changed dependency from AuthRequestProcessor to BaseRunProcessor - Initialize with NoOpRunProcessor by default - Updated `run()` method parameter from `auth_request_processor` to `run_processor` 3. Updated `veadk/integrations/ve_identity/auth_processor.py`: - Made AuthRequestProcessor inherit from BaseRunProcessor - Renamed main method from `with_auth_loop` to `process_run`

cuericlee

/lgtm

veadk/agent.py

Eliminated the unused _NoOpAuthProcessor import and reference from ve_identity/__init__.py. Also removed a trailing blank line in processors/__init__.py and added a missing comma in NoOpRunProcessor's decorator signature for consistency.

cuericlee reviewed Oct 27, 2025

View reviewed changes

cuericlee requested a review from Copilot October 27, 2025 12:13

cuericlee reviewed Oct 27, 2025

View reviewed changes

Copilot AI reviewed Oct 27, 2025

View reviewed changes

loveyana added 2 commits October 27, 2025 20:41

fix(identity): refactor imports to use absolute paths in ve_identity

62adc03

- Fix Non-standard docstrings - Remove veadk prefix in logger

chore(identity):fix type hints for tool_context in auth mixins

35c48ec

loveyana force-pushed the feat/identity-integration branch from 57bb133 to e6f222c Compare October 29, 2025 11:14

loveyana force-pushed the feat/identity-integration branch from cad97e5 to 3561379 Compare October 29, 2025 11:16

loveyana added 2 commits October 29, 2025 20:35

feat(ve_identity): Add Agent Identity authentication docs

4e81f59

Introduces documentation for Agent Identity authentication, including product overview, API Key outbound, OAuth2 M2M outbound, and OAuth2 USER_FEDERATION outbound.

feat(identity): Integrate VeIdentity config and region support

f0d5941

Added VeIdentityConfig to global settings and improved region handling for Agent Identity authentication. Updated configuration files and environment variable documentation.

loveyana force-pushed the feat/identity-integration branch 4 times, most recently from 39b7dc7 to 10f29fd Compare October 29, 2025 19:31

cuericlee reviewed Oct 30, 2025

View reviewed changes

loveyana force-pushed the feat/identity-integration branch 3 times, most recently from 0657344 to 08db89d Compare October 30, 2025 06:55

chore(ve_identity): Make OAuth2 flow and scopes parameters optional

9bed908

Updated OAuth2-related classes and functions to make 'auth_flow' and 'scopes' parameters optional, allowing control plane defaults to be used if not provided.

loveyana force-pushed the feat/identity-integration branch 2 times, most recently from 17120a5 to 9314c09 Compare October 30, 2025 09:24

cuericlee approved these changes Oct 30, 2025

View reviewed changes

chore(ve_identity): Remove redundant logging from identity and token …

1ba91e8

…modules Eliminated unnecessary logger.info statements from IdentityClient and WorkloadTokenManager to reduce log verbosity and improve clarity. No changes to core logic or functionality.

loveyana force-pushed the feat/identity-integration branch from 15a63e8 to 1ba91e8 Compare October 30, 2025 11:43

cuericlee approved these changes Oct 31, 2025

View reviewed changes

veadk/agent.py Outdated Show resolved Hide resolved

cuericlee approved these changes Oct 31, 2025

View reviewed changes

cuericlee merged commit 993a9f6 into volcengine:main Oct 31, 2025
5 checks passed


		### 方式一：使用内置 Vendor（推荐）

		选择提供商类型：Google、GitHub 或 Coze，填写：

Comments

Conversation

loveyana commented Oct 27, 2025

Key Features

1. Unified Authentication Framework

2. Tool Integration

3. Authentication Processing

4. Token Management

5. Identity Client

6. Data Models

7. Utility Functions

Uh oh!

cuericlee left a comment

Choose a reason for hiding this comment

Uh oh!

cuericlee left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cuericlee Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

cuericlee Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

cuericlee Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

loveyana Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

cuericlee Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cuericlee Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cuericlee left a comment

Choose a reason for hiding this comment

Uh oh!

cuericlee left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants