如何為OSS Python SDK配置訪問憑證 - Object Storage Service

使用Python SDK發起OSS請求，您需要配置訪問憑證。阿里雲服務會通過訪問憑證驗證您的身份資訊和存取權限。您可以根據使用情境對認證和授權的要求，選擇不同類型的訪問憑證。

前提條件

在配置訪問憑證前，您需要安裝OSS Python SDK。詳情請參見安裝。

初始化憑證提供者

憑證提供者選型

OSS支援多種方式初始化憑證提供者，您可以根據使用情境對認證和授權的要求，選擇對應的方式初始化憑證提供者。

憑證提供者初始化方式	適用情境	是否需要提供前置的AK或STS Token	底層實現基於的憑證	憑證有效期間	憑證輪轉或重新整理方式
方式一：使用AK	部署運行在安全、穩定且不易受外部攻擊的環境的應用程式，無需頻繁輪轉憑證就可以長期訪問雲端服務	是	AK	長期	手動輪轉
方式二：使用自動輪轉的AK	部署運行在面臨AK泄露風險的環境的應用程式，需要頻繁輪轉憑證才長期能訪問雲端服務	否	AK	長期	自動輪轉
方式三：使用STS Token	部署運行在不可信的環境的應用程式，希望能控制訪問的有效期間、許可權	是	STS Token	臨時	手動重新整理
方式四：使用RAMRoleARN	需要授權訪問雲端服務，例如跨阿里雲帳號訪問雲端服務的應用程式	是	STS Token	臨時	自動重新整理
方式五：使用ECSRAMRole	部署運行在阿里雲的ECS執行個體、ECI執行個體、Container ServiceKubernetes版的Worker節點中的應用程式	否	STS Token	臨時	自動重新整理
方式六：使用OIDCRoleARN	部署運行在阿里雲的Container ServiceKubernetes版的Worker節點中的不可信應用程式	否	STS Token	臨時	自動重新整理
方式七：使用Function Compute上下文中的Credentials	部署運行在阿里雲Function Compute中的應用程式的函數	否	STS Token	臨時	無需重新整理
方式八：使用CredentialsURI	需要通過外部系統擷取訪問憑證的應用程式	否	STS Token	臨時	自動重新整理
方式九：使用自訂訪問憑證	如果以上憑證配置方式都不滿足要求時，您可以自訂擷取憑證的方式	自訂	自訂	自訂	自訂

方式一：使用AK

如果您的應用程式部署運行在安全、穩定且不易受外部攻擊的環境中，需要長期訪問您的OSS，且不能頻繁輪轉憑證時，您可以使用阿里雲主帳號或RAM使用者的AK（Access Key ID、Access Key Secret）初始化憑證提供者。需要注意的是，該方式需要您手動維護一個AK，存在安全性風險和維護複雜度增加的風險。如何擷取AK，請參見CreateAccessKey - 建立主帳號或RAM使用者存取金鑰。

環境變數

警告

阿里雲帳號擁有資源的全部許可權，AK一旦泄露，會給系統帶來巨大風險，不建議使用。推薦使用最小化授權的RAM使用者的AK。

使用AK設定環境變數。

Mac OS X/Linux/Unix

export OSS_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID>
export OSS_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>

Windows

set OSS_ACCESS_KEY_ID <ALIBABA_CLOUD_ACCESS_KEY_ID>
set OSS_ACCESS_KEY_SECRET <ALIBABA_CLOUD_ACCESS_KEY_SECRET>

使用環境變數來傳遞憑證資訊。

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 使用環境變數中擷取的RAM使用者存取金鑰配置訪問憑證
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 使用auth進行後續操作...

靜態憑證

您可以在代碼中使用變數來引用憑證，這些變數在運行時會被環境變數、設定檔或其他外部資料源中的實際憑證值填充。

以下操作步驟以設定檔為例。

建立設定檔config.ini。

[configName]
alibaba_cloud_access_key_id = <ALIBABA_CLOUD_ACCESS_KEY_ID>
alibaba_cloud_access_key_secret = <ALIBABA_CLOUD_ACCESS_KEY_SECRET>

使用設定檔來傳遞憑證資訊。

# -*- coding: utf-8 -*-
import oss2
import configparser

# 讀取設定檔
config = configparser.ConfigParser()
# 假設config.ini位於指令碼同級目錄下
config.read('config.ini')

# 從設定檔中擷取Access Key ID和Access Key Secret
access_key_id = config.get('configName', 'alibaba_cloud_access_key_id')
access_key_secret = config.get('configName', 'alibaba_cloud_access_key_secret')

# 使用擷取的RAM使用者的存取金鑰配置訪問憑證
auth = oss2.AuthV4(access_key_id, access_key_secret)

# 使用auth進行後續操作...

方式二：使用自動輪轉的AK

如果您的應用程式需要長期訪問您的OSS，但部署啟動並執行環境面臨AK泄露的風險，需要頻繁手動輪轉（輪換）AK，您可以使用ClientKey初始化憑證提供者。該方式底層實現是AK。使用ClientKey後，Key Management Service（KMS）可以對託管的RAM使用者AK進行全自動的定期輪轉，將靜態RAM使用者AK動態化，從而降低AK泄漏的風險。除定期輪轉外，KMS還支援立即輪轉，在AK泄漏情況下快速更換AK。該方式無需您手動維護一個AK，從而降低安全性風險和維護複雜度增加的風險。如何擷取ClientKey，請參見建立應用存取點。

添加憑據用戶端依賴。

pip install aliyun-secret-manager-client

建立設定檔secretsmanager.properties。

# 訪問憑據類型，固定為client_key
credentials_type=client_key

# 讀取Client Key的解密密碼：支援從環境變數或者檔案讀取，只需設定一種
client_key_password_from_env_variable=<your client key private key password environment variable name>
client_key_password_from_file_path=<your client key private key password file path>

# Client Key的私密金鑰檔案路徑
client_key_private_key_path=<your client key private key file path>

# 關聯的KMS服務地區
cache_client_region_id=[{"regionId":"<regionId>"}]

使用設定檔來傳遞憑證資訊。

# -*- coding: utf-8 -*-
import json
import oss2
from oss2 import CredentialsProvider
from oss2.credentials import Credentials
from alibaba_cloud_secretsmanager_client.secret_manager_cache_client_builder import SecretManagerCacheClientBuilder


class CredentialProviderWrapper(CredentialsProvider):
    def get_credentials(self):
        secret_cache_client = SecretManagerCacheClientBuilder.new_client()
        secret_info = secret_cache_client.get_secret_info("<secretName>")
        secret_value_json = json.loads(secret_info.secret_value)
        return Credentials(secret_value_json["AccessKeyId"], secret_value_json["AccessKeySecret"])


credentials_provider = CredentialProviderWrapper()

auth = oss2.ProviderAuthV4(credentials_provider)

# 使用auth進行後續操作...

方式三：使用STS Token

如果您的應用程式需要臨時訪問OSS，細化存取控制，即時調整許可權，以提高安全性和靈活性，您可以使用通過STS服務擷取的臨時身份憑證（Access Key ID、Access Key Secret和Security Token）初始化憑證提供者。需要注意的是，該方式需要您手動維護一個STS Token，存在安全性風險和維護複雜度增加的風險。如何擷取STS Token，請參見AssumeRole - 擷取扮演角色的臨時身份憑證。

環境變數

使用臨時身份憑證設定環境變數。

Mac OS X/Linux/Unix

export OSS_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID>
export OSS_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>
export OSS_SESSION_TOKEN=<ALIBABA_CLOUD_SECURITY_TOKEN>

Windows

set OSS_ACCESS_KEY_ID <ALIBABA_CLOUD_ACCESS_KEY_ID>
set OSS_ACCESS_KEY_SECRET <ALIBABA_CLOUD_ACCESS_KEY_SECRET>
set OSS_SESSION_TOKEN <ALIBABA_CLOUD_SECURITY_TOKEN>

通過環境變數來傳遞憑證資訊。

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# 使用環境變數中擷取的STS Token配置訪問憑證
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 使用auth進行後續操作...

靜態憑證

您可以在代碼中使用變數來引用憑證，這些變數在運行時會被環境變數、設定檔或其他外部資料源中的實際憑證值填充。

以下操作步驟以設定檔為例。

建立設定檔config.ini。

[configName]
alibaba_cloud_access_key_id = <ALIBABA_CLOUD_ACCESS_KEY_ID>
alibaba_cloud_access_key_secret = <ALIBABA_CLOUD_ACCESS_KEY_SECRET>
alibaba_cloud_security_token = <ALIBABA_CLOUD_SECURITY_TOKEN>

使用設定檔來傳遞憑證資訊。

# -*- coding: utf-8 -*-
import oss2
import configparser

# 讀取設定檔
config = configparser.ConfigParser()
# 假設config.ini位於指令碼同級目錄下
config.read('config.ini')

# 從設定檔中擷取臨時AccessKeyId、臨時AccessKeySecret和SecurityToken
access_key_id = config.get('configName', 'alibaba_cloud_access_key_id')
access_key_secret = config.get('configName', 'alibaba_cloud_access_key_secret')
security_token = config.get('configName', 'alibaba_cloud_security_token')

# 使用臨時訪問憑證中的認證資訊初始化StsAuth執行個體
auth = oss2.StsAuth(access_key_id, access_key_secret, security_token).auth_version('v4')

# 使用auth進行後續操作...

方式四：使用RAMRoleARN

如果您的應用程式需要跨阿里雲帳號訪問OSS，通過扮演RAM角色的方式進行許可權管理，以確保安全性和靈活性，您可以使用RAMRoleARN初始化憑證提供者。該方式底層實現是STS Token。通過指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具會前往STS服務擷取STS Token，並在會話到期前自動重新整理STS Token。此外，您還可以通過為policy賦值來限制RAM角色到一個更小的許可權集合。需要注意的是，該方式需要您提供一個AK或STS Token，存在安全性風險和維護複雜度增加的風險。如何擷取AK或STS Token，請參見CreateAccessKey - 為RAM使用者建立存取金鑰或AssumeRole - 擷取扮演角色的臨時身份憑證。如何擷取RAMRoleARN，請參見CreateRole - 建立角色。

AK和RAMRoleARN

添加alibabacloud_credentials依賴。
```
pip install alibabacloud_credentials
```

配置AK和RAMRoleARN作為訪問憑證。

# -*- coding: utf-8 -*-
import oss2
from alibabacloud_credentials.client import Client
from alibabacloud_credentials.models import Config
from oss2 import CredentialsProvider
from oss2.credentials import Credentials
import os


class CredentialProviderWrapper(CredentialsProvider):
    def __init__(self, client, config):
        self.client = client
        self.config = config

    def get_credentials(self):
        credential = self.client.get_credential(self.config)
        access_key_id = credential.access_key_id
        access_key_secret = credential.access_key_secret
        security_token = credential.security_token
        return Credentials(access_key_id, access_key_secret, security_token)


config = Config(
    # 從環境變數中擷取RAM使用者的存取金鑰（AccessKey ID和AccessKey Secret）
    access_key_id=os.getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    access_key_secret=os.getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
    type='ram_role_arn',
    # 要扮演的RAM角色ARN，樣本值：acs:ram::123456789012****:role/adminrole，可以通過環境變數ALIBABA_CLOUD_ROLE_ARN設定RoleArn
    role_arn='<RoleArn>',
    # 角色會話名稱，可以通過環境變數ALIBABA_CLOUD_ROLE_SESSION_NAME設定RoleSessionName
    role_session_name='<RoleSessionName>',
    # 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    policy='<Policy>',
    # 設定角色會話有效期間，非必填
    role_session_expiration=3600
)


cred = Client(config)

credentials_provider = CredentialProviderWrapper(cred, config)

auth = oss2.ProviderAuthV4(credentials_provider)

# 使用auth進行後續操作...

STS Token和RAMRoleARN

添加alibabacloud_credentials依賴。
```
pip install alibabacloud_credentials
```

配置STS Token和RAMRoleARN作為訪問憑證。

# -*- coding: utf-8 -*-
import oss2
from alibabacloud_credentials.client import Client
from alibabacloud_credentials.models import Config
from oss2 import CredentialsProvider
from oss2.credentials import Credentials
import os


class CredentialProviderWrapper(CredentialsProvider):
    def __init__(self, client, config):
        self.client = client
        self.config = config

    def get_credentials(self):
        credential = self.client.get_credential(self.config)
        access_key_id = credential.access_key_id
        access_key_secret = credential.access_key_secret
        security_token = credential.security_token
        return Credentials(access_key_id, access_key_secret, security_token)


config = Config(
    # 從環境變數中擷取的臨時身份憑證（Access Key ID、Access Key Secret和Security Token）
    access_key_id=os.getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    access_key_secret=os.getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
    security_token=os.getenv('<ALIBABA_CLOUD_SECURITY_TOKEN>'),
    type='RAM_role_arn',
    # 要扮演的RAM角色ARN，樣本值：acs:ram::123456789012****:role/adminrole，可以通過環境變數ALIBABA_CLOUD_ROLE_ARN設定RoleArn
    role_arn='<RoleArn>',
    # 角色會話名稱，可以通過環境變數ALIBABA_CLOUD_ROLE_SESSION_NAME設定RoleSessionName
    role_session_name='<RoleSessionName>',
    # 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    policy='<Policy>',
    # 設定角色會話有效期間，非必填
    role_session_expiration=3600
)


cred = Client(config)

credentials_provider = CredentialProviderWrapper(cred, config)

auth = oss2.ProviderAuthV4(credentials_provider)

# 使用auth進行後續操作...

方式五：使用ECSRAMRole

如果您的應用程式運行在ECS執行個體、ECI執行個體、Container ServiceKubernetes版的Worker節點中，建議您使用ECSRAMRole初始化憑證提供者。該方式底層實現是STS Token。ECSRAMRole允許您將一個角色關聯到ECS執行個體、ECI執行個體或Container Service Kubernetes 版的Worker節點，實現在執行個體內部自動重新整理STS Token。該方式無需您提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。如何擷取ECSRAMRole，請參見CreateRole - 建立角色。

添加alibabacloud_credentials依賴。
```
pip install alibabacloud_credentials
```

配置ECSRAMRole作為訪問憑證。

# -*- coding: utf-8 -*-
import oss2
from alibabacloud_credentials.client import Client
from alibabacloud_credentials.models import Config
from oss2 import CredentialsProvider
from oss2.credentials import Credentials


class CredentialProviderWrapper(CredentialsProvider):
    def __init__(self, client, config):
        self.client = client
        self.config = config

    def get_credentials(self):
        credential = self.client.get_credential(self.config)
        access_key_id = credential.access_key_id
        access_key_secret = credential.access_key_secret
        security_token = credential.security_token
        return Credentials(access_key_id, access_key_secret, security_token)


config = Config(
    type='ecs_ram_role',      # 訪問憑證類型。固定為ecs_ram_role。
    role_name='<RoleName>'    # 為ECS授予的RAM角色的名稱。選擇性參數。如果不設定，將自動檢索。強烈建議設定，以減少請求。
)


cred = Client(config)

credentials_provider = CredentialProviderWrapper(cred, config)

auth = oss2.ProviderAuthV4(credentials_provider)

# 使用auth進行後續操作...

方式六：使用OIDCRoleARN

在Container ServiceKubernetes版中設定了Worker節點RAM角色後，對應節點內的Pod中的應用也就可以像ECS上部署的應用一樣，通過中繼資料服務（Meta Data Server）擷取關聯角色的STS Token。但如果容器叢集上部署的是不可信的應用（比如部署您的客戶提交的應用，代碼也沒有對您開放），您可能並不希望它們能通過中繼資料服務擷取Worker節點關聯執行個體RAM角色的STS Token。為了避免影響雲上資源的安全，同時又能讓這些不可信的應用安全地擷取所需的STS Token，實現應用層級的許可權最小化，您可以使用RRSA（RAM Roles for Service Account）功能。該方式底層實現是STS Token。阿里雲容器叢集會為不同的應用Pod建立和掛載相應的服務賬戶OIDC Token檔案，並將相關配置資訊注入到環境變數中，Credentials工具通過擷取環境變數的配置資訊，調用STS服務的AssumeRoleWithOIDC介面換取綁定角色的STS Token。該方式無需您提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。詳情請參見通過RRSA配置ServiceAccount的RAM許可權實現Pod許可權隔離。

添加alibabacloud_credentials依賴。
```
pip install alibabacloud_credentials
```

配置OIDCRoleArn作為訪問憑證。

# -*- coding: utf-8 -*-
import oss2
from alibabacloud_credentials.client import Client
from alibabacloud_credentials.models import Config
from oss2 import CredentialsProvider
from oss2.credentials import Credentials
import os


class CredentialProviderWrapper(CredentialsProvider):
    def __init__(self, client, config):
        self.client = client
        self.config = config

    def get_credentials(self):
        credential = self.client.get_credential(self.config)
        access_key_id = credential.access_key_id
        access_key_secret = credential.access_key_secret
        security_token = credential.security_token
        return Credentials(access_key_id, access_key_secret, security_token)


config = Config(
    # 指定Credential類型，固定值為oidc_role_arn。
    type='oidc_role_arn',
    # RAM角色名稱ARN，可以通過環境變數ALIBABA_CLOUD_ROLE_ARN設定RoleArn
    role_arn=os.environ.get('<RoleArn>'),
    # OIDC供應商ARN，可以通過環境變數ALIBABA_CLOUD_OIDC_PROVIDER_ARN設定OidcProviderArn
    oidc_provider_arn=os.environ.get('<OidcProviderArn>'),
    # OIDC Token檔案路徑，可以通過環境變數ALIBABA_CLOUD_OIDC_TOKEN_FILE設定OidcTokenFilePath
    oidc_token_file_path=os.environ.get('<OidcTokenFilePath>'),
    # 角色會話名稱，可以通過環境變數ALIBABA_CLOUD_ROLE_SESSION_NAME設定RoleSessionName
    role_session_name='<RoleSessionName>',
    # 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    policy='<Policy>',
    # 設定session到期時間
    role_session_expiration=3600
)


cred = Client(config)

credentials_provider = CredentialProviderWrapper(cred, config)

auth = oss2.ProviderAuthV4(credentials_provider)

# 使用auth進行後續操作...

方式七：使用Function Compute上下文中的Credentials

如果您的應用程式的函數部署運行在Function Compute中，您可以使用Function Compute上下文中的Credentials初始化憑證提供者。該方式底層實現是STS Token。Function Compute根據函數配置的角色，通過扮演服務角色，而擷取一個STS Token，然後通過上下文中的參數Credentials將STS Token傳遞給您的應用程式。該STS Token的有效期間為36小時，且不支援修改。函數的最大執行時間為24小時，因此，執行函數過程中，STS Token不會到期，您無需考慮重新整理問題。該方式無需您提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。如何授予Function Compute訪問OSS的許可權，請參見授予Function Compute訪問其他雲端服務的許可權。

使用Function Compute上下文中的Credentials初始化憑證提供者。

# -*- coding: utf-8 -*-
import oss2
from oss2 import CredentialsProvider
from oss2.credentials import Credentials


def handler(event, context):

    class CredentialProviderWrapper(CredentialsProvider):
        def get_credentials(self):
            creds = context.credentials
            return Credentials(creds.access_key_id, creds.access_key_secret, creds.security_token)

    credentials_provider = CredentialProviderWrapper()
    auth = oss2.ProviderAuthV4(credentials_provider)
    # 使用auth進行後續操作...

    return 'success'

方式八：使用CredentialsURI

如果您的應用程式需要通過外部系統擷取阿里雲憑證，從而實現靈活的憑證管理和無密鑰訪問，您可以使用CredentialsURI初始化憑證提供者。該方式底層實現是STS Token。Credentials工具通過您提供的URI擷取STS Token，完成憑證用戶端初始化。該方式無需您提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。需要注意的是，提供CredentialsURI響應的後端服務需要實現STS Token的自動重新整理邏輯，確保您的應用程式始終能擷取到有效憑證。

為了使Credentials工具正確解析和使用STS Token，URI必須遵循以下響應協議：

響應狀態代碼：200

響應體結構：

{
    "Code": "Success",
    "AccessKeySecret": "AccessKeySecret",
    "AccessKeyId": "AccessKeyId",
    "Expiration": "2021-09-26T03:46:38Z",
    "SecurityToken": "SecurityToken"
}

添加alibabacloud_credentials依賴。
```
pip install alibabacloud_credentials
```

配置URI憑證作為訪問憑證。

# -*- coding: utf-8 -*-
import oss2
from alibabacloud_credentials.client import Client
from alibabacloud_credentials.models import Config
from oss2 import CredentialsProvider
from oss2.credentials import Credentials


class CredentialProviderWrapper(CredentialsProvider):
    def __init__(self, client, config):
        self.client = client
        self.config = config

    def get_credentials(self):
        credential = self.client.get_credential(self.config)
        access_key_id = credential.access_key_id
        access_key_secret = credential.access_key_secret
        security_token = credential.security_token
        return Credentials(access_key_id, access_key_secret, security_token)


config = Config(
	type='credentials_uri',
	" commenttypeid="40" timestamp="2024-08-02T10:22:56+08:00" authorid="23918" uuid="5c1e4a9e-c0c0-41aa-a6ea-36f6709ff91c"># 憑證的 URI，格式為http://local_or_remote_uri/，可以通過環境變數ALIBABA_CLOUD_CREDENTIALS_URI設定CredentialsUri
	credentials_uri='<CredentialsUri>',
)


cred = Client(config)

credentials_provider = CredentialProviderWrapper(cred, config)

auth = oss2.ProviderAuthV4(credentials_provider)

# 使用auth進行後續操作...

方式九：使用自訂訪問憑證

如果以上憑證配置方式都不滿足要求時，您還可以通過實現Credential Providers介面的方式，來自訂憑證提供方式。需要注意，如果底層實現是STS Token，需要提供憑證的更新支援。

# -*- coding: utf-8 -*-
import oss2
from oss2 import CredentialsProvider
from oss2.credentials import Credentials


class CredentialProviderWrapper(CredentialsProvider):
    def get_credentials(self):
        # TODO
        # 自訂訪問憑證的擷取方法

        # 返回長期憑證access_key_id, access_key_secrect
        return Credentials('<access_key_id>', '<access_key_secrect>')

        # 返回 臨時憑證access_key_id, access_key_secrect, token
        # 對於臨時憑證，需要根據到期時間，重新整理憑證。
        # return Credentials('<access_key_id>', '<access_key_secrect>', '<token>');


credentials_provider = CredentialProviderWrapper()


auth = oss2.ProviderAuthV4(credentials_provider)

# 使用auth進行後續操作...

後續步驟

配置訪問憑證後，您需要初始化OSSClient。詳情請參見初始化。