Alibaba Cloud SDK:Manage credentials

Method 1: Default credential chain

If you do not pass any configuration parameters when initializing the Credentials tool, it retrieves credentials from the default credential chain. To use this method, ensure that your application's runtime environment is configured with at least one of the credential retrieval methods supported by the default credential chain.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.CredentialModel;
public class DemoTest {
    public static void main(String[] args) throws Exception {
        // If no configuration parameters are specified, the tool retrieves credentials from the default credential chain.
        Client credentialClient = new Client();
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        // If you are using a cloud product V2.0 SDK, use com.aliyun.teaopenapi.models.Config to pass the credential.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // The code for initializing the cloud product client with the config object is omitted.
    }
}

Method 2: AK

The Credentials tool uses the AccessKey you provide as the access credential.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;
public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("access_key");
        // Required. This example retrieves the AccessKey ID from an environment variable.
        credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // Required. This example retrieves the AccessKey secret from an environment variable.
        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        Client credentialClient = new Client(credentialConfig);
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        // If you are using a cloud product V2.0 SDK, use com.aliyun.teaopenapi.models.Config to pass the credential.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // The code for initializing the cloud product client with the config object is omitted.
    }
}

Method 3: STS token

The Credentials tool uses the static STS token you provide as the access credential.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;
public class DemoTest {
    public static void main(String[] args) {
        Config credentialConfig = new Config();
        credentialConfig.setType("sts");
        // Required. This example retrieves the AccessKey ID from an environment variable.
        credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // Required. This example retrieves the AccessKey secret from an environment variable.
        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // Required. This example retrieves the temporary security token from an environment variable.
        credentialConfig.setSecurityToken(System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN"));
        Client credentialClient = new Client(credentialConfig);
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        // If you are using a cloud product V2.0 SDK, use com.aliyun.teaopenapi.models.Config to pass the credential.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // The code for initializing the cloud product client with the config object is omitted.
    }
}

Method 4: AK and RAM role ARN

The Credentials tool uses your AK and RAM role ARN to call the AssumeRole API and obtain an STS token, which serves as the access credential. Credentials obtained this way support automatic refresh. For more information, see Automatic refresh of session credentials.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;
public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("ram_role_arn");
        // Required. This example retrieves the AccessKey ID from an environment variable.
        credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // Required. This example retrieves the AccessKey secret from an environment variable.
        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // Optional. Allows the use of temporary credentials to assume another RAM role.
        credentialConfig.setSecurityToken(System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN"));
        // Required. The ARN of the RAM role to assume. Example: acs:ram::123456789012****:role/adminrole. You can also set this by using the ALIBABA_CLOUD_ROLE_ARN environment variable.
        credentialConfig.setRoleArn("<RoleArn>");
        // Optional. The role session name. Default format: credentials-java-. You can also set this by using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
        credentialConfig.setRoleSessionName("<RoleSessionName>");
        // Optional. A more restrictive permission policy. Not required. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
        credentialConfig.setPolicy("<Policy>");
        // Optional. An external ID to prevent the confused deputy problem.
        credentialConfig.setExternalId("<ExternalId>");
        // Optional. The session expiration time in seconds. Default value: 3600.
        credentialConfig.setRoleSessionExpiration(3600);
        Client credentialClient = new Client(credentialConfig);
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        // If you are using a cloud product V2.0 SDK, use com.aliyun.teaopenapi.models.Config to pass the credential.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // The code for initializing the cloud product client with the config object is omitted.
    }
}

Method 5: ECS instance RAM role

If your application runs on an Elastic Compute Service (ECS) or Elastic Container Instance (ECI) instance with an assigned RAM role, the Credentials tool retrieves an STS token from the instance metadata to use as the access credential. When accessing instance metadata, the tool first retrieves the name of the RAM role assigned to the instance. You can specify the RAM role name by using the roleName parameter or the ALIBABA_CLOUD_ECS_METADATA environment variable to reduce retrieval time and improve efficiency. Credentials obtained this way support automatic refresh. For more information, see Automatic refresh of session credentials.

By default, the Credentials tool accesses instance metadata in secured mode (IMDSv2). If this access fails, use the disableIMDSv1 parameter or the ALIBABA_CLOUD_IMDSV1_DISABLED environment variable to control the fallback behavior:

• If set to false (default), the tool falls back to normal mode to retrieve the credential.

• If set to true, the tool only uses secured mode and throws an exception if access fails.

Whether your server supports IMDSv2 depends on its configuration.

To disable credential access from instance metadata, set the ALIBABA_CLOUD_ECS_METADATA_DISABLED=true environment variable.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;
public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("ecs_ram_role");
        // Optional. The name of the RAM role granted to the ECS instance. If not specified, the tool retrieves it automatically. We recommend setting this parameter to reduce the number of requests. You can also set this by using the ALIBABA_CLOUD_ECS_METADATA environment variable.
        credentialConfig.setRoleName("<RoleName>");
        // Optional. Set to true to enforce secured mode. Default value: false. The tool first attempts to get credentials in secured mode. If it fails, it falls back to normal mode.
        credentialConfig.setDisableIMDSv1(false);
        Client credentialClient = new Client(credentialConfig);
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        // If you are using a cloud product V2.0 SDK, use com.aliyun.teaopenapi.models.Config to pass the credential.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // The code for initializing the cloud product client with the config object is omitted.
    }
}

Method 6: OIDC role ARN

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;
public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("oidc_role_arn");
        // Required. The RAM role ARN. You can also set this by using the ALIBABA_CLOUD_ROLE_ARN environment variable.
        credentialConfig.setRoleArn("<RoleArn>");
        // Required. The ARN of the OIDC identity provider. You can also set this by using the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
        credentialConfig.setOidcProviderArn("<OidcProviderArn>");
        // Required. The OIDC token file path. You can also set this by using the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
        credentialConfig.setOidcTokenFilePath("<OidcTokenFilePath>");
        // Optional. The role session name. You can also set this by using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
        credentialConfig.setRoleSessionName("<RoleSessionName>");
        // Optional. A more restrictive permission policy. Not required. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
        credentialConfig.setPolicy("<Policy>");
        // Optional. The session expiration time in seconds. Default value: 3600.
        credentialConfig.setRoleSessionExpiration(3600);
        Client credentialClient = new Client(credentialConfig);
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        // If you are using a cloud product V2.0 SDK, use com.aliyun.teaopenapi.models.Config to pass the credential.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // The code for initializing the cloud product client with the config object is omitted.
    }
}

Method 7: Credentials URI

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;
public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("credentials_uri");
        // Required. The URI for retrieving external credentials. Format: http://local_or_remote_uri/. You can also set this by using the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
        credentialConfig.setCredentialsUri("<CredentialsUri>");
        Client credentialClient = new Client(credentialConfig);
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        // If you are using a cloud product V2.0 SDK, use com.aliyun.teaopenapi.models.Config to pass the credential.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // The code for initializing the cloud product client with the config object is omitted.
    }
}

Method 8: Bearer token

Currently, only Alibaba Cloud Call Center (CCC) supports bearer token authentication.

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;
public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("bearer");
        // Required. Enter your bearer token.
        credentialConfig.setBearerToken("<BearerToken>");
        Client credentialClient = new Client(credentialConfig);
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        // If you are using the CCC V2.0 SDK, use com.aliyun.teaopenapi.models.Config to pass the credential.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // The code for initializing the cloud product client with the config object is omitted.
    }
}

1. System properties

The provider chain first checks for a credential in Java system properties.

• If the alibabacloud.accessKeyId and alibabacloud.accessKeySecret system properties are defined, the provider chain uses an AccessKey as the default credential.

• If the alibabacloud.accessKeyId, alibabacloud.accessKeySecret, and alibabacloud.sessionToken system properties are defined, the provider chain uses an STS token as the default credential.

You can specify these values by adding the following JVM parameters when you run your Java program:

-Dalibabacloud.accessKeyId=your-access-key-id -Dalibabacloud.accessKeySecret=your-access-key-secret

2. Environment variables

3. OIDC RAM role

4. Shared credentials file

{
  "current": "<PROFILE_NAME>",
  "profiles": [
    {
      "name": "<PROFILE_NAME>",
      "mode": "AK",
      "access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
      "access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>"
    },
    {
      "name": "<PROFILE_NAME1>",
      "mode": "StsToken",
      "access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
      "access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
      "sts_token": "<SECURITY_TOKEN>"
    },
    {
      "name":"<PROFILE_NAME2>",
      "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":"<PROFILE_NAME3>",
      "mode":"EcsRamRole",
      "ram_role_name":"<RAM_ROLE_ARN>"
    },
    {
      "name":"<PROFILE_NAME4>",
      "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":"<PROFILE_NAME5>",
      "mode":"ChainableRamRoleArn",
      "source_profile":"<PROFILE_NAME>",
      "ram_role_arn":"<ROLE_ARN>",
      "ram_session_name":"<ROLE_SESSION_NAME>",
      "expired_seconds":3600
    }
  ]
}

5. Instance RAM role

6. CredentialsURI

Session credential types, such as ram_role_arn, ecs_ram_role, oidc_role_arn, and credentials_uri, support automatic refresh through a built-in mechanism in the credential provider. When a credential client retrieves a credential for the first time, the provider stores it in a cache. In subsequent operations, the same client instance automatically retrieves the credential from this cache. If the cached credential has expired, the client instance fetches a new one and updates the cache accordingly.

The following example uses the singleton pattern to create a credential client. It demonstrates the refresh mechanism by fetching a credential at different time intervals and calling an OpenAPI operation to verify that the credential is usable.

Analysis based on the log output:

• On the first call, the cache is empty. The system retrieves a credential based on your configuration and then stores it in the cache.

• The second call uses the same credential as the first, indicating it was retrieved from the cache.

• On the third call, the cached credential has expired. Its expiration time (RoleSessionExpiration) is 3,600 seconds, but this call is made 4,200 seconds after the first one. Consequently, the SDK's automatic refresh mechanism fetches a new credential and updates the cache.

• The fourth call uses the same credential as the third, confirming that the cache was updated.