Object Storage Service:How to configure access credentials for OSS SDK for Python

Select a credential provider

OSS supports multiple methods to initialize a credential provider. You can select a suitable method based on the authentication and authorization requirements of your actual scenario.

Method 1: Use an AccessKey pair

If your application is deployed in a secure and stable environment that is not vulnerable to external attacks and requires long-term access to OSS, you can use an AccessKey pair of your Alibaba Cloud account or a RAM user to initialize a credential provider. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. Take note that this method requires you to manually maintain an AccessKey pair. This poses security risks and increases maintenance complexity. For more information about how to obtain an AccessKey pair, see CreateAccessKey.

Environment variables

1. Use the AccessKey pair to specify environment variables.

   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>

2. Use environment variables to pass credentials.

   # -*- coding: utf-8 -*-
   import oss2
   from oss2.credentials import EnvironmentVariableCredentialsProvider
   
   # Use the AccessKey pair of the RAM user obtained from the environment variables to configure the access credentials.
   auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
   
   # Use auth for subsequent operations.
   

Static credentials

You can use credentials by specifying variables in your code. In a runtime environment, the variables may be passed by actual credential values from environment variables, configuration files, or other external data sources.

The following procedure describes how to use a configuration file to pass credentials.

1. Create a configuration file named config.ini.

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

2. Use the configuration file to pass credentials.

   # -*- coding: utf-8 -*-
   import oss2
   import configparser
   
   # Read the configuration file.
   config = configparser.ConfigParser()
   # For example, the config.ini configuration file is stored in the same directory as the script.
   config.read('config.ini')
   
   # Obtain the AccessKey ID and AccessKey secret from the configuration file.
   access_key_id = config.get('configName', 'alibaba_cloud_access_key_id')
   access_key_secret = config.get('configName', 'alibaba_cloud_access_key_secret')
   
   # Use the AccessKey pair of the RAM user to configure the access credentials.
   auth = oss2.AuthV4(access_key_id, access_key_secret)
   
   # Use auth for subsequent operations.
   

Method 2: Use an AccessKey pair that automatically rotates

If your application needs to access OSS for a long period of time, but the runtime environment faces the risk of AccessKey pair leaks, you need to manually rotate the AccessKey pair. In this case, you can use a client key to initialize the credential provider. The underlying logic of this method is to use an AccessKey pair to access OSS resources. After you use a client key, Key Management Service (KMS) can automatically and regularly rotate the AccessKey pair of a managed RAM user and dynamically change the static AccessKey pair of a RAM user. This reduces the risk of AccessKey pair leaks. KMS also supports immediate rotation to quickly replace a leaked AccessKey pair. This eliminates the need to manually maintain an AccessKey pair and reduces security risks and maintenance complexity. For more information about how to obtain a client key, see Create an AAP.

1. Add credential dependencies to the client.

   pip install aliyun-secret-manager-client

2. Create a configuration file named secretsmanager.properties.

   # Set the credential type to client_key.
   credentials_type=client_key
   
   # Specify the decryption password of the client key. You can obtain the decryption password from environment variables or the configuration file.
   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>
   
   # Specify the path of the private key file of the client key.
   client_key_private_key_path=<your client key private key file path>
   
   # Specify the ID of the region in which you want to use KMS.
   cache_client_region_id=[{"regionId":"<regionId>"}]

3. Use the configuration file to pass credentials.

   # -*- 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)
   
   # Use auth for subsequent operations.
   

Method 3: Use a security token

If your application needs to access OSS temporarily and manage access control in a fine-grained manner in real time to improve data security and flexibility, you can use temporary access credentials, which consist of an AccessKey pair and a security token, obtained from Security Token Service (STS) to initialize a credential provider. Take note that this method requires you to manually maintain a security token. This poses security risks and increases maintenance complexity. For more information about how to obtain a security token, see AssumeRole.

Environment variables

1. Use temporary access credentials to specify environment variables.

   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>

2. Specify environment variables to pass temporary access credentials.

   # -*- coding: utf-8 -*-
   import oss2
   from oss2.credentials import EnvironmentVariableCredentialsProvider
   
   # Use the security token obtained from the environment variable to configure the access credentials.
   auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
   
   # Use auth for subsequent operations.
   

Static credentials

You can use credentials by specifying variables in your code. In a runtime environment, the variables may be passed by actual credential values from environment variables, configuration files, or other external data sources.

The following procedure describes how to use a configuration file to pass credentials.

1. Create a configuration file named 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>

2. Use the configuration file to pass credentials.

   # -*- coding: utf-8 -*-
   import oss2
   import configparser
   
   # Read the configuration file.
   config = configparser.ConfigParser()
   # For example, the config.ini configuration file is stored in the same directory as the script.
   config.read('config.ini')
   
   # Obtain the temporary AccessKey pair and security token from the configuration file.
   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')
   
   # Initialize the StsAuth instance with the authentication information in the temporary access credentials.
   auth = oss2.StsAuth(access_key_id, access_key_secret, security_token).auth_version('v4')
   
   # Use auth for subsequent operations.
   

Method 4: Use RAMRoleARN

If your application needs to be authorized to access the OSS resources of another Alibaba Cloud account and assume a RAM role to ensure data security and flexibility, you can use RAMRoleARN to initialize a credential provider. The underlying logic of this method is to use a security token obtained from STS to configure access credentials. By specifying the Alibaba Cloud Resource Name (ARN) of a RAM role, the Credentials tool obtains the security token from STS and automatically refreshes the security token before the session expires. You can assign a value to the policy parameter to limit the RAM role permissions. Take note that this method requires you to manually provide an AccessKey pair and a security token. This poses security risks and increases maintenance complexity. For more information about how to obtain an AccessKey pair or a security token, see CreateAccessKey or AssumeRole. For more information about how to obtain the RAM role ARN, see CreateRole.

AccessKey pair and RAMRoleARN

1. Add the alibabacloud_credentials dependency.

   pip install alibabacloud_credentials

2. Configure the AccessKey pair and RAMRoleARN as access credentials.

   # -*- 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):
           self.client = client
   
       def get_credentials(self):
           credential = self.client.get_credential()
           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(
       # Obtain the AccessKey pair (AccessKey ID and AccessKey secret) of the RAM user from environment variables.
       access_key_id=os.getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
       access_key_secret=os.getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
       type='ram_role_arn',
       # Specify the ARN of the RAM role that you want your application to assume by specifying the ALIBABA_CLOUD_ROLE_ARN environment variable. Example: acs:ram::123456789012****:role/adminrole.
       role_arn='<RoleArn>',
       # Specify the role session name by specifying the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
       role_session_name='<RoleSessionName>',
       # Optional. Specify limited permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
       policy='<Policy>',
       # Optional. Specify the validity period of the role session.
       role_session_expiration=3600
   )
   
   
   cred = Client(config)
   
   credentials_provider = CredentialProviderWrapper(cred)
   
   auth = oss2.ProviderAuthV4(credentials_provider)
   
   # Use auth for subsequent operations.
   

Security token and RAMRoleARN

1. Add the alibabacloud_credentials dependency.

   pip install alibabacloud_credentials

2. Configure the security token and RAMRoleARN as the access credentials.

   # -*- 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):
           self.client = client
   
       def get_credentials(self):
           credential = self.client.get_credential()
           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(
       # Specify the temporary access credentials (Access Key ID, Access Key Secret, and security token) obtained from environment variables.
       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',
       # Specify the ARN of the RAM role that you want your application to assume by specifying the ALIBABA_CLOUD_ROLE_ARN environment variable. Example: acs:ram::123456789012****:role/adminrole.
       role_arn='<RoleArn>',
       # Specify the role session name by specifying the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
       role_session_name='<RoleSessionName>',
       # Optional. Specify limited permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
       policy='<Policy>',
       # Optional. Specify the validity period of the role session.
       role_session_expiration=3600
   )
   
   
   cred = Client(config)
   
   credentials_provider = CredentialProviderWrapper(cred)
   
   auth = oss2.ProviderAuthV4(credentials_provider)
   
   # Use auth for subsequent operations.
   

Method 5: Use ECSRAMRole

If your application runs on an ECS instance, an elastic container instance, or an ACK worker node, we recommend that you use ECSRAMRole to initialize a credential provider. The underlying logic of this method is to use a security token obtained from STS to configure access credentials. ECSRAMRole allows you to attach a RAM role to an ECS instance, an elastic container instance, or an ACK worker node to automatically refresh the security token on the instance. This method eliminates the risks that may arise when you manually maintain an AccessKey pair or a security token. For more information about how to obtain the ECSRAMRole role, see CreateRole.

1. Add the alibabacloud_credentials dependency.

   pip install alibabacloud_credentials

2. Configure ECSRAMRole as the access credential.

   # -*- 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):
           self.client = client
   
       def get_credentials(self):
           credential = self.client.get_credential()
           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',      # Set the credential type to ecs_ram_role. 
       role_name='<RoleName>' # Specify the name of the RAM role that is attached to the ECS instance. This parameter is optional. If you do not configure this parameter, the system automatically searches for a RAM role. We recommend that you configure this parameter to reduce the number of requests. 
   )
   
   
   cred = Client(config)
   
   credentials_provider = CredentialProviderWrapper(cred)
   
   auth = oss2.ProviderAuthV4(credentials_provider)
   
   # Use auth for subsequent operations.
   

Method 6: Use OIDCRoleARN

After the RAM role is configured on the ACK worker node, the application in a pod on the node can obtain the security token of the attached role by using the metadata server in the same manner as an application deployed on an ECS instance does. However, if an untrusted application is deployed on the worker node, such as an application that is submitted by your customer and whose code is unavailable to you, you may not want the application to use the metadata server to obtain a security token of the RAM role attached to the worker node. To ensure the security of cloud resources, allow untrusted applications to securely obtain the required security token, and minimize application-level permissions, you can use the RAM Roles for Service Account (RRSA) feature. The underlying logic of this method is to use a security token obtained from STS to configure access credentials. ACK creates and mounts corresponding OpenID Connect (OIDC) token files for different application pods, and passes relevant configuration information to environment variables. The Credentials tool obtains the configuration information of environment variables and calls the AssumeRoleWithOIDC operation of STS to obtain the security token of attached roles. This method eliminates the risks that may arise when you manually maintain an AccessKey pair or a security token. For more information, see Use RRSA to authorize different pods to access different cloud services.

Method 7: Use the Credentials parameter in the context of Function Compute

If the function of your application is deployed and run in Function Compute, you can initialize the credential provider by using the Credentials parameter in the context of Function Compute. The underlying logic of this method is to use a security token obtained from STS to configure access credentials. Function Compute obtains a security token by assuming a service role based on the role configured for the function. Then, the security token is passed to your application by using the Credentials parameter in the context of Function Compute. The security token is valid for 36 hours. You cannot change its validity period. The maximum execution time of a function is 24 hours. Therefore, you do not need to refresh the security token because it does not expire when the function is executed. This method eliminates the risks that may arise when you manually maintain an AccessKey pair or a security token. For more information about how to authorize Function Compute to access OSS, see Grant Function Compute permissions to access other Alibaba Cloud services.

1. Initialize the credential provider by using the Credentials parameter in the Function Compute context.

   # -*- 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)
       # Use auth for subsequent operations.
   
       return 'success'
   

Method 8: Use CredentialsURI

If your application needs to obtain an Alibaba Cloud credential from an external system to implement flexible credential management and keyless access, you can use the CredentialsURI to initialize a credential provider. The underlying logic of this method is to use a security token obtained from STS to configure access credentials. The Credentials tool obtains the security token by using the URI that you specify to initialize an OSSClient instance on the client. This method eliminates the risks that may arise when you manually maintain an AccessKey pair or a security token. Take note that the backend service that provides the CredentialsURI response must automatically refresh the security token to ensure that your application can always obtain a valid credential.

1. To allow the Credentials tool to correctly parse and use a security token, the URI must comply with the following response protocol:

   • Response status code: 200

   • Response body structure:

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

2. Add the alibabacloud_credentials dependency.

   pip install alibabacloud_credentials

3. Configure the URI as the access credential.

   # -*- 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):
           self.client = client
   
       def get_credentials(self):
           credential = self.client.get_credential()
           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',
   	# Specify the URI of the credential in the http://local_or_remote_uri/ format by specifying the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
   	credentials_uri='<CredentialsUri>',
   )
   
   
   cred = Client(config)
   
   credentials_provider = CredentialProviderWrapper(cred)
   
   auth = oss2.ProviderAuthV4(credentials_provider)
   
   # Use auth for subsequent operations.
   

Method 9: Use custom access credentials

If none of the preceding methods meet your requirements, you can specify a custom method to obtain access credentials by calling the CredentialsProvider operation. Take note that if the underlying logic is a security token, you need to provide credential update support.

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


class CredentialProviderWrapper(CredentialsProvider):
    def get_credentials(self):
        # TODO
        # Specify the method used to obtain the custom access credentials.

        # Return long-term access credentials, which consists of an AccessKey ID and an AccessKey secret.
        return Credentials('<access_key_id>', '<access_key_secrect>')

        # Return temporary access credentials, which consists of an AccessKey ID, an AccessKey secret, and a security token.
        # Refresh the temporary access credentials based on the validity period. 
        # return Credentials('<access_key_id>', '<access_key_secrect>', '<token>');


credentials_provider = CredentialProviderWrapper()


auth = oss2.ProviderAuthV4(credentials_provider)

# Use auth for subsequent operations.