All Products
Search
Document Center

Alibaba Cloud SDK:Manage access credentials

最終更新日:Nov 18, 2024

When you call API operations to manage cloud resources by using Alibaba Cloud SDKs, you must configure valid credential information. The Alibaba Cloud Credentials tool provides powerful features that allow you to obtain and manage access credentials with ease. This topic describes how to use the Credentials tool to configure various types of credentials such as the default credential, AccessKey pairs, or Security Token Service (STS) tokens. This topic also describes the order based on which the Credentials tool obtains the default credential. You can develop a thorough knowledge of configuring and managing credentials in Alibaba Cloud SDKs. This ensures that you can perform operations on cloud resources in an efficient and secure manner.

Background information

A credential is a set of information that is used to prove the identity of a user. When you log on to the system, you must use a valid credential to complete identity authentication. The following types of credentials are commonly used:

  1. An AccessKey pair of an Alibaba Cloud account or a Resource Access Management (RAM) user. An AccessKey pair is permanently valid and consists of an AccessKey ID and an AccessKey secret.

  2. An STS token of a RAM role. An STS token is a temporary credential. You can specify a validity period and access permissions for an STS token. For more information, see What is STS?

  3. A bearer token. It is used for identity authentication and authorization.

Prerequisites

Install the Credentials tool

Install Alibaba Cloud Credentials for Java by adding the following Maven dependency:

<dependency>
   <groupId>com.aliyun</groupId>
   <artifactId>credentials-java</artifactId>
   <version>LATEST</version>
</dependency>
  1. We recommend that you use the latest version of Alibaba Cloud Credentials for Java. This ensures that all credentials are supported.

  2. For more information about all released versions of Alibaba Cloud Credentials for Java, see ChangeLog.txt.

  3. We recommend that you use Alibaba Cloud SDK V2.0. If you do not use Alibaba Cloud SDK V2.0 but rely on the credentials-java module, you must add the following dependency. Otherwise, an error is reported to indicate that the com.aliyun.tea.TeaModel class file does not exist.

    <dependency>
      <groupId>com.aliyun</groupId>
      <artifactId>tea</artifactId>
      <version>LATEST</version>
    </dependency>

Initialize a Credentials client

You can use one of the following methods to initialize a Credentials client based on your business requirements:

Important

If you use a plaintext AccessKey pair in a project, the AccessKey pair may be leaked due to improper permission management on the code repository. This may threaten the security of all resources within the account to which the AccessKey pair belongs. We recommend that you store the AccessKey pair in environment variables or configuration files.

Method 1: Use the default credential provider chain

If you do not specify a method to initialize a Credentials client, the default credential provider chain is used. For more information, see the Default credential provider chain section of this topic.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
    public static void main(String[] args) throws Exception{
        // Do not specify a method to initialize a Credentials client.
        Config credentialConfig = new Config();
        Client credentialClient = new Client(credentialConfig);
    }
}

Call example

You can use the default credential provider chain to automatically create access credentials and call the API operations of Alibaba Cloud services without using a hard-coded AccessKey pair.

The following sample code provides an example on how to call the DescribeRegions operation of Elastic Compute Service (ECS). Before you call this operation, you must install ECS SDK for Java.

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // Use the default credential to initialize a Credentials client. 
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();

        Config ecsConfig = new Config();
        // Specify the endpoint of ECS. 
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        // Use the SDK Credentials package to configure a credential. 
        ecsConfig.setCredential(credentialClient);
        // Initialize the ECS SDK client. 
        Client ecsClient = new Client(ecsConfig);
        // Initialize the request to call the DescribeRegions operation. 
        DescribeRegionsRequest describeInstancesRequest = new DescribeRegionsRequest();
        // Initialize the runtime configurations. 
        RuntimeOptions runtime = new RuntimeOptions();
        // Call the DescribeRegions operation and obtain a response. 
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeInstancesRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

Method 2: Use an AccessKey pair

You can create an AccessKey pair that is used to call API operations for your Alibaba Cloud account or a RAM user. For more information, see Create an AccessKey pair. Then, you can use the AccessKey pair to initialize a Credentials client.

Warning

An Alibaba Cloud account has full permissions on resources within the account. AccessKey pair leaks of an Alibaba Cloud account pose critical threats to the system.

Therefore, we recommend that you use an AccessKey pair of a RAM user that is granted permissions based on the principle of least privilege to initialize a Credentials client.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
    public static void main(String[] args) throws Exception{
        Config credentialConfig = new Config();
        credentialConfig.setType("access_key");
        credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        Client credentialClient = new Client(credentialConfig);
    }
}

Call example

You can use the Credentials tool to read an AccessKey pair and call the API operations of Alibaba Cloud services.

The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java.

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // Use an AccessKey pair to initialize a Credentials client. 
        com.aliyun.credentials.models.Config credentialsConfig = new com.aliyun.credentials.models.Config();
        // Specify the type of the credential. 
        credentialsConfig.setType("access_key");
        // Specify the AccessKey ID. 
        credentialsConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // Specify the AccessKey secret. 
        credentialsConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialsConfig);

        Config ecsConfig = new Config();
        // Specify the endpoint of ECS. 
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        // Use the SDK Credentials package to configure a credential. 
        ecsConfig.setCredential(credentialClient);
        // Initialize the ECS SDK client. 
        Client ecsClient = new Client(ecsConfig);
        // Initialize the request to call the DescribeRegions operation. 
        DescribeRegionsRequest describeInstancesRequest = new DescribeRegionsRequest();
        // Initialize the runtime configurations. 
        RuntimeOptions runtime = new RuntimeOptions();
        // Call the DescribeRegions operation and obtain a response. 
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeInstancesRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

Method 3: Use an STS token

You can call the AssumeRole operation of STS as a RAM user to obtain an STS token. You can specify the maximum validity period of the STS token. The following example shows how to initialize a Credentials client by using an STS token. The example does not show how to obtain an STS token.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
    public static void main(String[] args) {
        Config credentialConfig = new Config();
        credentialConfig.setType("sts");
        // Obtain the AccessKey ID from the environment variable.
        credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // Obtain the AccessKey secret from the environment variable.
        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // Obtain the temporary STS token from the environment variable.
        credentialConfig.setSecurityToken(System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN"));
        Client credentialClient = new Client(credentialConfig);
    }
}

Call example

You can use the Credentials tool to read an STS token and call the API operations of Alibaba Cloud services.

The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java and STS SDK for Java.

import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.sts20150401.Client;
import com.aliyun.sts20150401.models.AssumeRoleRequest;
import com.aliyun.sts20150401.models.AssumeRoleResponse;
import com.aliyun.sts20150401.models.AssumeRoleResponseBody;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // Create an StsClient object and call the AssumeRole operation to obtain an STS token.
        Config config = new Config()
                // Obtain the AccessKey ID from the environment variable.
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Obtain the AccessKey secret from the environment variable.
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")); 
        config.endpoint = "sts.cn-hangzhou.aliyuncs.com";
        Client client = new Client(config);
        AssumeRoleRequest assumeRoleRequest = new AssumeRoleRequest()
                // Specify the Alibaba Cloud Resource Name (ARN) of the RAM role that you want your application to assume by specifying the ALIBABA_CLOUD_ROLE_ARN environment variable. Example: acs:ram::123456789012****:role/adminrole.
                .setRoleArn("<RoleArn>")
                // Specify the role session name by specifying the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
                .setRoleSessionName("<RoleSessionName>"); 
        RuntimeOptions runtime = new RuntimeOptions();
        AssumeRoleResponse assumeRoleResponse = client.assumeRoleWithOptions(assumeRoleRequest, runtime);
        AssumeRoleResponseBody.AssumeRoleResponseBodyCredentials assumeRoleResponseBodyCredentials = assumeRoleResponse.body.credentials;

        // Use an STS token to initialize a Credentials client. 
        com.aliyun.credentials.models.Config credentialsConfig = new com.aliyun.credentials.models.Config();
        credentialsConfig.setType("sts"); // Specify the type of the credential. 
        credentialsConfig.setAccessKeyId(assumeRoleResponseBodyCredentials.accessKeyId);
        credentialsConfig.setAccessKeySecret(assumeRoleResponseBodyCredentials.accessKeySecret);
        credentialsConfig.setSecurityToken(assumeRoleResponseBodyCredentials.securityToken);
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialsConfig);

        // Use the Credentials tool to create an ECS client. 
        Config ecsConfig = new Config();
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        ecsConfig.setCredential(credentialClient);
        com.aliyun.ecs20140526.Client ecsClient = new com.aliyun.ecs20140526.Client(ecsConfig);
        DescribeRegionsRequest describeInstancesRequest = new DescribeRegionsRequest();
        RuntimeOptions describeRegionsRuntime = new RuntimeOptions();

        // Call the DescribeRegions operation and obtain a response. 
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeInstancesRequest, describeRegionsRuntime);
        System.out.println(response.body.toMap());
    }
}

Method 4: Use an AccessKey pair and a RAM role

The underlying logic of this method is to use an STS token to initialize a Credentials client. After you specify the ARN of a RAM role, the Credentials tool can obtain an STS token from STS. You can also use the setPolicy method to limit the permissions of the RAM role.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
  public static void main(String[] args) throws Exception {
    Config credentialConfig = new Config();
    credentialConfig.setType("ram_role_arn");
    credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
    credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
    // Specify the ARN of the RAM role that you want your application to assume by specifying the ALIBABA_CLOUD_ROLE_ARN environment variable. Example: acs:ram::123456789012****:role/adminrole.
    credentialConfig.setRoleArn("<RoleArn>");
    // Specify the role session name by specifying the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
    credentialConfig.setRoleSessionName("<RoleSessionName>");
    // Optional. Specify limited permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
    credentialConfig.setPolicy("<Policy>");
    // Not required, the external ID of the RAM role
    // This parameter is provided by an external party and is used to prevent the confused deputy problem.
    credentialConfig.setExternalId("<ExternalId>");
    credentialConfig.setRoleSessionExpiration(3600);
    Client credentialClient = new Client(credentialConfig);
  }
}

Call example

The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java.

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // Use an AccessKey pair and a RAM role to initialize the Credentials client.
        com.aliyun.credentials.models.Config credentialsConfig = new com.aliyun.credentials.models.Config();
        // Specify the type of the credential.
        credentialsConfig.setType("ram_role_arn");
        // Obtain the AccessKey ID from the environment variable.
        credentialsConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // Obtain the AccessKey secret from the environment variable.
        credentialsConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // Specify the ARN of the RAM role that you want your application to assume by specifying the ALIBABA_CLOUD_ROLE_ARN environment variable. Example: acs:ram::123456789012****:role/adminrole.
        credentialsConfig.setRoleArn("<RoleArn>");
        // Specify the role session name by specifying the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
        credentialsConfig.setRoleSessionName("<RoleSessionName>");
        // Optional. Specify limited permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
        credentialsConfig.setPolicy("<Policy>");
        // Not required, the external ID of the RAM role
        // This parameter is provided by an external party and is used to prevent the confused deputy problem.
        credentialsConfig.setExternalId("<ExternalId>");
        // Specify the validity period of the session.
        credentialsConfig.setRoleSessionExpiration(3600);
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialsConfig);

        // Use the Credentials tool to initialize the ECS client. 
        Config ecsConfig = new Config();
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        ecsConfig.setCredential(credentialClient);
        Client ecsClient = new Client(ecsConfig);
        DescribeRegionsRequest describeInstancesRequest = new DescribeRegionsRequest();
        RuntimeOptions runtime = new RuntimeOptions();
        // Call the DescribeRegions operation and obtain a response. 
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeInstancesRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

Method 5: Use the RAM role of an ECS instance

You can attach a RAM role to an ECS instance or elastic container instance. The Credentials tool automatically obtains the RAM role attached to the instance and uses the metadata server to obtain the STS token of the RAM role. The STS token is then used to initialize a Credentials client.

The metadata server supports access in normal mode (IMDSv1) and security hardening mode (IMDSv2). By default, the Credentials tool obtains access credentials from the metadata server in security hardening mode. If an exception occurs in the security hardening mode, you can configure the DisableIMDSv1 parameter to specify an exception handling logic. Valid values of the DisableIMDSv1 parameter:

  1. false (default): The Credentials tool continues to obtain the access credential in normal mode.

  2. true: The exception is thrown and the Credentials tool continues to obtain the access credential in security hardening mode.

The configurations for the metadata server determine whether the server supports the security hardening mode.

Note
import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("ecs_ram_role");
        // Optional. Specify the name of the RAM role of the ECS instance by specifying the ALIBABA_CLOUD_ECS_METADATA environment variable. If you do not specify this parameter, the value is automatically obtained. We recommend that you specify this parameter to reduce the number of requests.
        credentialConfig.setRoleName("<RoleName>");
        // Set the DisableIMDSv1 parameter to true, which indicates that the security hardening mode is forcibly used. The default value is false, which indicates that the system first tries to obtain the access credential in security hardening mode. If the access credential fails to be obtained, the normal mode is used. 
        // credentialConfig.setDisableIMDSv1(true);
        Client credentialClient = new Client(credentialConfig);
    }
}

Call example

The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java.

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // Use the RAM role of an ECS instance to initialize a Credentials client. 
        com.aliyun.credentials.models.Config credentialsConfig = new com.aliyun.credentials.models.Config();
        // Specify the type of the credential. 
        credentialsConfig.setType("ecs_ram_role");
        // Optional. Specify the name of the RAM role of the ECS instance by specifying the ALIBABA_CLOUD_ECS_METADATA environment variable. If you do not specify this parameter, the value is automatically obtained. We recommend that you specify this parameter to reduce the number of requests.
        credentialsConfig.setRoleName("<RoleName>");

        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialsConfig);

        Config ecsConfig = new Config();
        // Specify the endpoint of ECS. 
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        // Use the SDK Credentials package to configure a credential. 
        ecsConfig.setCredential(credentialClient);
        // Initialize the ECS SDK client. 
        Client ecsClient = new Client(ecsConfig);
        // Initialize the request to call the DescribeRegions operation. 
        DescribeRegionsRequest describeInstancesRequest = new DescribeRegionsRequest();
        // Initialize the runtime configurations. 
        RuntimeOptions runtime = new RuntimeOptions();
        // Call the DescribeRegions operation and obtain a response. 
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeInstancesRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

Method 6: Use the RAM role of an OIDC IdP

After you attach a RAM role to a worker node in a Container Service for Kubernetes cluster, applications in the pods on the worker node can use the metadata server to obtain an STS token in the same way as the applications on ECS instances. However, if an untrusted application is deployed on the worker node, such as an application that is submitted by your customer and whose code is unavailable to you, you may not want the application to use the metadata server to obtain an STS token of the RAM role attached to the worker node. To ensure the security of cloud resources and enable untrusted applications to securely obtain required STS tokens, you can use the RAM Roles for Service Accounts (RRSA) feature to grant minimum necessary permissions to an application. In this case, the ACK cluster creates a service account OpenID Connect (OIDC) token file, associates the token file with a pod, and then injects relevant environment variables into the pod. Then, the Credentials tool uses the environment variables to call the AssumeRoleWithOIDC operation of STS to obtain an STS token of the RAM role. For more information about the RRSA feature, see Use RRSA to authorize different pods to access different cloud services.

The following environment variables are injected into the pod:

ALIBABA_CLOUD_ROLE_ARN: the ARN of the RAM role.

ALIBABA_CLOUD_OIDC_PROVIDER_ARN: the ARN of the OIDC identity provider (IdP).

ALIBABA_CLOUD_OIDC_TOKEN_FILE: the path of the OIDC token file.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {

  public static void main(String[] args) throws Exception {
    Config credentialConfig = new Config();
    credentialConfig.setType("oidc_role_arn");
    // Specify the ARN of the RAM role by specifying the ALIBABA_CLOUD_ROLE_ARN environment variable.
    credentialConfig.setRoleArn("<RoleArn>");
    // Specify the ARN of the OIDC IdP by specifying the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
    credentialConfig.setOidcProviderArn("<OidcProviderArn>");
    // Specify the path of the OIDC token file by specifying the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
    credentialConfig.setOidcTokenFilePath("<OidcTokenFilePath>");
    // Specify the role session name by specifying the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
    credentialConfig.setRoleSessionName("<RoleSessionName>");
    // Optional. Specify limited permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
    credentialConfig.setPolicy("<Policy>");
    // Specify the validity period of the session.
    credentialConfig.setRoleSessionExpiration(3600);
    Client credentialClient = new Client(credentialConfig);
  }
}

Call example

The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java.

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // Use the RAM role of an OIDC IdP to initialize a Credentials client. 
        com.aliyun.credentials.models.Config credentialsConfig = new com.aliyun.credentials.models.Config();
        // Specify the type of the credential. 
        credentialsConfig.setType("oidc_role_arn");
        // Specify the ARN of the OIDC IdP by specifying the ALIBABA_CLOUD_ROLE_ARN environment variable.
        credentialConfig.setRoleArn("<RoleArn>");
        // Specify the ARN of the OIDC IdP by specifying the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
        credentialConfig.setOidcProviderArn("<OidcProviderArn>");
        // Specify the path of the OIDC token file by specifying the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
        credentialConfig.setOidcTokenFilePath("<OidcTokenFilePath>");
        // Specify the role session name by specifying the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
        credentialConfig.setRoleSessionName("<RoleSessionName>");
        // Optional. Specify limited permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
        credentialsConfig.setPolicy("<Policy>");
        // Specify the validity period of the session.
        credentialsConfig.setRoleSessionExpiration(3600);
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialsConfig);

        Config ecsConfig = new Config();
        // Specify the endpoint of ECS. 
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        // Use the SDK Credentials package to configure a credential. 
        ecsConfig.setCredential(credentialClient);
        // Initialize the ECS SDK client. 
        Client ecsClient = new Client(ecsConfig);
        // Initialize the request to call the DescribeRegions operation. 
        DescribeRegionsRequest describeInstancesRequest = new DescribeRegionsRequest();
        // Initialize the runtime configurations. 
        RuntimeOptions runtime = new RuntimeOptions();
        // Call the DescribeRegions operation and obtain a response. 
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeInstancesRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

Method 7: Use a credential URI

The underlying logic of this method is to use an STS token to initialize a Credentials client. The Credentials tool uses the uniform resource identifier (URI) that you provide to obtain an STS token. The STS token is then used to initialize a Credentials client.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("credentials_uri");
        // Specify the URI of the credential in the http://local_or_remote_uri/ format by specifying the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
        credentialConfig.setCredentialsUri("<CredentialsUri>");
        Client credentialClient = new Client(credentialConfig);
    }
}

Call example

To call the API operations of Alibaba Cloud services, you can specify a local or remote URI for credentials and use the Credentials tool to obtain and automatically update an STS token based on the local or remote URI.

To call the operations of an Alibaba Cloud service, you must install dependencies for the Alibaba Cloud service. The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java.

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // Use a URI to initialize a Credentials client. 
        com.aliyun.credentials.models.Config credentialsConfig = new com.aliyun.credentials.models.Config();
        // Specify the type of the credential. 
        credentialsConfig.setType("credentials_uri");
        // Obtain the URI of the credential in the http://local_or_remote_uri/ format by specifying the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
        credentialsConfig.setCredentialsUri("<CredentialsUri>");
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialsConfig);

        Config ecsConfig = new Config();
        // Specify the endpoint of ECS. 
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        // Use the SDK Credentials package to configure a credential. 
        ecsConfig.setCredential(credentialClient);
        // Initialize the ECS SDK client. 
        Client ecsClient = new Client(ecsConfig);
        // Initialize the request to call the DescribeRegions operation. 
        DescribeRegionsRequest describeInstancesRequest = new DescribeRegionsRequest();
        // Initialize the runtime configurations. 
        RuntimeOptions runtime = new RuntimeOptions();
        // Call the DescribeRegions operation and obtain a response. 
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeInstancesRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

Method 8: Use a bearer token

Only Cloud Call Center allows you to use a bearer token to initialize a Credentials client.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("bearer");
        // Enter the bearer token.
        credentialConfig.setBearerToken("<BearerToken>");
        Client credentialClient = new Client(credentialConfig);
    }
}

Call example

The following sample code provides an example on how to call the GetInstance operation of Cloud Call Center. Before you call this operation, you must install Cloud Call Center SDK for Java.

import com.aliyun.ccc20200701.Client;
import com.aliyun.ccc20200701.models.GetInstanceRequest;
import com.aliyun.ccc20200701.models.GetInstanceResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // Use a bearer token to initialize a Credentials client. 
        com.aliyun.credentials.models.Config credentialsConfig = new com.aliyun.credentials.models.Config();
        // Specify the type of the credential. 
        credentialsConfig.setType("bearer");
        // Specify the bearer token that is automatically generated by the server. The bearer token has a validity period. 
        credentialsConfig.setBearerToken("<bearer_token>");
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialsConfig);

        Config cccConfig = new Config();
        // Specify the endpoint of ECS. 
        cccConfig.setEndpoint("ccc.aliyuncs.com");
        // Use the SDK Credentials package to configure a credential. 
        cccConfig.setCredential(credentialClient);
        Client cccClient = new Client(cccConfig);
        GetInstanceRequest getInstanceRequest = new GetInstanceRequest().setInstanceId("ccc-test");
        // Initialize the runtime configurations. 
        RuntimeOptions runtime = new RuntimeOptions();
        GetInstanceResponse response = cccClient.getInstanceWithOptions(getInstanceRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

Default credential provider chain

If you want to use different types of credentials in the development and production environments of your application, you generally need to obtain the environment information from the code and write code branches to obtain different credentials for the development and production environments. The default credential provider chain of Alibaba Cloud Credentials for Java allows you to use the same code to obtain credentials for different environments based on configurations independent of the application. If you use Client client = new Client() to initialize a Credentials client without specifying an initialization method, the Credentials tool obtains the credential information in the following order:

1. Obtain the credential information from system properties

The Credentials tool first obtains the credential information from system properties.

If the alibabacloud.accessKeyId (AccessKey ID) and alibabacloud.accessKeyIdSecret (AccessKey secret) system properties are specified, the Credentials tool uses the specified AccessKey pair as the default credential.

You can add the -Dalibabacloud.accessKeyId=*** and -Dalibabacloud.accessKeyIdSecret=*** properties to specify the credential when you run your Java application.

2. Obtain the credential information from environment variables

If no credentials are found in the previous step, the Credentials tool obtains the credential information from environment variables.

  • If the ALIBABA_CLOUD_ACCESS_KEY_ID (AccessKey ID) and ALIBABA_CLOUD_ACCESS_KEY_SECRET (AccessKey secret) system environment variables are specified, the Credentials tool uses the specified AccessKey pair as the default credential.

  • If the ALIBABA_CLOUD_ACCESS_KEY_ID (AccessKey ID), ALIBABA_CLOUD_ACCESS_KEY_SECRET (AccessKey secret), and ALIBABA_CLOUD_SECURITY_TOKEN (STS token) system environment variables are specified, the Credentials tool uses the specified STS token as the default credential.

3. Obtain the credential information by using the RAM role of an OIDC IdP

If no credentials are found in the previous step, the Credentials tool obtains the values of the following environment variables:

ALIBABA_CLOUD_ROLE_ARN: the ARN of the RAM role.

ALIBABA_CLOUD_OIDC_PROVIDER_ARN: the ARN of the OIDC IdP.

ALIBABA_CLOUD_OIDC_TOKEN_FILE: the path of the OIDC token file.

If the preceding three environment variables are specified, the Credentials tool uses the environment variables to call the AssumeRoleWithOIDC operation of STS to obtain an STS token as the default credential.

4. Obtain the credential information from the config.json file

If no credentials are found in the previous step, the Credentials tool obtains the credential information from the config.json file. The path of the configuration file varies based on the operating system:

Linux: ~/.aliyun/config.json

Windows: C:\Users\USER_NAME\.aliyun\config.json

If the config.json file exists, the application initializes a Credentials client by using credential information that is specified by the current parameter in the config.json file. You can also specify the ALIBABA_CLOUD_PROFILE environment variable to specify the credential information. For example, you can set the ALIBABA_CLOUD_PROFILE environment variable to client1.

The mode parameter in the config.json file specifies the method that is used to obtain the credential information. Valid values:

  • AK: uses the AccessKey pair of a RAM user to obtain the credential information.

  • RamRoleArn: uses the ARN of a RAM role to obtain the credential information.

  • EcsRamRole: uses the RAM role attached to an ECS instance to obtain the credential information.

  • OIDC: uses the ARN of an OIDC IdP and the OIDC token file to obtain the credential information.

  • ChainableRamRoleArn: uses a role chain and specifies an access credential in another JSON file to obtain the credential information.

Configuration example:

{
	"current": "default",
	"profiles": [
		{
			"name": "default",
			"mode": "AK",
			"access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
			"access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>"
		},
		{
			"name":"client1",
			"mode":"RamRoleArn",
			"access_key_id":"<ALIBABA_CLOUD_ACCESS_KEY_ID>",
			"access_key_secret":"<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
			"ram_role_arn":"<ROLE_ARN>",
			"ram_session_name":"<ROLE_SESSION_NAME>",
			"expired_seconds":3600
		},
		{
			"name":"client2",
			"mode":"EcsRamRole",
			"ram_role_name":"<RAM_ROLE_ARN>"
		},
		{
			"name":"client3",
			"mode":"OIDC",
			"oidc_provider_arn":"<OIDC_PROVIDER_ARN>",
			"oidc_token_file":"<OIDC_TOKEN_FILE>",
			"ram_role_arn":"<ROLE_ARN>",
			"ram_session_name":"<ROLE_SESSION_NAME>",
			"expired_seconds":3600
		},
		{
			"name":"client4",
			"mode":"ChainableRamRoleArn",
			"source_profile":"<PROFILE_NAME>",
			"ram_role_arn":"<ROLE_ARN>",
			"ram_session_name":"<ROLE_SESSION_NAME>",
			"expired_seconds":3600
		}
	]
}

5. Obtain the credential information by using the RAM role of an ECS instance

If no credentials are found in the previous step, the Credentials tool obtains the value of the ALIBABA_CLOUD_ECS_METADATA environment variable that specifies the RAM role name of an ECS instance. If the RAM role exists, the application obtains an STS token of the RAM role as the default credential by using the metadata server of ECS in security hardening mode. If an exception occurs in the security hardening mode, the Credentials tool obtains the access credential in normal mode. You can also configure the ALIBABA_CLOUD_IMDSV1_DISABLED environment variable to specify an exception handling logic. Valid values of the environment variable:

  1. false: The Credentials tool continues to obtain the access credential in normal mode.

  2. true: The exception is thrown and the Credentials tool continues to obtain the access credential in security hardening mode.

The configurations for the metadata server determine whether the server supports the security hardening mode.

6. Obtain the credential information by using a credential URI

If no credentials are found in the previous step, the Credentials tool obtains the value of the ALIBABA_CLOUD_CREDENTIALS_URI environment variable that specifies the URI of the credential. If the URI of the credential exists, the application uses the URI of the credential to obtain an STS token as the default credential.

Switch between credentials

You can use one of the following methods to use different credentials to call different API operations in your application:

Use multiple Credentials clients

Initialize multiple Credentials clients to pass different credentials to different request clients.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
    public static void main(String[] args) {
        Config credentialConfig1 = new Config();
        credentialConfig1.setType("access_key");
        credentialConfig1.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        credentialConfig1.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        Client credentialClient1 = new Client(credentialConfig1);

        Config credentialConfig2 = new Config();
        credentialConfig2.setType("sts");
        credentialConfig2.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        credentialConfig2.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        credentialConfig2.setSecurityToken(System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN"));
        Client credentialClient2 = new Client(credentialConfig2);
    }
}

Use the AuthUtils class

If you initialize a Credentials client by using the credential information recorded in a configuration file, you can use the AuthUtils.setClientType method to switch between different credentials. Sample code:

import com.aliyun.credentials.utils.AuthUtils;

public class Sample {
    public static void main(String[] args) {
        // If you do not specify the clientType property of the AuthUtils class, default is used. 
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
        // Switch to the client1 credential.
        AuthUtils.setClientType("client1");
        com.aliyun.credentials.Client credentialClient1 = new com.aliyun.credentials.Client();
        // Switch to the client2 credential.
        AuthUtils.setClientType("client2");
        com.aliyun.credentials.Client credentialClient2 = new com.aliyun.credentials.Client();
    }
}

Call example

The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java.

import com.aliyun.credentials.utils.AuthUtils;
import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // Use the default credential to initialize a Credentials client. 
        com.aliyun.credentials.Client defaultCredentialClient = new com.aliyun.credentials.Client();
        // Use client1 in the configuration file to initialize a Credentials client. 
        AuthUtils.setClientType("client1");
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();

        Config ecsConfig = new Config();
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        // Use the default credential to configure the credential. 
        ecsConfig.setCredential(defaultCredentialClient);
        // Initialize the ECS SDK client. 
        Client ecsClient = new Client(ecsConfig);
        // Initialize the request to call the DescribeRegions operation. 
        DescribeRegionsRequest describeRegionsRequest = new DescribeRegionsRequest();
        // Initialize the runtime configurations. 
        RuntimeOptions runtime = new RuntimeOptions();
        // Call the DescribeRegions operation and obtain a response. 
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

References