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.
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 |
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. | ||
None. | ||
None. |
SDK for Python
Alibaba Cloud SDK | Module of the RAM secret plug-in | Description |
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. | ||
None. |
SDK for Go
Alibaba Cloud SDK | Module of the RAM secret plug-in | Description |
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. | ||
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.
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.
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>"}]
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
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>
NoteWe recommend that you install the latest version of the plug-in. For more information, visit Source code.
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
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>
NoteWe recommend that you install the latest version of the plug-in. For more information, visit Source code.
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
Run the pip command to install the RAM secret plug-in.
pip install aliyun-openapi-python-sdk-managed-credentials-provider
NoteMake sure that the version of the RAM secret plug-in is 0.1.0 or later. For more information, visit Source code.
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
Run the pip command to install the RAM secret plug-in.
pip install aliyun-oss-python-sdk-managed-credentials-provider
NoteMake sure that the version of the RAM secret plug-in is 0.1.0 or later. For more information, visit Source code.
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
Install the RAM secret plug-in.
NoteWe 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
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
Install the RAM secret plug-in.
NoteWe 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
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() }