agent-identity-python-sdk 0.1.1__tar.gz

agent_identity_python_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.1
+Name: agent_identity_python_sdk
+Version: 0.1.1
+Summary: Python SDK for using Agent Identity Service
+Home-page: https://github.com/aliyun/agent-identity-dev-kit
+Author: shaoheng
+Author-email: liuyuhao.lyh@alibaba-inc.com
+License: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+
+# Agent Identity Python SDK
+
+The Agent Identity Python SDK is a Python development toolkit for accessing Agent Identity services. This SDK provides identity authentication, token management, API key acquisition, and more, supporting both synchronous and asynchronous invocation modes.
+
+## Features
+
+- **OAuth2 Access Token Acquisition**: Supports multiple OAuth2 flows for access token retrieval
+- **API Key Acquisition**: Programmatic API key retrieval
+- **STS Credential Acquisition**: Obtain temporary security token service credentials
+- **Context Management**: Thread-safe context variable management
+- **Caching Mechanism**: Built-in credential caching for improved performance
+- **Decorator Support**: Simplified authentication flow integration via decorators
+- **Concurrency Safety**: Supports multi-threading and asynchronous environments
+
+## Installation
+
+```bash
+pip install agent-identity-python-sdk
+```
+
+## Quick Start
+
+### Basic Configuration
+
+Before using the SDK, ensure you have set the correct environment variables:
+
+```bash
+export AGENT_IDENTITY_REGION_ID="cn-beijing"  # Optional, set your Region ID, default is cn-beijing
+export AGENT_IDENTITY_WORKLOAD_ACCESS_TOKEN="<your-workload-access-token>" # Optional, set your workload access token, if not specified, the Agent Identity service will be automatically called to obtain it
+export AGENT_IDENTITY_WORKLOAD_IDENTITY_NAME="<your-workload-identity-name>" # Optional, set your workload identity name, if specified, the workload identity will be used as the agent's identity, otherwise a random workload identity will be generated
+export AGENT_IDENTITY_USE_STS="true/false" # Optional, set whether to use the agent identity associated role for resource credential acquisition, default is true
+```
+
+### Using Decorators to Automatically Obtain Tokens
+
+```python
+from agent_identity_python_sdk.core import requires_access_token
+
+@requires_access_token(
+    credential_provider_name="your-provider-name",
+    inject_param_name="access_token",
+    auth_flow="USER_FEDERATION",
+    on_auth_url= lambda url: print(f"Please visit {url} to authenticate."),
+    scopes=["openid", "profile", "email"],
+    force_authentication=False,
+    callback_url="http://localhost:8080",
+    custom_parameters={
+        "custom_param_1": "value_1",
+        "custom_param_2": "value_2"
+    }
+)
+def my_function(access_token: str):
+    # Use access_token here
+    print(f"Access token: {access_token}")
+    # Your business logic
+
+# Call the function
+my_function()
+```
+
+### Using Decorators to Obtain API Keys
+
+```python
+from agent_identity_python_sdk.core.decorators import requires_api_key
+
+@requires_api_key(credential_provider_name="your-provider-name", inject_param_name="api_key")
+def my_function(api_key: str):
+    # Use api_key here
+    print(f"API key: {api_key}")
+    # Your business logic
+
+# Call the function
+my_function()
+```
+
+### Using Decorators to Obtain STS Credentials
+
+```python
+from agent_identity_python_sdk.core.decorators import requires_sts_token
+from agent_identity_python_sdk.model.stscredential import STSCredential
+
+@requires_sts_token(inject_param_name="sts_credential")
+def my_function(sts_credential: STSCredential):
+    # Use sts_credential here
+    print(f"STS Access Key ID: {sts_credential.access_key_id}")
+    # Your business logic
+
+# Call the function
+my_function()
+```
+
+## Core Modules
+
+### IdentityClient
+
+IdentityClient is the core identity management client that provides methods for creating and managing identities and acquiring various types of credentials.
+
+```python
+from agent_identity_python_sdk.core.identity import IdentityClient
+
+client = IdentityClient(region_id="cn-beijing")
+
+# Create workload identity
+workload_identity_name = client.create_workload_identity(
+    workload_identity_name="my-workload",
+    allowed_resource_oauth2_return_urls=["https://example.com/callback"],
+    role_arn="acs:ram::12****:role/example-role",
+)
+
+# Get workload access token
+token = client.get_workload_access_token(
+    workload_name=workload_identity_name,
+    user_token="ejwyJ9***",
+    user_id="example-user"
+) # Prioritizes using user_token to obtain workload access token; if not available, uses user_id to obtain workload access token; if both are absent, obtains workload access token without end-user information
+```
+
+### Context Management
+
+The SDK provides context managers for storing thread/async task isolated data:
+
+#### AgentIdentityContext
+
+Used to manage workload access tokens, user ID, user tokens, session ID, etc. The SDK will read the current thread's context variables to obtain the workload access token when acquiring workload access tokens.
+
+```python
+from agent_identity_python_sdk.context.context import AgentIdentityContext
+
+# Set workload access token
+AgentIdentityContext.set_workload_access_token("your-token")
+
+# Get workload access token
+token = AgentIdentityContext.get_workload_access_token()
+
+# Set user token
+AgentIdentityContext.set_user_token("your-token")
+
+# Set user ID
+AgentIdentityContext.set_user_id("user-123")
+
+# Set custom state
+AgentIdentityContext.set_custom_state("your-state")
+
+# Clear current thread context, needs to be actively cleared at the end of a single session, otherwise permission leakage may occur due to thread sharing
+AgentIdentityContext.clear()
+```
+
+If a workload access token is set in the context, it will be prioritized when acquiring workload access tokens from the current thread context variables.
+
+If no workload access token is set, when the SDK automatically acquires a workload access token, it will retrieve user ID/user token information from the current thread context variables, following the **user token/user ID/none** priority to acquire the workload access token.
+
+If a custom state is set, during OAuth2 authorization, the custom state will be passed along. User applications can use the custom state to handle authorization callbacks and perform verification. It is recommended that applications use custom state for session verification to prevent malicious sharing of authorization links to obtain other users' permissions.
+
+⚠️ **Note**: After the current workflow execution is completed, you need to actively clear the current thread context, otherwise permission leakage may occur due to thread sharing.
+
+## Environment Variables Configuration
+
+| Variable Name | Description | Default Value |
+|---------------|-------------|---------------|
+| AGENT_IDENTITY_REGION_ID | Region identifier | cn-beijing |
+| AGENT_IDENTITY_WORKLOAD_ACCESS_TOKEN | Workload identity token | None |
+| AGENT_IDENTITY_WORKLOAD_IDENTITY_NAME | Workload identity name | None |
+| AGENT_IDENTITY_USE_STS | Whether to use STS for resource credential acquisition | true |
+
+## Contributing
+
+Issues and Pull Requests are welcome to help improve this SDK.
+
+## License
+
+This project is licensed under the Apache-2.0 License. See the [LICENSE](../LICENSE) file for details.

agent_identity_python_sdk-0.1.1/README.md

@@ -0,0 +1,171 @@
+# Agent Identity Python SDK
+
+The Agent Identity Python SDK is a Python development toolkit for accessing Agent Identity services. This SDK provides identity authentication, token management, API key acquisition, and more, supporting both synchronous and asynchronous invocation modes.
+
+## Features
+
+- **OAuth2 Access Token Acquisition**: Supports multiple OAuth2 flows for access token retrieval
+- **API Key Acquisition**: Programmatic API key retrieval
+- **STS Credential Acquisition**: Obtain temporary security token service credentials
+- **Context Management**: Thread-safe context variable management
+- **Caching Mechanism**: Built-in credential caching for improved performance
+- **Decorator Support**: Simplified authentication flow integration via decorators
+- **Concurrency Safety**: Supports multi-threading and asynchronous environments
+
+## Installation
+
+```bash
+pip install agent-identity-python-sdk
+```
+
+## Quick Start
+
+### Basic Configuration
+
+Before using the SDK, ensure you have set the correct environment variables:
+
+```bash
+export AGENT_IDENTITY_REGION_ID="cn-beijing"  # Optional, set your Region ID, default is cn-beijing
+export AGENT_IDENTITY_WORKLOAD_ACCESS_TOKEN="<your-workload-access-token>" # Optional, set your workload access token, if not specified, the Agent Identity service will be automatically called to obtain it
+export AGENT_IDENTITY_WORKLOAD_IDENTITY_NAME="<your-workload-identity-name>" # Optional, set your workload identity name, if specified, the workload identity will be used as the agent's identity, otherwise a random workload identity will be generated
+export AGENT_IDENTITY_USE_STS="true/false" # Optional, set whether to use the agent identity associated role for resource credential acquisition, default is true
+```
+
+### Using Decorators to Automatically Obtain Tokens
+
+```python
+from agent_identity_python_sdk.core import requires_access_token
+
+@requires_access_token(
+    credential_provider_name="your-provider-name",
+    inject_param_name="access_token",
+    auth_flow="USER_FEDERATION",
+    on_auth_url= lambda url: print(f"Please visit {url} to authenticate."),
+    scopes=["openid", "profile", "email"],
+    force_authentication=False,
+    callback_url="http://localhost:8080",
+    custom_parameters={
+        "custom_param_1": "value_1",
+        "custom_param_2": "value_2"
+    }
+)
+def my_function(access_token: str):
+    # Use access_token here
+    print(f"Access token: {access_token}")
+    # Your business logic
+
+# Call the function
+my_function()
+```
+
+### Using Decorators to Obtain API Keys
+
+```python
+from agent_identity_python_sdk.core.decorators import requires_api_key
+
+@requires_api_key(credential_provider_name="your-provider-name", inject_param_name="api_key")
+def my_function(api_key: str):
+    # Use api_key here
+    print(f"API key: {api_key}")
+    # Your business logic
+
+# Call the function
+my_function()
+```
+
+### Using Decorators to Obtain STS Credentials
+
+```python
+from agent_identity_python_sdk.core.decorators import requires_sts_token
+from agent_identity_python_sdk.model.stscredential import STSCredential
+
+@requires_sts_token(inject_param_name="sts_credential")
+def my_function(sts_credential: STSCredential):
+    # Use sts_credential here
+    print(f"STS Access Key ID: {sts_credential.access_key_id}")
+    # Your business logic
+
+# Call the function
+my_function()
+```
+
+## Core Modules
+
+### IdentityClient
+
+IdentityClient is the core identity management client that provides methods for creating and managing identities and acquiring various types of credentials.
+
+```python
+from agent_identity_python_sdk.core.identity import IdentityClient
+
+client = IdentityClient(region_id="cn-beijing")
+
+# Create workload identity
+workload_identity_name = client.create_workload_identity(
+    workload_identity_name="my-workload",
+    allowed_resource_oauth2_return_urls=["https://example.com/callback"],
+    role_arn="acs:ram::12****:role/example-role",
+)
+
+# Get workload access token
+token = client.get_workload_access_token(
+    workload_name=workload_identity_name,
+    user_token="ejwyJ9***",
+    user_id="example-user"
+) # Prioritizes using user_token to obtain workload access token; if not available, uses user_id to obtain workload access token; if both are absent, obtains workload access token without end-user information
+```
+
+### Context Management
+
+The SDK provides context managers for storing thread/async task isolated data:
+
+#### AgentIdentityContext
+
+Used to manage workload access tokens, user ID, user tokens, session ID, etc. The SDK will read the current thread's context variables to obtain the workload access token when acquiring workload access tokens.
+
+```python
+from agent_identity_python_sdk.context.context import AgentIdentityContext
+
+# Set workload access token
+AgentIdentityContext.set_workload_access_token("your-token")
+
+# Get workload access token
+token = AgentIdentityContext.get_workload_access_token()
+
+# Set user token
+AgentIdentityContext.set_user_token("your-token")
+
+# Set user ID
+AgentIdentityContext.set_user_id("user-123")
+
+# Set custom state
+AgentIdentityContext.set_custom_state("your-state")
+
+# Clear current thread context, needs to be actively cleared at the end of a single session, otherwise permission leakage may occur due to thread sharing
+AgentIdentityContext.clear()
+```
+
+If a workload access token is set in the context, it will be prioritized when acquiring workload access tokens from the current thread context variables.
+
+If no workload access token is set, when the SDK automatically acquires a workload access token, it will retrieve user ID/user token information from the current thread context variables, following the **user token/user ID/none** priority to acquire the workload access token.
+
+If a custom state is set, during OAuth2 authorization, the custom state will be passed along. User applications can use the custom state to handle authorization callbacks and perform verification. It is recommended that applications use custom state for session verification to prevent malicious sharing of authorization links to obtain other users' permissions.
+
+⚠️ **Note**: After the current workflow execution is completed, you need to actively clear the current thread context, otherwise permission leakage may occur due to thread sharing.
+
+## Environment Variables Configuration
+
+| Variable Name | Description | Default Value |
+|---------------|-------------|---------------|
+| AGENT_IDENTITY_REGION_ID | Region identifier | cn-beijing |
+| AGENT_IDENTITY_WORKLOAD_ACCESS_TOKEN | Workload identity token | None |
+| AGENT_IDENTITY_WORKLOAD_IDENTITY_NAME | Workload identity name | None |
+| AGENT_IDENTITY_USE_STS | Whether to use STS for resource credential acquisition | true |
+
+## Contributing
+
+Issues and Pull Requests are welcome to help improve this SDK.
+
+## License
+
+This project is licensed under the Apache-2.0 License. See the [LICENSE](../LICENSE) file for details.

agent_identity_python_sdk-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_identity_python_sdk-0.1.1/setup.py

@@ -0,0 +1,45 @@
+from setuptools import setup, find_packages
+
+with open("README.md", encoding="utf-8") as f:
+    long_description = f.read()
+
+setup(
+    name="agent_identity_python_sdk",
+    version="0.1.1",
+    description="Python SDK for using Agent Identity Service",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    license="Apache-2.0",
+    author="shaoheng",
+    author_email="liuyuhao.lyh@alibaba-inc.com",
+    url="https://github.com/aliyun/agent-identity-dev-kit",
+    packages=find_packages(where="src"),
+    package_dir={"": "src"},
+    python_requires=">=3.10",
+    install_requires=[
+        "alibabacloud-agentidentity20250901>=1.0.1",
+        "alibabacloud-agentidentitydata20251127>=1.0.2",
+        "setuptools",
+        "pydantic==2.11.7",
+        "urllib3==2.3.0",
+        "utils==1.0.2",
+    ],
+    extras_require={
+        "dev": [
+            "pytest>=8.4.1",
+            "pytest-asyncio>=0.24.0",
+            "pytest-cov>=6.0.0",
+        ],
+    },
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: Apache Software License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+    ],
+)

agent_identity_python_sdk-0.1.1/src/agent_identity_python_sdk/__init__.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+
+__version__ = "0.1.0"
+
+from .context import AgentIdentityContext
+from .core import requires_access_token, requires_sts_token, requires_api_key
+from .core import IdentityClient
+
+
+__all__ = [
+    "IdentityClient",
+    "requires_access_token",
+    "requires_sts_token",
+    "requires_api_key",
+    "AgentIdentityContext"
+]

agent_identity_python_sdk-0.1.1/src/agent_identity_python_sdk/context/__init__.py

@@ -0,0 +1,6 @@
+"""Agent Identity Runtime Package.
+"""
+
+from .context import AgentIdentityContext
+
+__all__ = ["AgentIdentityContext"]

agent_identity_python_sdk-0.1.1/src/agent_identity_python_sdk/context/context.py

@@ -0,0 +1,106 @@
+import os
+from contextvars import ContextVar
+from typing import Optional
+
+class AgentIdentityContext:
+    """
+    AgentIdentityContext is a context management class used to store user-related information in concurrent environments.
+    It utilizes contextvars to ensure data isolation between threads/asynchronous tasks.
+
+    This class is primarily used to store the following pieces of information:
+    1. user_id: Unique identifier for the user, used to identify the current operating user
+    2. user_token: User access token, used for authentication and authorization
+    3. custom_state: Custom state parameter, used in OAuth2 flow to prevent CSRF attacks and verify request sources during callback
+    4. workload_access_token: Token for accessing workload resources, which can be retrieved from context or environment variable
+    5. session_id: Unique identifier for the session, used to track and manage user sessions
+
+    These pieces of information are isolated within threads, allowing safe usage in asynchronous operations or multi-threaded environments
+    without risk of data confusion.
+    """
+
+    # Session ID context variable, used to pass session identifier within request chain
+    _session_id: ContextVar[Optional[str]] = ContextVar("session_id")
+
+    # User ID context variable, used to pass user id within request chain
+    _user_id: ContextVar[Optional[str]] = ContextVar("user_id")
+
+    # User token context variable, used to pass user token within request chain
+    _user_token: ContextVar[Optional[str]] = ContextVar("user_token")
+
+    # Custom state context variable, used to pass custom state within request chain.
+    # The custom state will be carried when OAuth2 authorization is successful and redirected to the user application.
+    # It is recommended that the user application perform ownership verification of the callback login status and state
+    # to prevent the link from being maliciously disseminated and causing unauthorized access.
+    _custom_state: ContextVar[Optional[str]] = ContextVar("custom_state")
+
+    # Workload access token context variable, used to pass workload authentication token within request chain
+    # The workload access token will be retrieved from this context first, if not present,
+    # it will read from environment variable. This allows the platform to preset the workload
+    # access token to the agent execution environment in certain scenarios. If neither exists,
+    # the Agent Identity SDK will automatically acquire it for the client based on the current context.
+    _workload_access_token: ContextVar[Optional[str]] = ContextVar("workload_access_token")
+
+    @classmethod
+    def set_user_id(cls, user_id: str):
+        # Set the user ID in the context
+        cls._user_id.set(user_id)
+
+    @classmethod
+    def get_user_id(cls) -> Optional[str]:
+        # Get the user ID from context
+        try:
+            return cls._user_id.get()
+        except LookupError:
+            return None
+
+    @classmethod
+    def set_user_token(cls, token: str):
+        # Set the user token in the context
+        cls._user_token.set(token)
+
+    @classmethod
+    def get_user_token(cls) -> Optional[str]:
+        # Get the user token from context
+        try:
+            return cls._user_token.get()
+        except LookupError:
+            return None
+
+    @classmethod
+    def set_custom_state(cls, state: str):
+        # Set the custom state in the context
+        cls._custom_state.set(state)
+
+    @classmethod
+    def get_custom_state(cls) -> Optional[str]:
+        # Get the custom state from context
+        try:
+            return cls._custom_state.get()
+        except LookupError:
+            return None
+
+    @classmethod
+    def set_workload_access_token(cls, token: str):
+        # Set the workload access token in the context
+        cls._workload_access_token.set(token)
+
+    @classmethod
+    def get_workload_access_token(cls) -> Optional[str]:
+        # Get the workload access token from context or environment variable
+        try:
+            workload_access_token = cls._workload_access_token.get()
+            if workload_access_token is None:
+                return os.environ.get("AGENT_IDENTITY_WORKLOAD_ACCESS_TOKEN", None)
+            return workload_access_token  # Return the context value if it's not None
+        except LookupError:
+            return None
+
+    @classmethod
+    def clear(cls):
+        # Clear all context variables
+        cls._session_id.set(None)
+        cls._user_id.set(None)
+        cls._user_token.set(None)
+        cls._custom_state.set(None)
+        cls._workload_access_token.set(None)
+

agent_identity_python_sdk-0.1.1/src/agent_identity_python_sdk/core/__init__.py

@@ -0,0 +1,6 @@
+"""Agent identity core package."""
+
+from .decorators import requires_access_token, requires_api_key, requires_sts_token
+from .identity import IdentityClient
+
+__all__ = ["requires_access_token", "requires_api_key", "requires_sts_token", "IdentityClient"]