feat(ve_identity): Add Identity Service integration with OAuth2, API 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

Author: loveyana

veadk/integrations/ve_identity/__init__.py

@@ -0,0 +1,98 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Identity integration for ADK.
+
+This module provides integration with VolcEngine Identity Service for managing
+authentication and credentials in ADK agents.
+
+Main components:
+- IdentityClient: Low-level client for identity service API calls
+- WorkloadTokenManager: Manages workload access tokens with caching
+- AuthRequestProcessor: Handles OAuth2 flows in agent conversations
+
+Example usage:
+    from veadk.integrations.ve_identity import VeIdentityFunctionTool
+
+    @VeIdentityFunctionTool(
+        provider_name="github",
+        scopes=["repo", "user"],
+        auth_flow="USER_FEDERATION",
+    )
+    async def get_github_repos(access_token: str):
+        # Tool implementation
+        pass
+"""
+
+from .auth_processor import (
+    AuthRequestConfig,
+    AuthRequestProcessor,
+    _NoOpAuthProcessor,
+    MockOauth2AuthPoller,
+    get_function_call_auth_config,
+    get_function_call_id,
+    is_pending_auth_event,
+)
+
+# New unified tools
+from .auth_config import (
+    api_key_auth,
+    oauth2_auth,
+    workload_auth,
+    ApiKeyAuthConfig,
+    OAuth2AuthConfig,
+    WorkloadAuthConfig,
+    VeIdentityAuthConfig,
+)
+from .function_tool import VeIdentityFunctionTool
+from .mcp_tool import VeIdentityMcpTool
+from .mcp_toolset import VeIdentityMcpToolset
+from .identity_client import IdentityClient
+from .models import (
+    OAuth2TokenResponse,
+    OAuth2AuthPoller,
+    WorkloadToken,
+)
+from .token_manager import WorkloadTokenManager, get_workload_token
+
+__all__ = [
+    # Client
+    "IdentityClient",
+    # Token management
+    "WorkloadTokenManager",
+    "get_workload_token",
+    "VeIdentityFunctionTool",
+    "VeIdentityMcpTool",
+    "VeIdentityMcpToolset",
+    # Auth configurations
+    "api_key_auth",
+    "oauth2_auth",
+    "workload_auth",
+    "ApiKeyAuthConfig",
+    "OAuth2AuthConfig",
+    "WorkloadAuthConfig",
+    "VeIdentityAuthConfig",
+    # Auth processor
+    "AuthRequestProcessor",
+    "_NoOpAuthProcessor",
+    "AuthRequestConfig",
+    "is_pending_auth_event",
+    "get_function_call_id",
+    "get_function_call_auth_config",
+    # Models
+    "OAuth2TokenResponse",
+    "WorkloadToken",
+    "OAuth2AuthPoller",
+    "MockOauth2AuthPoller",
+]

veadk/integrations/ve_identity/auth_config.py

@@ -0,0 +1,182 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Authentication configuration classes for Identity integration.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable, List, Literal, Optional, Union
+
+from pydantic import BaseModel, model_validator, field_validator
+
+from .models import OAuth2AuthPoller
+from .identity_client import IdentityClient
+
+
+class AuthConfig(BaseModel, ABC):
+    """Base authentication configuration."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    provider_name: str
+    identity_client: Optional[IdentityClient] = None
+    region: str = "cn-beijing"
+
+    @field_validator("provider_name")
+    @classmethod
+    def validate_provider_name_not_empty(cls, v: str) -> str:
+        """Validate that provider_name is not empty."""
+        if not v or not v.strip():
+            raise ValueError("provider_name cannot be empty")
+        return v.strip()
+
+    @property
+    @abstractmethod
+    def auth_type(self) -> str:
+        """Return the authentication type identifier."""
+        pass
+
+
+class ApiKeyAuthConfig(AuthConfig):
+    """API Key authentication configuration."""
+
+    @property
+    def auth_type(self) -> str:
+        return "api_key"
+
+
+class OAuth2AuthConfig(AuthConfig):
+    """OAuth2 authentication configuration."""
+
+    # Required fields
+    scopes: List[str]
+    auth_flow: Literal["M2M", "USER_FEDERATION"]
+    # Optional fields
+    callback_url: Optional[str] = None
+    force_authentication: bool = False
+    response_for_auth_required: Optional[Union[dict, str]] = None
+    on_auth_url: Optional[Callable[[str], Any]] = None
+    oauth2_auth_poller: Optional[Callable[[Any], OAuth2AuthPoller]] = None
+
+    @field_validator("scopes")
+    @classmethod
+    def validate_scopes_not_empty(cls, v: List[str]) -> List[str]:
+        """Validate that scopes list is not empty and contains valid scope strings."""
+        if not v:
+            raise ValueError("scopes cannot be empty")
+
+        # Validate each scope is not empty
+        for scope in v:
+            if not scope or not scope.strip():
+                raise ValueError("scope values cannot be empty")
+
+        # Remove duplicates while preserving order
+        seen = set()
+        unique_scopes = []
+        for scope in v:
+            scope = scope.strip()
+            if scope not in seen:
+                seen.add(scope)
+                unique_scopes.append(scope)
+
+        return unique_scopes
+
+    @field_validator("callback_url")
+    @classmethod
+    def validate_callback_url(cls, v: Optional[str]) -> Optional[str]:
+        """Validate callback URL format if provided."""
+        if v is not None:
+            v = v.strip()
+            if not v:
+                return None
+            # Basic URL validation
+            if not (v.startswith("http://") or v.startswith("https://")):
+                raise ValueError("callback_url must be a valid HTTP/HTTPS URL")
+        return v
+
+    @model_validator(mode="after")
+    def _validate_required_fields(self):
+        """Validate required fields."""
+        if not self.scopes:
+            raise ValueError("scopes is required for OAuth2AuthConfig")
+        if not self.auth_flow:
+            raise ValueError("auth_flow is required for OAuth2AuthConfig")
+        return self
+
+    @property
+    def auth_type(self) -> str:
+        return "oauth2"
+
+class WorkloadAuthConfig(AuthConfig):
+    """Workload Access Token authentication configuration."""
+
+    @property
+    def auth_type(self) -> str:
+        return "workload"
+
+
+
+# Type alias for all auth configs
+VeIdentityAuthConfig = Union[ApiKeyAuthConfig, OAuth2AuthConfig, WorkloadAuthConfig]
+
+
+# Convenience factory functions
+def api_key_auth(
+    provider_name: str,
+    identity_client: Optional[IdentityClient] = None,
+    region: str = "cn-beijing",
+) -> ApiKeyAuthConfig:
+    """Create an API key authentication configuration."""
+    return ApiKeyAuthConfig(
+        provider_name=provider_name, identity_client=identity_client, region=region
+    )
+
+def workload_auth(
+    provider_name: str,
+    identity_client: Optional[IdentityClient] = None,
+    region: str = "cn-beijing",
+) -> WorkloadAuthConfig:
+    """Create a workload authentication configuration."""
+    return WorkloadAuthConfig(
+        provider_name=provider_name, identity_client=identity_client, region=region
+    )
+
+def oauth2_auth(
+    provider_name: str,
+    scopes: List[str],
+    auth_flow: Literal["M2M", "USER_FEDERATION"],
+    callback_url: Optional[str] = None,
+    force_authentication: bool = False,
+    response_for_auth_required: Optional[Union[dict, str]] = None,
+    on_auth_url: Optional[Callable[[str], Any]] = None,
+    oauth2_auth_poller: Optional[Callable[[Any], OAuth2AuthPoller]] = None,
+    identity_client: Optional[IdentityClient] = None,
+    region: str = "cn-beijing",
+) -> OAuth2AuthConfig:
+    """Create an OAuth2 authentication configuration."""
+    return OAuth2AuthConfig(
+        provider_name=provider_name,
+        scopes=scopes,
+        auth_flow=auth_flow,
+        callback_url=callback_url,
+        force_authentication=force_authentication,
+        response_for_auth_required=response_for_auth_required,
+        on_auth_url=on_auth_url,
+        oauth2_auth_poller=oauth2_auth_poller,
+        identity_client=identity_client,
+        region=region,
+    )