All Products
Search
Document Center

Key Management Service:RAM secret plug-in

Last Updated:Jul 05, 2024

If you managed the secret of a Resource Access Management (RAM) user in Key Management Service (KMS) and installed the RAM secret plug-in, you can reference the name of the secret to complete API authentication when you call an Alibaba Cloud SDK. The secret of a RAM user refers to the AccessKey pair that is used by the RAM user. You do not need to check the details of the AccessKey pair or whether the AccessKey pair is rotated. This topic describes how the RAM secret plug-in works and provides sample code on how to install and use the RAM secret plug-in.

How the RAM secret plug-in works

The RAM secret plug-in retrieves a RAM secret from KMS based on a secret name and then caches the secret in the memory of the application for which the plug-in is installed. When the application uses an Alibaba Cloud SDK to access a cloud service, the application uses the AccessKey pair that is cached by the RAM secret plug-in to initiate requests.

If the cached AccessKey pair becomes invalid due to reasons such as secret rotation, the RAM secret plug-in immediately retrieves another secret from KMS, refreshes the cache, and then retries the failed request by using the new secret based on error-triggered retry settings. If the InvalidAccessKeyId or InvalidAccessKeyId.NotFound error is returned, the RAM secret plug-in considers that the AccessKey pair is invalid.

Supported Alibaba Cloud SDKs

KMS provides the RAM secret plug-in for the Alibaba Cloud SDKs in the following table.

Important

The RAM secret plug-in must be developed separately for each Alibaba Cloud SDK. If your application uses SDKs that are not in the following table, you can use Secret client, KMS Instance SDK, or an Alibaba Cloud SDK to retrieve a secret. For more information, see SDK references. You can also contact technical support for help.

SDK for Java (Java 8 and later)

Alibaba Cloud SDK

Module of the RAM secret plug-in

Description

Alibaba Cloud SDK V1.0 for Java

aliyun-java-sdk-managed-credentials-provider

Only Alibaba Cloud SDK V1.0 is supported. Alibaba Cloud SDK V2.0 is not supported. For Alibaba Cloud SDK V2.0, we recommend that you use Secret client, KMS Instance SDK, or Alibaba Cloud SDK.

OSS SDK for Java

aliyun-oss-java-sdk-managed-credentials-provider

None.

ONS Java Client

ons-client-managed-credentials-provider

None.

SDK for Python

Alibaba Cloud SDK

Module of the RAM secret plug-in

Description

Alibaba Cloud SDK V1.0 for Python

aliyun-openapi-python-sdk-managed-credentials-provider

Only Alibaba Cloud SDK V1.0 is supported. Alibaba Cloud SDK V2.0 is not supported. For Alibaba Cloud SDK V2.0, we recommend that you use Secret client, KMS Instance SDK, or Alibaba Cloud SDK.

OSS SDK for Python

aliyun-oss-python-sdk-managed-credentials-provider

None.

SDK for Go

Alibaba Cloud SDK

Module of the RAM secret plug-in

Description

Alibaba Cloud SDK V1.0 for Go

alibaba-cloud-sdk-go-managed-credentials-provider

Only Alibaba Cloud SDK V1.0 is supported. Alibaba Cloud SDK V2.0 is not supported. For Alibaba Cloud SDK V2.0, we recommend that you use Secret client, KMS Instance SDK, or Alibaba Cloud SDK.

OSS SDK for Go

aliyun-oss-go-sdk-managed-credentials-provider

None.

Identity authentication methods

The following two authentication methods are supported when you use the RAM secret plug-in:

  • Client key of an application access point (AAP): You can retrieve a secret by using a KMS instance endpoint or a KMS endpoint. Before you use this method, you must create an AAP and then create a client key for the AAP. For more information, see Create an AAP.

  • Instance RAM role attached to an Elastic Compute Service (ECS) instance: You can retrieve a secret by calling API operations and by using a KMS endpoint. Before you use this method, you must create an instance RAM role for your ECS instance. For more information, see Grant ECS access to resources of other Alibaba Cloud services by using instance RAM roles.

Important

To achieve high QPS and low latency, we recommend that you use the first method and a KMS instance endpoint to retrieve a secret.

Configure the runtime parameters of the RAM secret plug-in by using a configuration file

The RAM secret plug-in allows you to configure runtime parameters by using only a configuration file. You must add the managed_credentials_providers.properties configuration file to the working directory of your application and then add content to the configuration file based on the authentication method that is used.

Note

If your application cannot find the managed_credentials_providers.properties configuration file, you can specify the configuration file path in code for the application to read the file. For more information, see the following sample code.

  • (Recommended) Use the client key of an AAP and a KMS instance endpoint to retrieve a secret

    You must configure the cache_client_dkms_config_info parameter in the JSON array format. You can configure multiple KMS instances to ensure high service availability and disaster recovery capabilities. The configuration varies based on the method that is used to obtain the password of the client key file.

    • Method 1: Obtain the password of the client key file from a file

      cache_client_dkms_config_info=[{"regionId":"<your kms region>","endpoint":"<your kms endpoint>","passwordFromFilePath":"<your client key password file absolute path>","clientKeyFile":"<your client key file absolute path>","ignoreSslCerts":false,"caFilePath":"<your DKMS's CA certificate file absolute path>"}]
    • Method 2: Obtain the password of the client key file from an environment variable

      This method requires you to configure the password of the client key file in an environment variable. The name of the environment variable must be the value that you specify for the passwordFromEnvVariable parameter.

      cache_client_dkms_config_info=[{"regionId":"<your kms region>","endpoint":"<your kms endpoint>","passwordFromEnvVariable":"<your_password_env_variable>","clientKeyFile":"<your client key file absolute path>","ignoreSslCerts":false,"caFilePath":"<your DKMS's CA certificate file absolute path>"}]

    View parameter description

    Parameter

    Description

    Setting notes

    regionId

    The ID of the region where the KMS instance resides.

    For more information about how to obtain the region ID, see Regions and endpoints.

    endpoint

    The endpoint of the KMS instance, which is in the {Instance ID}.kms.aliyuncs.com format.

    To view the endpoint of a KMS instance, go to the Instances page in the KMS console, view the details of the KMS instance, obtain the value of Instance VPC Endpoint, and then remove https:// from the value.

    clientKeyFile

    The absolute or relative path to the client key file in the JSON format.

    • Client key file: The file is downloaded when you create a client key for an AAP. The file stores the content of Application Access Secret (ClientKeyContent) and is named in the ClientKey_******.json format.

    • Password of the client key file: You must obtain the password (ClientKeyPassword) that is saved when you create the client key.

    Important

    The client key file and password are a one-to-one correspondence. You can obtain the file and password only when you create the client key. If you do not save the file or password when you create the client key, you must create another client key. For more information, see Create an AAP.

    passwordFromFilePath or passwordFromEnvVariable

    • passwordFromFilePath: The password of the client key file is obtained from a file. The value is the absolute or relative path to the file that contains the password of the client key file. You must save the password to the file.

    • passwordFromEnvVariable: The password of the client key file is obtained from an environment variable. The value is the name of an environment variable that stores the password of the client key file. You must configure the password in the environment variable.

    ignoreSslCerts

    Specifies whether to ignore the validity check on the SSL certificate of the KMS instance. The KMS instance has a built-in SSL certificate that is used for identity verification and SSL- or TLS-encrypted communication. The type of the CMK. Valid values:

    • true: The validity check is ignored.

      Note

      If you set the value to true, you do not need to configure the caFilePath parameter.

    • false: The validity check is performed.

    In the production environment, set this parameter to false.

    caFilePath

    The absolute or relative path to the certificate authority (CA) certificate file of the KMS instance.

    The CA certificate is used to check the validity of the SSL certificate of the KMS instance. For example, you can check whether the SSL certificate is issued by the required CA, whether the SSL certificate is within the validity period, and whether the domain name bound to the SSL certificate is the endpoint of the KMS instance.

    To obtain the CA certificate, go to the Instances page and click Download below Instance CA Certificate. For more information, see Obtain the CA certificate of a KMS instance.

  • Use the client key of an AAP and a KMS endpoint to retrieve a secret

    ## The type of the secret. 
    credentials_type=client_key
    
    ## The system can read the password of the client key file from an environment variable or a file. 
    ## Password of the client key file: You must obtain the password (ClientKeyPassword) that is saved when you create the 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#
    
    # The path to the client key file. 
    # Client key file: The file is downloaded when you create a client key for an AAP. The file stores the content of Application Access Secret (ClientKeyContent). 
    By default, the name of the client key file is in the ClientKey_******.json format. 
    client_key_private_key_path=#your client key private key file path#
    
    ## The region of the KMS instance. 
    cache_client_region_id=[{"regionId":"#regionId#"}]
  • Use an instance RAM role attached to an ECS instance and a KMS endpoint to retrieve a secret

    credentials_type=ecs_ram_role
    ## The name of the instance RAM role that is attached to your ECS instance.
    credentials_role_name=#credentials_role_name#
    ## The region of the KMS instance.
    cache_client_region_id=[{"regionId":"#regionId#"}]

Sample code

Java

Alibaba Cloud SDK V1.0 for Java

  1. Add the RAM secret plug-in as a Maven dependency to your project.

    <dependency>
       <groupId>com.aliyun</groupId>
       <artifactId>aliyun-java-sdk-core</artifactId>
       <version>[4.3.2,5.0.0)</version>
    </dependency>
    <dependency>
      <groupId>com.aliyun</groupId>
      <artifactId>aliyun-java-sdk-core-managed-credentials-provider</artifactId>
      <version>[1.3.1,)</version>
    </dependency>
    Note

    We recommend that you install the latest version of the plug-in. For more information, visit Source code.

  2. Create a client of Alibaba Cloud SDK for Java and call a cloud service.

    The following sample code provides an example on how to call the DescribeInstanceStatus operation of ECS:

    When you run the following sample code, add the aliyun-java-sdk-ecs dependency of ECS to the pom.xml file.

    import com.aliyuncs.IAcsClient;
    import com.aliyuncs.ecs.model.v20140526.DescribeInstanceStatusRequest;
    import com.aliyuncs.ecs.model.v20140526.DescribeInstanceStatusResponse;
    import com.aliyun.kms.secretsmanager.plugin.sdkcore.ProxyAcsClient;
    import com.aliyuncs.exceptions.ClientException;
    import com.aliyuncs.exceptions.ServerException;
    
    public class AliyunSdkProviderSample {
        public static void main(String[]args) {
            String secretName="******";
            /*
              If the application cannot set the default configuration file (managed_credentials_providers.properties) to read from the classpath and executable jar package, 
              or if you want to specify a custom file name, you can use the following code to configure a custom file:
              1. If your-config-name is set to a value in the Absolute path + File name format, the configuration file in the absolute path is read.
              2. If your-config-name is set to a file name, the configuration file in classpath is read and then the configuration file in the executable JAR package is read.
            */
            //ConfigLoader.setConfigName("your-config-name");
            
            // 1. Create a client.
            IAcsClient client = null;
            try {
                client = new ProxyAcsClient("<the regionId of ECS>", secretName);
            } catch (ClientException e) {
                 e.printStackTrace();
             }
            // 2. Call an API operation of ECS to implement business functionality.
            DescribeInstanceStatusRequest request = new DescribeInstanceStatusRequest();
            DescribeInstanceStatusResponse response;
            try {
                 response = client.getAcsResponse(request);
            } catch (ServerException e) {
                 e.printStackTrace();
             } catch (ClientException e) {
                 e.printStackTrace();
             }
            // 3. Shut down the client to release plug-in-related resources. 
            client.shutdown();
        }
    }

OSS SDK for Java

  1. Add the RAM secret plug-in as a Maven dependency to your project.

    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>aliyun-java-sdk-core</artifactId>
        <version>4.5.17</version>
    </dependency>
    <dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>[2.1.0,3.10.2]</version>
    <exclusions>
        <exclusion>
            <groupId>com.aliyun</groupId>
            <artifactId>aliyun-java-sdk-kms</artifactId>
        </exclusion>
    </exclusions>
    </dependency>
    <dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-sdk-oss-managed-credentials-provider</artifactId>
    <version>[1.3.1,]</version>
    </dependency>
    Note

    We recommend that you install the latest version of the plug-in. For more information, visit Source code.

  2. Create a client of Object Storage Service (OSS) SDK for Java and call a cloud service.

    The following sample code provides an example on how to call the listBuckets operation of OSS:

    import com.aliyun.kms.secretsmanager.plugin.oss.ProxyOSSClientBuilder;
    import com.aliyun.oss.OSS;
    import com.aliyun.oss.model.Bucket;
    
    import java.util.List;
    
    public class OssProviderSample {
    
        public static void main(String[] args) throws Exception {
            String secretName = "******";
            String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
    
            /*
              If the application cannot set the default configuration file (managed_credentials_providers.properties) to read from the classpath and executable jar package, 
              or if you want to specify a custom file name, you can use the following code to configure a custom file:
              1. If your-config-name is set to a value in the Absolute path + File name format, the configuration file in the absolute path is read.
              2. If your-config-name is set to a file name, the configuration file in classpath is read and then the configuration file in the executable JAR package is read.
            */
            //ConfigLoader.setConfigName("your-config-name");
    
            // Create a client.
            OSS ossClient = new ProxyOSSClientBuilder().build(endpoint, secretName);
    
    
            // Call the listBuckets operation.
            List<Bucket> buckets = ossClient.listBuckets();
            for (Bucket bucket : buckets) {
                if (bucket != null) {
                    // ...
                }
            }
    
            // Shut down the client to release plug-in-related resources. 
            ossClient.shutdown();
        }
    
    }

Python

Alibaba Cloud SDK V1.0 for Python

  1. Run the pip command to install the RAM secret plug-in.

    pip install aliyun-openapi-python-sdk-managed-credentials-provider
    Note

    Make sure that the version of the RAM secret plug-in is 0.1.0 or later. For more information, visit Source code.

  2. Create a client of Alibaba Cloud SDK for Python and call a cloud service.

    from aliyun_sdk_secretsmanager_sdk_core_plugin.proxy_acs_client import ProxyAcsClient
    
       region="cn-hangzhou"
       secretName="******"
    
       # 1. Create an ACSClient instance.
       client = ProxyAcsClient(region_id=region, secret_name=secretName )
    
       # 2. Use the instance to call a cloud service. You do not need to modify the business code. 
       ...
    
       # 3. Disable the instance to release plug-in-related resources.
       client.shutdown()

OSS SDK for Python

  1. Run the pip command to install the RAM secret plug-in.

    pip install aliyun-oss-python-sdk-managed-credentials-provider
    Note

    Make sure that the version of the RAM secret plug-in is 0.1.0 or later. For more information, visit Source code.

  2. Create a client of OSS SDK for Python and call a cloud service.

    from aliyun_sdk_secretsmanager_oss_plugin.proxy_bucket import ProxyBucket
    from itertools import islice
    
    endpoint = "******"
    secret_name ="******"
    bucket_name = "******"
    bucket = ProxyBucket(secret_name=secret_name, endpoint=endpoint, bucket_name=bucket_name)
    objects = bucket.list_objects()
    for b in islice(objects.object_list, 10):
        print(b.key)
    bucket.shutdown()

Go

Alibaba Cloud SDK V1.0 for Go

  1. Install the RAM secret plug-in.

    Note

    We recommend that you install the latest version of the plug-in. For more information, visit Source code.

    • Method 1: Use the go.mod file to manage dependencies.

      Add the following content to the go.mod file to install the dependency package:

      require (
          github.com/aliyun/aliyun-sdk-managed-credentials-providers-go/aliyun-sdk-managed-credentials-providers/alibaba-cloud-sdk-go-managed-credentials-provider vX.X.X
      )
    • Method 2: Run the go get command to obtain the remote code package.

      go get -u github.com/aliyun/aliyun-sdk-mxanaged-credentials-providers-go/aliyun-sdk-managed-credentials-providers/alibaba-cloud-sdk-go-managed-credentials-provider
  2. Create a client of Alibaba Cloud SDK for Go and call a cloud service.

    The following sample code provides an example on how to call the DescribeInstances operation of ECS:

    package sample
    
    import (
        "fmt"
        "github.com/aliyun/alibaba-cloud-sdk-go/services/ecs"
        sdkcoreprovider "github.com/aliyun/aliyun-sdk-managed-credentials-providers-go/aliyun-sdk-managed-credentials-providers/alibaba-cloud-sdk-go-managed-credentials-provider/sdk"
    )
    
    func main() {
        secretName := "********"
        regionId := "cn-hangzhou"
    
        client, err := sdkcoreprovider.GetClient(&ecs.Client{}, regionId, secretName)
        if err != nil {
            fmt.Println(err)
            return
        }
        ecsClient := client.(*ecs.Client)
    
        request := ecs.CreateDescribeInstancesRequest()
        instancesResponse, err := ecsClient.DescribeInstances(request)
        if err != nil {
            fmt.Println(err)
            return
        }
    
        for _, instance := range instancesResponse.Instances.Instance {
            // do something with instance
        }
    }

OSS SDK for Go

  1. Install the RAM secret plug-in.

    Note

    We recommend that you install the latest version of the plug-in. For more information, visit Source code.

    • Method 1: Use the go.mod file to manage dependencies.

      Add the following content to the go.mod file to install the dependency package:

      require (
          github.com/aliyun/aliyun-sdk-managed-credentials-providers-go/aliyun-sdk-managed-credentials-providers/aliyun-oss-go-sdk-managed-credentials-provider vX.X.X
      )
    • Method 2: Run the go get command to obtain the remote code package.

      go get -u github.com/aliyun/aliyun-sdk-managed-credentials-providers-go/aliyun-sdk-managed-credentials-providers/aliyun-oss-go-sdk-managed-credentials-provider
  2. Create a client of OSS SDK for Go and call a cloud service.

    package sample
    
    import (
        "fmt"
        ossprovider "aliyun-oss-go-sdk-managed-credentials-provider/sdk"
    )
    
    func main() {
        secretName := "********"
        endpoint := "https://oss-cn-hangzhou.aliyuncs.com"
    
        // Create a proxy OSS client.
        client, err := ossprovider.New(endpoint, secretName)
        if err != nil {
            fmt.Println(err)
            return
        }
    
        result, err := client.ListBuckets()
        if err != nil {
            fmt.Println(err)
            return
        }
        for _, bucket := range result.Buckets {
            // The business code.
        }
    
        // Shut down the proxy OSS client to release plug-in-related resources.
        client.Shutdown()
    }