Metadata-Version: 2.4
Name: cloud-idaas-akless-alibabacloud-adapter
Version: 0.0.1b0
Summary: Python SDK for IDaaS (Identity as a Service) AKless Adapter - Enables AK-free authentication for Alibaba Cloud services
Author-email: AlibabaCloud IDaaS Team <cloudidaas@list.alibaba-inc.com>
License: Apache-2.0
Keywords: IDaaS,IDaaS SDK
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cloud-idaas-core>=0.0.5b0
Requires-Dist: alibabacloud-credentials>=1.0.0
Requires-Dist: oss2>=2.18.0
Requires-Dist: alibabacloud-oss-v2>=1.0.0
Requires-Dist: aliyun-log-python-sdk>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
Dynamic: license-file

# cloud-idaas-akless-alibabacloud-adapter

[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
[![Development Status](https://img.shields.io/badge/status-Beta-orange)](https://pypi.org/project/cloud-idaas-akless-alibabacloud-adapter/)
[![Version](https://img.shields.io/badge/version-0.0.1b0-blue)](https://pypi.org/project/cloud-idaas-akless-alibabacloud-adapter/)

[简体中文](README_zh.md) | English

Python SDK for IDaaS (Identity as a Service) AKless Adapter — Enables AK-free authentication for Alibaba Cloud services using IDaaS PAM (Privileged Access Management) to obtain STS temporary credentials.

## Features

- **AK-free Authentication**: Eliminates the need for long-term AccessKey, uses OIDC Token to obtain STS temporary credentials via IDaaS PAM, reducing the risk of credential leakage
- **Multi-SDK Adaptation**: Provides credential provider adapters for multiple Alibaba Cloud SDKs, including OSS V1, OSS V2, and SLS
- **Automatic Credential Refresh**: Built-in credential caching and automatic refresh based on expiration time, ensuring seamless credential rotation
- **Simple Integration**: Factory class provides one-line creation of credential providers, minimizing integration effort

## Requirements

- Python >= 3.9
- Dependencies:
  - cloud-idaas-core >= 0.0.5b0
  - alibabacloud-credentials >= 1.0.0
  - oss2 >= 2.18.0
  - alibabacloud-oss-v2 >= 1.0.0
  - aliyun-log-python-sdk >= 0.9.0

## Installation

```bash
pip install cloud-idaas-akless-alibabacloud-adapter
```

## Prerequisites

This SDK depends on [cloud-idaas-core](https://pypi.org/project/cloud-idaas-core/). You need to complete the IDaaS Core SDK initialization before using this adapter.

1. Install and configure `cloud-idaas-core`, refer to [cloud-idaas-core README](https://github.com/aliyunidaas-lab/idaas-python-core-sdk/blob/main/README.md) for details.

2. In the configuration file, set the `scope` to the IDaaS built-in scope for PAM:

   ```json
   {
       "scope": "urn:cloud:idaas:pam|.all"
   }
   ```

3. Complete the IDaaS Core SDK initialization:

   ```python
   from cloud_idaas.core import IDaaSCredentialProviderFactory

   IDaaSCredentialProviderFactory.init()
   ```

## Quick Start

The simplest way to use this SDK is through the `IDaaSPamAklessCredentialFactory` factory class:

```python
from cloud_idaas.core import IDaaSCredentialProviderFactory
from cloud_idaas.adapter.alibabacloud.pam import IDaaSPamAklessCredentialFactory

# 1. Initialize IDaaS Core SDK
IDaaSCredentialProviderFactory.init()

# 2. Create an Alibaba Cloud credentials provider
credentials_provider = IDaaSPamAklessCredentialFactory.get_alibaba_cloud_credentials_provider(
    role_arn="acs:ram::123456789:role/your-role-name"
)

# 3. Get credentials
credentials = credentials_provider.get_credentials()
print(credentials.access_key_id)
print(credentials.access_key_secret)
print(credentials.security_token)
```

> **Note**: The `role_arn` parameter can also be configured via the environment variable `ALIBABA_CLOUD_ROLE_ARN`.

## Usage Examples

### OSS V1 (oss2)

```python
import oss2
from cloud_idaas.core import IDaaSCredentialProviderFactory
from cloud_idaas.adapter.alibabacloud.pam import IDaaSPamAklessCredentialFactory

# Initialize
IDaaSCredentialProviderFactory.init()

# Create OSS V1 credentials provider
oss_v1_provider = IDaaSPamAklessCredentialFactory.get_oss_v1_credential_provider(
    role_arn="acs:ram::123456789:role/your-role-name"
)

# Use with OSS V1 SDK
auth = oss2.ProviderAuthV4(oss_v1_provider)
bucket = oss2.Bucket(auth, "https://oss-cn-hangzhou.aliyuncs.com", "your-bucket-name")
```

### OSS V2 (alibabacloud-oss-v2)

```python
import alibabacloud_oss_v2 as oss
from cloud_idaas.core import IDaaSCredentialProviderFactory
from cloud_idaas.adapter.alibabacloud.pam import IDaaSPamAklessCredentialFactory

# Initialize
IDaaSCredentialProviderFactory.init()

# Create OSS V2 credentials provider
oss_v2_provider = IDaaSPamAklessCredentialFactory.get_oss_v2_credential_provider(
    role_arn="acs:ram::123456789:role/your-role-name"
)

# Use with OSS V2 SDK
cfg = oss.config.load_default()
cfg.credentials_provider = oss_v2_provider
cfg.region = "cn-hangzhou"
client = oss.Client(cfg)
```

### SLS (aliyun-log-python-sdk)

```python
from aliyun.log import LogClient
from cloud_idaas.core import IDaaSCredentialProviderFactory
from cloud_idaas.adapter.alibabacloud.pam import IDaaSPamAklessCredentialFactory

# Initialize
IDaaSCredentialProviderFactory.init()

# Create SLS credentials provider
sls_provider = IDaaSPamAklessCredentialFactory.get_sls_credential_provider(
    role_arn="acs:ram::123456789:role/your-role-name"
)

# Use with SLS SDK
client = LogClient("cn-hangzhou.log.aliyuncs.com", credentials_provider=sls_provider)
```

## API Reference

### IDaaSPamAklessCredentialFactory

Factory class providing static methods to create credential providers.

| Method | Return Type | Description |
|--------|-------------|-------------|
| `get_alibaba_cloud_credentials_provider(role_arn=None)` | `IDaaSPamAlibabaCloudCredentialsProvider` | Creates a general Alibaba Cloud credentials provider |
| `get_oss_v1_credential_provider(role_arn=None)` | `IDaaSPamOSSV1CredentialsProvider` | Creates an OSS V1 SDK credentials provider |
| `get_oss_v2_credential_provider(role_arn=None)` | `IDaaSPamOSSV2CredentialsProvider` | Creates an OSS V2 SDK credentials provider |
| `get_sls_credential_provider(role_arn=None)` | `IDaaSPamSLSCredentialsProvider` | Creates an SLS SDK credentials provider |

### IDaaSPamAlibabaCloudCredentialsProvider

Core credentials provider that obtains STS temporary credentials from PAM API using OIDC Token.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| developer_api_endpoint | str | Yes | - | PAM Developer API endpoint |
| idaas_instance_id | str | Yes | - | IDaaS instance ID |
| role_arn | str | No | Env `ALIBABA_CLOUD_ROLE_ARN` | RAM role ARN to assume |
| duration_seconds | int | No | 3600 | Session duration in seconds (minimum 900) |
| connect_timeout | int | No | 5000 | Connection timeout in milliseconds |
| read_timeout | int | No | 10000 | Read timeout in milliseconds |

### Environment Variables

| Variable | Description |
|----------|-------------|
| `ALIBABA_CLOUD_ROLE_ARN` | RAM role ARN. Used when `role_arn` is not explicitly provided |
| `ALIBABA_CLOUD_OIDC_TOKEN_FILE` | Path to the OIDC Token file. Used for OIDC Token provider |

## Support and Feedback

- **Email**: cloudidaas@list.alibaba-inc.com
- **Issues**: Please submit an Issue for questions or suggestions

## License

This project is licensed under the [Apache License 2.0](LICENSE).
