If you use an Alibaba Cloud SDK and install a managed secret plug-in for this SDK, you can use the name of a managed Resource Access Management (RAM) secret to access cloud services, regardless of what an AccessKey pair is or whether the AccessKey pair is rotated. A managed RAM secret stores the AccessKey pair of a RAM user.

Principles

If an application uses a managed secret plug-in, the application needs only to reference the name of a managed RAM secret. The plug-in obtains the 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 default expiration handler.

Supported Alibaba Cloud SDKs

Alibaba Cloud provides different SDKs. Managed secret plug-ins for different SDKs must be separately developed. The following table lists these SDKs.

Alibaba Cloud SDK Version Managed secret plug-in
Alibaba Cloud SDK for Java 4.3.2 to 4.5.17 Managed secret plug-in for Alibaba Cloud SDK for Java
OSS Java SDK 2.1.0 to 3.10.2 Managed secret plug-in for OSS SDK for Java
ONS Java Client 1.8.5.Final to 1.8.7.4.Final Managed secret plug-in for ONS Java Client

Install a managed secret plug-in

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

You can install the managed secret plug-ins 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>1.0.0</version>
</dependency>
Note For more information about the versions of the managed secret plug-ins for Alibaba Cloud SDKs for Java, visit aliyun-sdk-managed-credentials-providers-java release.

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

  1. Configure a managed secret plug-in for the 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 is used in this example. For more information about how to create a client key, see Bind a client key to the application access point.

    ## 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";
      
              // Obtain the 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
                  }
              }
      
              // Use the following method to close 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 default expiration handler

By default, the managed secret plug-in calls the AKExpireHandler operation to determine whether an invalid secret is used to access a 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);
}

The AKExpireHandler operation can be called again to determine whether the error code returned by the cloud service is caused by using an invalid AccessKey pair. 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);

    // Use the following method to close 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());
  }

}