Object Storage Service:Configure access credentials

Use the AccessKey pair of a RAM user

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.

Environment variables

1. Configure environment variables for the AccessKey pair of the RAM user.

   Linux

   1. Run the following commands on the CLI to add the configurations of the environment variables to the ~/.bashrc file:

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

      1. Run the following command to apply the changes:

         source ~/.bashrc

      2. Run the following commands to check whether the environment variables have taken effect:

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. Run the following command in the terminal to view the default shell type:

      echo $SHELL

   2. Configure environment variables based on the default shell type.

      Zsh

      1. Run the following commands to add the configurations of the environment variables to the ~/.zshrc file:

         echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
         echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

      2. Run the following command to apply the changes:

         source ~/.zshrc

      3. Run the following commands to check whether the environment variables take effect:

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      Bash

      1. Run the following commands to add the configurations of the environment variables to the ~/.bash_profile file:

         echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
         echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

      2. Run the following command to apply the changes:

         source ~/.bash_profile

      3. Run the following commands to check whether the environment variables take effect:

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. Run the following commands in CMD:

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

   2. Run the following commands to check whether the environment variables take effect:

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. Run the following commands in PowerShell:

      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

   2. Run the following commands to check whether the environment variable takes effect:

      [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

2. To make sure that your settings are loaded, restart or refresh your compilation and runtime environments, such as the IDE, command-line tool, desktop applications, and services in the background.

3. Use environment variables to pass credentials.

   import alibabacloud_oss_v2 as oss
   
   def main():
       # Obtain access credentials from environment variables for authentication.
       credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
   
       # Load the default configurations of the SDK and specify the credential provider.
       cfg = oss.config.load_default()
       cfg.credentials_provider = credentials_provider
   
       # Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
       cfg.region = 'cn-hangzhou'
   
       # Use the configurations to create an OSSClient instance.
       client = oss.Client(cfg)
   
       # Use the OSSClient instance to perform subsequent operations.
   
   # Call the main function when the script is directly run.
   if __name__ == "__main__":
       main() # Specify the entry points in the main function of the script when the script is directly run.

Static credentials

The following example shows how to hardcode access credentials of a RAM user in code:

import alibabacloud_oss_v2 as oss

def main():
    # Create a static credential provider and explicitly specify the AccessKey ID and AccessKey Secret of your RAM user.
    credentials_provider = oss.credentials.StaticCredentialsProvider(
        access_key_id="RAM AccessKey ID",
        access_key_secret="RAM AccessKey Secret"
    )

    # Load the default configurations of the SDK and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
    cfg.region = 'cn-hangzhou'

    # Use the configurations to create an OSSClient instance.
    client = oss.Client(cfg)

    # Use the OSSClient instance to perform subsequent operations.


# Call the main function when the script is directly run.
if __name__ == "__main__":
    main() # Specify the entry points in the main function of the script when the script is directly run.

Use temporary access credentials provided by STS

If your application needs to access OSS temporarily, you can use temporary access credentials, which consist of an AccessKey pair and a security token, obtained from STS. Take note that this method requires you to manually maintain a security token. This poses security risks and increases maintenance complexity. If you want to access OSS multiple times, you must manually refresh the security token.

Environment variables

1. Configure environment variables for temporary access credentials.

   Mac OS X/Linux/Unix

   Warning

   • Take note that the temporary access credentials (AccessKey ID, AccessKey secret, and security token) provided by STS are used instead of the AccessKey ID and AccessKey secret of the RAM user.

   • The AccessKey ID obtained from STS starts with STS. Example: STS.****************.

   export OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
   export OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
   export OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>

   Windows

   Warning

   • Take note that the temporary access credentials (AccessKey ID, AccessKey secret, and security token) provided by STS are used instead of the AccessKey ID and AccessKey secret of the RAM user.

   • The AccessKey ID obtained from STS starts with STS. Example: STS.L4aBSCSJVMuKg5U1****.

   set OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
   set OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
   set OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>

2. Pass the temporary access credentials by using environment variables.

   import alibabacloud_oss_v2 as oss
   
   def main():
       # Load the authentication information required to access OSS from the environment variables.
       credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
   
       # Load the default configurations of the SDK and specify the credential provider.
       cfg = oss.config.load_default()
       cfg.credentials_provider = credentials_provider
   
       # Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
       cfg.region = 'cn-hangzhou'
   
       # Use the configurations to create an OSSClient instance.
       client = oss.Client(cfg)
   
       # Use the OSSClient instance to perform subsequent operations.
   
   
   # Call the main function when the script is directly run.
   if __name__ == "__main__":
       main() # Specify the entry points in the main function of the script when the script is directly run.

Static credentials

Below is the sample code for hardcoding access credentials to explicitly specify the AccessKey pair that you want to use to access OSS.

import alibabacloud_oss_v2 as oss

def main():
    # Specify the temporary AccessKey ID and AccessKey secret provided by STS, instead of the AccessKey ID and AccessKey secret of an Alibaba Cloud account. 
    # Take note that an AccessKey ID provided by STS starts with STS. 
    sts_access_key_id = 'STS.****************'
    sts_access_key_secret = 'yourAccessKeySecret'
    # Specify the security token obtained from STS. 
    sts_security_token = 'yourSecurityToken'

    # Create a static credential provider and explicitly specify the AccessKey ID, AccessKey Secret, and the security token obtained from STS.
    credentials_provider = oss.credentials.StaticCredentialsProvider(
        access_key_id=sts_access_key_id,
        access_key_secret=sts_access_key_secret,
        security_token=sts_security_token,
    )

    # Load the default configurations of the SDK and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
    cfg.region = 'cn-hangzhou'

    # Use the configurations to create an OSSClient instance.
    client = oss.Client(cfg)

    # Use the OSSClient instance to perform subsequent operations.


# Call the main function when the script is directly run.
if __name__ == "__main__":
    main() # Specify the entry points in the main function of the script when the script is directly run.

Use the ARN of a RAM role

If you need to authorize your application to access OSS, for example, in a cross-account access scenario, you can use the Alibaba Cloud Resource Name (ARN) of a RAM role 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 a security token based on the ARN of the RAM role and refreshes the security token by calling the AssumeRole operation before the session expires. You can specify the Policy parameter to limit the permissions granted to the RAM role.

1. Add the alibabacloud_credentials dependency.

   pip install alibabacloud_credentials

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

   # -*- coding: utf-8 -*-
   import os
   from alibabacloud_credentials.client import Client
   from alibabacloud_credentials.models import Config
   import alibabacloud_oss_v2 as oss
   
   def main():
       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. Default value: 3600. Unit: seconds.
           role_session_expiration=3600
       )
   
       cred_client = Client(config)
   
       def get_credentials_wrapper():
           cred = cred_client.get_credential()
           return oss.credentials.Credentials(access_key_id=cred.access_key_id, access_key_secret=cred.access_key_secret, security_token=cred.security_token)
   
       # Create a credential provider to dynamically load the credentials.
       credentials_provider = oss.credentials.CredentialsProviderFunc(func=get_credentials_wrapper)
   
       # Load the default configurations of the SDK.
       cfg = oss.config.load_default()
       cfg.credentials_provider = credentials_provider
   
       # Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
       cfg.region = 'cn-hangzhou'
   
       # Create an OSSClient instance.
       client = oss.Client(cfg)
   
       # Use the OSSClient instance to perform subsequent operations.
   
   
   # Call the main function when the script is directly run.
   if __name__ == "__main__":
       main() # Specify the entry points in the main function of the script when the script is directly run.

Use the RAM role of an ECS instance

If your application runs on an ECS instance, an elastic container instance, or an ACK worker node, we recommend that you use the RAM role of the ECS instance to initialize a credential provider. The underlying logic of this method is to use a security token obtained from STS to configure access credentials. You can 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. You can create a RAM role by calling the CreateRole operation. The ARN is included in the response. For more information, see CreateRole.

1. Add the alibabacloud_credentials dependency.

   pip install alibabacloud_credentials

2. Use the RAM role to provide access credentials.

   from alibabacloud_credentials.client import Client
   from alibabacloud_credentials.models import Config
   import alibabacloud_oss_v2 as oss
   
   def main():
       config = Config(
           type='ecs_ram_role',      # Set the credential type to ecs_ram_role. 
           role_name='EcsRoleExample'    # 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 = Client(config)
   
       def get_credentials_wrapper():
           cred = cred_client.get_credential()
           return oss.credentials.Credentials(access_key_id=cred.access_key_id, access_key_secret=cred.access_key_secret, security_token=cred.security_token)
   
       # Create a credential provider to dynamically load the credentials.
       credentials_provider = oss.credentials.CredentialsProviderFunc(func=get_credentials_wrapper)
   
       # Load the default configurations of the SDK.
       cfg = oss.config.load_default()
       cfg.credentials_provider = credentials_provider
   
       # Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou. 
       cfg.region = 'cn-hangzhou'
   
       # Create an OSSClient instance.
       client = oss.Client(cfg)
   
       # Use the OSSClient instance to perform subsequent operations.
   
   
   # Call the main function when the script is directly run.
   if __name__ == "__main__":
       main() # Specify the entry points in the main function of the script when the script is directly run.

Use the RAM role of an OIDC IdP

After the RAM role is configured on the ACK worker node, applications within pods on that node can retrieve the security token for the attached role by using the metadata server, similar to an application deployed on an ECS instance. 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 OIDC token files for different application pods, and passes relevant configuration information to environment variables. The Credentials tool obtains the configuration information from environment variables and calls the AssumeRoleWithOIDC operation of STS to obtain the security token of the 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.

Use custom access credentials

If the preceding credential configuration methods do not meet your business requirements, you can specify the method that you want to use to obtain access credentials. The following methods are supported:

1. Use the credentials.CredentialsProviderFunc method

   import argparse
   import alibabacloud_oss_v2 as oss
   import os
   
   def main():
   
       def get_credentials_wrapper():
           # Return long-term access credentials.
           return oss.credentials.Credentials(access_key_id='access_key_id', access_key_secret='access_key_security')
           # Return the temporary access credentials obtained from STS.
           # return oss.credentials.Credentials(access_key_id='access_key_id', access_key_secret='access_key_security', security_token='security_token')
   
       credentials_provider = oss.credentials.CredentialsProviderFunc(func=get_credentials_wrapper)
   
      # Load the default configurations of the SDK and specify the credential provider.
       cfg = oss.config.load_default()
       cfg.credentials_provider = credentials_provider
       
       # Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
       cfg.region = "cn-hangzhou"
   
       # Use the configurations to create an OSSClient instance.
       client = oss.Client(cfg)
   
       # Use the OSSClient instance to perform subsequent operations.
   
   if __name__ == "__main__":
       main() # Specify the entry points in the main function of the script when the script is directly run.

2. Use the credentials.CredentialsProvider method

   # -*- coding: utf-8 -*-
   import alibabacloud_oss_v2 as oss
   
   class CredentialProviderWrapper(oss.credentials.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 oss.credentials.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 oss.credentials.Credentials('<access_key_id>', '<access_key_secrect>', '<token>');
   
   
   def main():
       # Create a credential provider to dynamically load the credentials.
       credentials_provider = CredentialProviderWrapper()
   
       # Load the default configurations of the SDK.
       cfg = oss.config.load_default()
       cfg.credentials_provider = credentials_provider
   
       # Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
       cfg.region = 'cn-hangzhou'
   
       client = oss.Client(cfg)
   
       # Use the OSSClient instance to perform subsequent operations.
   
   
   if __name__ == "__main__":
       main() # Specify the entry points in the main function of the script when the script is directly run.