Key Management Service:Managed secret plug-in for Alibaba Cloud SDKs

Principles

If an application uses the managed secret plug-in, the application needs to only reference the name of a managed RAM secret. The plug-in obtains a value of the secret from Secrets Manager based on the name of the secret and caches the value in the memory of the application. You can also specify a frequency at which the plug-in retrieves the value of the secret from Secrets Manager and refreshes the cache.

When the application uses an Alibaba Cloud SDK, the application initiates requests to cloud services by using the AccessKey pair that is cached by the plug-in.

Cached RAM secrets may expire. This occurs when an administrator manually rotates secrets in Secrets Manager in response to security events. If you use an invalid RAM secret to access Alibaba Cloud services, an exception occurs in the application. If the error code InvalidAccessKeyId.NotFound or InvalidAccessKeyId is returned, the plug-in immediately refreshes the cache of RAM secrets and retries the failed request.

If other error codes are returned when you use an invalid RAM secret to access some cloud services, you can modify the default expiration handler. For more information, see Example 2: Reconfigure the AccessKey pair expiration-triggered handling process.

Supported Alibaba Cloud SDKs

Alibaba Cloud provides different SDKs. The managed secret plug-in for different SDKs must be separately developed. The following table lists the SDKs for which the managed secret plug-in is developed.

If you want to use the managed secret plug-in for other SDKs, contact technical support by using ticket.

Install the managed secret plug-in

Alibaba Cloud provides the managed secret plug-in for various Alibaba Cloud SDKs for Java. For more information about how to install the plug-in, visit aliyun-sdk-managed-credentials-providers-java.

You can install the managed secret plug-in for Alibaba Cloud SDKs for Java by adding the Maven dependencies. The following sample code provides an example on how to install the managed secret plug-in for OSS SDK for Java by adding the Maven dependency:

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-sdk-oss-managed-credentials-provider</artifactId>
    <version>x.x.x</version>
</dependency>

Example 1: Use a managed RAM secret in an Alibaba Cloud SDK

1. Configure the managed secret plug-in for an Alibaba Cloud SDK.

   You can use the managed_credentials_providers.properties configuration file to specify the method that you want to use to obtain a managed RAM secret from Secrets Manager. The client key of an application access point (AAP) is used in this example. For more information about how to create a client key, see Bind a client key to the AAP.

   ## Specify the access method. 
   credentials_type=client_key
   
   ## Read the decryption password of the client key. You can read the password from an environment variable or a 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#
   
   ## Read the private key file of the client key. 
   client_key_private_key_path=#your client key private key file path#
   
   ## Specify the region of KMS. 
   cache_client_region_id=[{"regionId":"#regionId#"}]

2. Use the managed RAM secret to access a cloud service.
   • Method 1: Use the encoding method. In this example, the managed RAM secret is used to access 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 OssPluginSample {
     
         public static void main(String[] args) throws Exception {
             String secretName = "******";
             String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
     
             // Create an OSS client. 
             OSS ossClient = new ProxyOSSClientBuilder().build(endpoint, secretName);
     
             List<Bucket> buckets = ossClient.listBuckets();
             for (Bucket bucket : buckets) {
                 if (bucket != null) {
                     // do something with bucket
                 }
             }
     
             // Shut down the client to release the resources associated with the plug-in. 
              ossClient.shutdown();
         }
     }

   • Method 2: Use the Spring beans. In this example, OSS SDKs are integrated with your system.

     <?xml version="1.0" encoding="UTF-8"?>
     <beans xmlns="http://www.springframework.org/schema/beans"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.springframework.org/schema/beans
                   http://www.springframework.org/schema/beans/spring-beans.xsd">
         <bean name="proxyOSSClientBuilder" class="com.aliyun.kms.secretsmanager.plugin.oss.ProxyOSSClientBuilder" scope="singleton" />
     </beans>

Example 2: Reconfigure the AccessKey pair expiration-triggered handling process

By default, the managed secret plug-in calls the AKExpireHandler operation to determine whether an invalid secret is used to access the cloud service. If an invalid secret is used, the plug-in obtains the latest secret from Secrets Manager and retries the access to the cloud service.

The following sample code defines the AKExpireHandler operation:

package com.aliyun.kms.secretsmanager.plugin.common;

public interface AKExpireHandler<TException> {

  /**
   * Determine whether the exception is caused by the expiration of the AccessKey pair. 
   *
   * @param e
   * @return
   */
  boolean judgeAKExpire(TException e);
}

Determine whether the error code returned by the cloud service is caused by using an invalid AccessKey pair. Troubleshoot the issue and call the AKExpireHandler operation again. Example:

import com.aliyun.kms.secretsmanager.plugin.sdkcore.ProxyAcsClient;
import com.aliyun.kms.secretsmanager.plugin.common.AKExpireHandler;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;

import java.util.HashSet;
import java.util.Set;

public class SdkRetrySample {

  public static void main(String[]args) throws Exception{
    String region="cn-hangzhou";
    String secretName="******";

    // Obtain the client of an Alibaba Cloud SDK and obtain the secret again based on specific error codes. 
    IAcsClient client = new ProxyAcsClient(
        region, secretName, new CustomHandler());

    // The business code. 
    invoke(client,region);

    // Shut down the client to release the resources associated with the plug-in.  
    client.shutdown();
  }
}

class CustomHandler implements AKExpireHandler<ClientException> {
  private Set<String> errorCodeSet;

  public CustomerHandler() {
      errorCodeSet = new HashSet<String>();
      // Add an error code to allow the client to obtain the managed RAM secret from Secrets Manager again. 
      errorCodeSet.add("InvalidAccessKeyId.NotFound");
      errorCodeSet.add("InvalidAccessKeyId");
  }

  @Override
  public boolean judgeAKExpire(ClientException e) {
      return errorCodeSet.contains(e.getErrCode());
  }

}