Key Management Service:Use the instance RAM role attached to an ECS instance to securely access KMS

Alibaba Cloud SDK V1.0

package com.aliyuncs.kms.examples;

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.auth.AlibabaCloudCredentialsProvider;
import com.aliyuncs.auth.InstanceProfileCredentialsProvider;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.kms.model.v20160120.*;
import com.aliyuncs.profile.DefaultProfile;

public class RamRoleTest {
    public static void main(final String[] args) throws Exception {
        String regionId = "<region-id>";
        DefaultProfile profile = DefaultProfile.getProfile(regionId);

        // Specify the instance RAM role name.
        String roleName = "EcsRamRoleTest";

        // Configure the credential provider to use the instance RAM role.
        AlibabaCloudCredentialsProvider provider = new InstanceProfileCredentialsProvider(roleName);

        IAcsClient client = new DefaultAcsClient(profile, provider);

        ListKeysRequest request = new ListKeysRequest();

        try {
            ListKeysResponse response = client.getAcsResponse(request);
            System.out.println(new Gson().toJson(response));
        } catch (ServerException e) {
            e.printStackTrace();
        } catch (ClientException e) {
            System.out.println("ErrCode:" + e.getErrCode());
            System.out.println("ErrMsg:" + e.getErrMsg());
            System.out.println("RequestId:" + e.getRequestId());
        }
    }
}

For credential management details, see Manage access credentials (Alibaba Cloud SDK V1.0).

Alibaba Cloud SDK V2.0

package com.aliyun.sample;

import com.aliyun.tea.*;

public class Sample {

    public static com.aliyun.kms20160120.Client createClient() throws Exception {
        com.aliyun.credentials.models.Config credentialConfig = new com.aliyun.credentials.models.Config();
        // Use the ECS instance RAM role as the credential type.
        credentialConfig.type = "ecs_ram_role";
        // Optional: specify the role name to reduce metadata service requests. If not set, the role name is automatically obtained.
        credentialConfig.roleName = "<your-ecsRamRoleName>";
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialConfig);

        com.aliyun.teaopenapi.models.Config kmsClientConfig = new com.aliyun.teaopenapi.models.Config()
            // Set the KMS endpoint for your region, for example, kms.cn-hangzhou.aliyuncs.com.
            .setEndpoint("kms.cn-hangzhou.aliyuncs.com")
            .setCredential(credentialClient);
        return new com.aliyun.kms20160120.Client(kmsClientConfig);
    }

    public static void main(String[] args_) throws Exception {
        java.util.List<String> args = java.util.Arrays.asList(args_);
        com.aliyun.kms20160120.Client client = Sample.createClient();
        com.aliyun.kms20160120.models.ListKeysRequest listKeysRequest = new com.aliyun.kms20160120.models.ListKeysRequest();
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        try {
            client.listKeysWithOptions(listKeysRequest, runtime);
        } catch (TeaException error) {
            System.out.println(error.getMessage());
            com.aliyun.teautil.Common.assertAsString(error.message);
        } catch (Exception _error) {
            _error.printStackTrace();
        }
    }
}

For credential management details, see Manage access credentials (Alibaba Cloud SDK V2.0).

Secrets Manager Client

Configure credentials in system environment variables or in secretsmanager.properties:

Then construct the client to retrieve secret values:

import com.aliyuncs.kms.secretsmanager.client.SecretCacheClient;
import com.aliyuncs.kms.secretsmanager.client.SecretCacheClientBuilder;
import com.aliyuncs.kms.secretsmanager.client.exception.CacheSecretException;
import com.aliyuncs.kms.secretsmanager.client.model.SecretInfo;

public class CacheClientEnvironmentSample {

    public static void main(String[] args) {
        try {
            // Build Secrets Manager Client using configuration from environment variables or secretsmanager.properties.
            SecretCacheClient client = SecretCacheClientBuilder.newClient();
            // Retrieve the secret value by secret name.
            SecretInfo secretInfo = client.getSecretInfo("#secretName#");
            System.out.println(secretInfo);
        } catch (CacheSecretException e) {
            e.printStackTrace();
        }
    }
}

For the full reference, see Secret client.

Secret JDBC client

Add secretsmanager.properties to your project:

## Credential type for the ECS instance RAM role.
credentials_type=ecs_ram_role
## Name of the instance RAM role attached to your ECS instance.
credentials_role_name=#credentials_role_name#
## Region of the KMS instance.
cache_client_region_id=[{"regionId":"#regionId#"}]
## Secret rotation interval. Default: 21600000 ms (6 hours). Minimum: 300000 ms (5 minutes).
refresh_secret_ttl=21600000

Connect to MySQL using the secret JDBC driver:

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

public class SecretManagerJDBCSample {
    public static void main(String[] args) throws Exception {
        // Load the secret JDBC driver.
        Class.forName("com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver");
        Connection connect = null;
        try {
            // The driver retrieves MySQL credentials from KMS automatically.
            connect = DriverManager.getConnection(
                "secrets-manager:mysql://<YOUR-MYSQL-IP>:<YOUR-MYSQL-PORT>/<YOUR-DATABASE-NAME>",
                "#your-mysql-secret-name#",
                ""
            );
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
}

For the full reference, see Secret JDBC client.

RAM secret plug-in

Add managed_credentials_providers.properties to your application's working directory:

credentials_type=ecs_ram_role
## Name of the instance RAM role attached to your ECS instance.
credentials_role_name=#credentials_role_name#
## Region of the KMS instance.
cache_client_region_id=[{"regionId":"#regionId#"}]

If the application cannot read the default configuration file (managed_credentials_providers.properties) from the classpath or executable JAR, you can specify a custom file path using ConfigLoader.setConfigName("your-config-name"). If the value is set to an absolute path, the system reads the configuration file from that path. If it is set to a file name only, the system first checks the classpath and then the executable JAR package.

Add the aliyun-java-sdk-ecs dependency to your pom.xml, then create a ProxyAcsClient to call Alibaba Cloud APIs:

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 = "******";

        // 1. Create a ProxyAcsClient backed by the RAM secret plug-in.
        IAcsClient client = null;
        try {
            client = new ProxyAcsClient("<the regionId of ECS>", secretName);
        } catch (ClientException e) {
            e.printStackTrace();
        }

        // 2. Call an API operation — credentials are injected automatically.
        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 resources.
        client.shutdown();
    }
}

For the full reference, see RAM secret plug-in.