Securely call OpenAPI by configuring Credentials (Go SDK) - Alibaba Cloud SDK

When you call API operations to manage cloud resources using Alibaba Cloud SDKs, you must configure valid credential information. The Credentials tool of Alibaba Cloud provides a set of easy-to-use features and supports various types of credentials, including the default credential, AccessKey pairs, and Security Token Service (STS) tokens. The Credentials tool helps you obtain and manage credentials. This topic describes how to configure different types of credentials and 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 a user provides to prove their identity. When a user logs on to a system, they must provide the correct credentials to be authenticated. Common credential types include the following:

The permanent AccessKey (AK) for an Alibaba Cloud account or a Resource Access Management (RAM) user. An AK is a key pair that consists of an AccessKey ID and an AccessKey secret.
The temporary Security Token Service (STS) token for an Alibaba Cloud RAM role. This is a temporary identity credential with a custom time-to-live (TTL) and access permissions. For more information, see What is STS?.
A Bearer Token. This is a token type for authentication and authorization.

Prerequisites

Go version 1.10.x or later is required to use the Credentials tool.
Use an Alibaba Cloud SDK for Go V2.0. For more information, see Use Alibaba Cloud SDK for Go in an IDE.

Install the Credentials tool

If you have already installed the Credentials tool, you can skip this step. We recommend that you use the latest version of the Credentials dependency package to ensure that all credential types are supported. You can view information about all published versions in Credentials.

You can install the Credentials tool in one of the following ways:

Method 1: You can run the go get command to download and install the tool.
```
$ go get -u github.com/aliyun/credentials-go
```
Method 2: If you use dep to manage dependency packages, you can run the following command:
```
dep ensure -add github.com/aliyun/credentials-go
```

Credentials tool configuration parameters

The configuration parameters for the Credentials tool are defined in the Config struct of the github.com/aliyun/credentials-go/credentials package. The credential type is specified by the required type parameter. After you determine the credential type, you can select the appropriate parameters for that type. The following table describes the valid values for type and the parameters supported by each credential type. In the table, √ indicates a required parameter, - indicates an optional parameter, and × indicates an unsupported parameter.

Note

Credential types and parameters not listed in the following table are no longer recommended for use.

Type	access_key	sts	ram_role_arn	ecs_ram_role	oidc_role_arn	credentials_uri	bearer
AccessKeyId: The ID of the access credential.	√	√	√	×	×	×	×
AccessKeySecret: The secret of the access credential.	√	√	√	×	×	×	×
SecurityToken: The STS token.	×	√	-	×	×	×	×
RoleArn: The Alibaba Cloud Resource Name (ARN) of the RAM role.	×	×	√	×	√	×	×
RoleSessionName: A custom session name. The default format is `credentials-go-current_timestamp`.	×	×	-	×	-	×	×
RoleName: The name of the RAM role.	×	×	×	-	×	×	×
DisableIMDSv1: Specifies whether to enforce the secure mode. The default value is `false`.	×	×	×	-	×	×	×
BearerToken: The bearer token.	×	×	×	×	×	×	√
Policy: A custom permission policy.	×	×	-	×	-	×	×
RoleSessionExpiration: The session expiration time. The default value is 3600 seconds.	×	×	-	×	-	×	×
OIDCProviderArn: The ARN of the OIDC IdP.	×	×	×	×	√	×	×
OIDCTokenFilePath: The file path of the OIDC token.	×	×	×	×	√	×	×
ExternalId: The external ID of the role. This parameter is used to prevent the confused deputy problem. For more information, see Use an external ID to prevent the confused deputy problem.	×	×	-	×	×	×	×
Url: The URI of the credential. This parameter must be assigned a value using SetURLCredential(v string).	×	×	×	×	×	√	×
STSEndpoint: The endpoint of STS. VPC endpoints and public network endpoints are supported. For a list of valid values, see Endpoints. The default value is `sts.aliyuncs.com`.	×	×	-	×	-	×	×
Timeout: The read timeout for HTTP requests. The default value is 5000 milliseconds.	×	×	-	-	-	-	×
ConnectTimeout: The connection timeout for HTTP requests. The default value is 10000 milliseconds.	×	×	-	-	-	-	×

Initialize the credential client

You can use one of the following methods to initialize a Credentials client as needed:

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.
We recommend that you initialize the Credentials client in single-instance mode. This mode not only enables the credential caching feature of the SDK, but also effectively prevents traffic control issues and waste of performance resources caused by multiple API calls. For more information, see the Automatic update mechanism of session credentials section of this topic.

Method 1: Use the default credential provider chain

When you initialize the credential client without passing any parameters, the Credentials tool initializes the client using the default credential provider chain. For more information about the logic for reading the default credential, see Default credential provider chain.

package main

import (
	"fmt"
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	"github.com/aliyun/credentials-go/credentials"
)

func main() {
	// Do not specify parameters or pass nil.
	credential, err := credentials.NewCredential(nil)
	
	config := &openapi.Config{}
        config.Credential = credential
        // The code for initializing a cloud product client using the config is omitted. For more information, see the API call example.
}

API call example

This example shows how to call the DescribeRegions operation of Elastic Compute Service (ECS). You must first install the ECS SDK.

package main

import (
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	ecs20140526 "github.com/alibabacloud-go/ecs-20140526/v7/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
	"github.com/aliyun/credentials-go/credentials"
)

func main() {
	// Initialize the Credentials client with the default credential.
	credentialClient, _err := credentials.NewCredential(nil)
	if _err != nil {
		panic(_err)
	}

	ecsConfig := &openapi.Config{}
	// Configure the endpoint of the cloud product.
	ecsConfig.Endpoint = tea.String("ecs.cn-beijing.aliyuncs.com")
	// Configure the credential using Credentials.
	ecsConfig.Credential = credentialClient
	// Initialize the ECS client.
	ecsClient, _err := ecs20140526.NewClient(ecsConfig)
	// Initialize the DescribeRegions request.
	describeInstancesRequest := &ecs20140526.DescribeRegionsRequest{}
	// Initialize the runtime configurations.
	runtime := &util.RuntimeOptions{}
	// Call the DescribeRegions operation and obtain the response.
	response, _err := ecsClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime)
	if _err != nil {
		panic(_err)
	}
	panic(response.Body.String())
}

Method 2: Use an AK

This method lets you create an AccessKey pair to initialize a Credentials client. For more information, see Create an AccessKey pair.

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 (PoLP) to initialize a Credentials client.

import (
	"fmt"
	"os"
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	"github.com/aliyun/credentials-go/credentials"
)

func main() {
	config := new(credentials.Config).
		SetType("access_key").
		SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
		SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))

	akCredential, err := credentials.NewCredential(config)
	if err != nil {
		return
	}
	
	config := &openapi.Config{}
        config.Credential = akCredential
        // The code for initializing a cloud product client using the config is omitted. For more information, see the API call example.
}

API call example

This example shows how to call the DescribeRegions operation of ECS. You must first install the ECS SDK.

package main

import (
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	ecs20140526 "github.com/alibabacloud-go/ecs-20140526/v7/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
	"github.com/aliyun/credentials-go/credentials"
	"os"
)

func main() {
	// Initialize the Credentials client with an AK.
	credentialsConfig := new(credentials.Config).
		// The credential type.
		SetType("access_key").
		// The AccessKey ID.
		SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
		// The AccessKey secret.
		SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
	credentialClient, _err := credentials.NewCredential(credentialsConfig)
	if _err != nil {
		panic(_err)
	}

	ecsConfig := &openapi.Config{}
	// Configure the endpoint of the cloud product.
	ecsConfig.Endpoint = tea.String("ecs.cn-beijing.aliyuncs.com")
	// Configure the credential using Credentials.
	ecsConfig.Credential = credentialClient
	// Initialize the ECS client.
	ecsClient, _err := ecs20140526.NewClient(ecsConfig)
	// Initialize the DescribeRegions request.
	describeInstancesRequest := &ecs20140526.DescribeRegionsRequest{}
	// Initialize the runtime configurations.
	runtime := &util.RuntimeOptions{}
	// Call the DescribeRegions operation and obtain the response.
	response, _err := ecsClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime)
	if _err != nil {
		panic(_err)
	}
	panic(response.Body.String())
}

Method 3: Use an STS token

This method lets you use a static STS token to initialize a Credentials client. For more information about how to obtain an STS token, see What is STS? The following example shows how to initialize a Credentials client using an STS token. The example does not show how to obtain an STS token.

package main

import (
	"fmt"
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	"github.com/aliyun/credentials-go/credentials"
	"os"
)

func main() {
	config := new(credentials.Config).
		SetType("sts").
		// Obtain the AccessKey ID from an environment variable.
		SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
		// Obtain the AccessKey secret from an environment variable.
		SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")).
		// Obtain the temporary STS credential from an environment variable.
		SetSecurityToken(os.Getenv("ALIBABA_CLOUD_SECURITY_TOKEN"))

	stsCredential, err := credentials.NewCredential(config)
	if err != nil {
		return
	}
	
	config := &openapi.Config{}
        config.Credential = stsCredential
        // The code for initializing a cloud product client using the config is omitted. For more information, see the API call example.
}

API call example

This example shows how to call the DescribeRegions operation of ECS. You must first install the Elastic Compute Service SDK and the Security Token Service SDK.

package main

import (
	"os"

	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	ecs20140526 "github.com/alibabacloud-go/ecs-20140526/v7/client"
	sts20150401 "github.com/alibabacloud-go/sts-20150401/v2/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
	"github.com/aliyun/credentials-go/credentials"
)

func main() {
	// Create an STS client and call the AssumeRole operation to obtain an STS token.
	stsConfig := &openapi.Config{}
	stsConfig.SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
	stsConfig.SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
	stsConfig.SetEndpoint("sts.cn-hangzhou.aliyuncs.com")
	client, _err := sts20150401.NewClient(stsConfig)
	if _err != nil {
		panic(_err)
	}
	assumeRoleRequest := &sts20150401.AssumeRoleRequest{}
	// The ARN of the RAM role to assume. Example: acs:ram::123456789012****:role/adminrole. You can set RoleArn using the ALIBABA_CLOUD_ROLE_ARN environment variable.
	assumeRoleRequest.SetRoleArn("<RoleArn>")
	// The name of the role session. You can set RoleSessionName using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
	assumeRoleRequest.SetRoleSessionName("<RoleSessionName>")
	assumeRoleRequest.SetDurationSeconds(3600)
	result, _err := client.AssumeRole(assumeRoleRequest)
	if _err != nil {
		panic(_err)
	}
	assumeRoleResponseBodyCredentials := result.Body.Credentials

	// Initialize the Credentials client with an STS token.
	credentialsConfig := new(credentials.Config).
		// The credential type.
		SetType("sts").
		SetAccessKeyId(*assumeRoleResponseBodyCredentials.AccessKeyId).
		SetAccessKeySecret(*assumeRoleResponseBodyCredentials.AccessKeySecret).
		SetSecurityToken(*assumeRoleResponseBodyCredentials.SecurityToken)

	credentialClient, _err := credentials.NewCredential(credentialsConfig)
	if _err != nil {
		panic(_err)
	}

	ecsConfig := &openapi.Config{}
	// Configure the endpoint of the cloud product.
	ecsConfig.Endpoint = tea.String("ecs.cn-hangzhou.aliyuncs.com")
	// Configure the credential using Credentials.
	ecsConfig.Credential = credentialClient
	// Initialize the ECS client.
	ecsClient, _err := ecs20140526.NewClient(ecsConfig)
	// Initialize the DescribeRegions request.
	describeInstancesRequest := &ecs20140526.DescribeRegionsRequest{}
	// Initialize the runtime configurations.
	runtime := &util.RuntimeOptions{}
	// Call the DescribeRegions operation and obtain the response.
	response, _err := ecsClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime)
	if _err != nil {
		panic(_err)
	}
	panic(response.Body.String())
}

Method 4: Use an AK and RamRoleArn

This method is implemented using an STS token. By specifying the Amazon Resource Name (ARN) of a RAM role, the Credentials tool can help developers obtain an STS token from STS. You can also assign a value to SetPolicy to restrict the RAM role to a smaller set of permissions.

package main

import (
	"fmt"
	"os"
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	"github.com/aliyun/credentials-go/credentials"
)

func main() {
	config := new(credentials.Config).
		SetType("ram_role_arn").
		SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
		SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")).
		// The ARN of the RAM role to assume. Example: acs:ram::123456789012****:role/adminrole. You can set RoleArn using the ALIBABA_CLOUD_ROLE_ARN environment variable.
		SetRoleArn("<RoleArn>").
		// The name of the role session. You can set RoleSessionName using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
		SetRoleSessionName("<RoleSessionName>").
		// Optional. A smaller permission policy. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
		SetPolicy("<Policy>").
		// Optional. The session expiration time.
		SetRoleSessionExpiration(3600).
		// Optional. The external ID of the role. This parameter is provided by an external party to represent the role and is used to prevent the confused deputy problem.
		SetExternalId("ExternalId").
		// Optional. The default value is sts.aliyuncs.com. We recommend that you use a region-specific STS domain name. Select a region that is geographically closer to you to ensure network connectivity.
		SetSTSEndpoint("sts.cn-hangzhou.aliyuncs.com")

	arnCredential, err := credentials.NewCredential(config)
	if err != nil {
		return
	}

	config := &openapi.Config{}
        config.Credential = arnCredential
        // The code for initializing a cloud product client using the config is omitted. For more information, see the API call example.
}

Note

For more information about ExternalId, see Use an external ID to prevent the confused deputy problem.

API call example

This example shows how to call the DescribeRegions operation of ECS. You must first install the ECS SDK.

package main

import (
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	ecs20140526 "github.com/alibabacloud-go/ecs-20140526/v7/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
	"github.com/aliyun/credentials-go/credentials"
	"os"
)

func main() {
	// Initialize the Credentials client with RamRoleArn.
	credentialsConfig := new(credentials.Config).
		// The credential type.
		SetType("ram_role_arn").
		// The AccessKey ID.
		SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
		// The AccessKey secret.
		SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")).
		// The ARN of the RAM role to assume. Example: acs:ram::123456789012****:role/adminrole. You can set RoleArn using the ALIBABA_CLOUD_ROLE_ARN environment variable.
		SetRoleArn("<RoleArn>").
		// The name of the role session. You can set RoleSessionName using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
		SetRoleSessionName("<RoleSessionName>").
		// Optional. A smaller permission policy. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
		SetPolicy("<Policy>").
		// Optional. The session expiration time.
		SetRoleSessionExpiration(3600).
		// Optional. The default value is sts.aliyuncs.com. We recommend that you use a region-specific STS domain name. Select a region that is geographically closer to you to ensure network connectivity.
		SetSTSEndpoint("sts.cn-hangzhou.aliyuncs.com")
	credentialClient, _err := credentials.NewCredential(credentialsConfig)
	if _err != nil {
		panic(_err)
	}

	ecsConfig := &openapi.Config{}
	// Configure the endpoint of the cloud product.
	ecsConfig.Endpoint = tea.String("ecs.cn-beijing.aliyuncs.com")
	// Configure the credential using Credentials.
	ecsConfig.Credential = credentialClient
	// Initialize the ECS client.
	ecsClient, _err := ecs20140526.NewClient(ecsConfig)
	// Initialize the DescribeRegions request.
	describeInstancesRequest := &ecs20140526.DescribeRegionsRequest{}
	// Initialize the runtime configurations.
	runtime := &util.RuntimeOptions{}
	// Call the DescribeRegions operation and obtain the response.
	response, _err := ecsClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime)
	if _err != nil {
		panic(_err)
	}
	panic(response.Body.String())
}

Method 5: Use an instance RAM role

Both ECS and ECI instances support attaching instance RAM roles. Programs that run on these instances can use the Credentials tool to automatically obtain the STS token for the role, which initializes the credential client.

By default, the Credentials tool uses the secure mode (IMDSv2) to access the ECS metadata service to obtain access credentials. If an exception occurs in secure mode, the tool falls back to the normal mode to obtain the credentials. You can also set the disableIMDSv1 parameter or the ALIBABA_CLOUD_IMDSV1_DISABLE environment variable to execute different exception handling logic:

If the value is false (default), the tool continues to obtain access credentials in normal mode.
If the value is true, it means that access credentials can only be obtained in secure mode, and an exception will be thrown.

Whether the server-side supports IMDSv2 depends on your server configuration.

Additionally, you can disable credential access from ECS metadata by setting the environment variable ALIBABA_CLOUD_ECS_METADATA_DISABLED=true.

Note

To obtain a temporary identity credential in secure mode, the version of credentials-go must be 1.3.10 or later.
For more information about ECS instance metadata, see Instance metadata.
For more information about how to grant a RAM role to an ECS or ECI instance, see Create a RAM role and grant it to an ECS instance and Grant an instance RAM role to an ECI instance.

package main

import (
	"fmt"
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	"github.com/aliyun/credentials-go/credentials"
)

func _main(args []*string) {
	// Initialize the Credentials client with EcsRamRole.
	credentialsConfig := new(credentials.Config).
		// The credential type.
		SetType("ecs_ram_role").
		// Optional. The name of the ECS role. If you do not specify this parameter, the role name is automatically obtained. We recommend that you specify this parameter to reduce the number of requests. You can set RoleName using the ALIBABA_CLOUD_ECS_METADATA environment variable.
		SetRoleName("<RoleName>")
	// Optional. The default value is false. If you set this parameter to true, the secure mode is enforced. If you set this parameter to false, the system first attempts to obtain credentials in secure mode. If the attempt fails, the system switches to normal mode (IMDSv1).
	// credentialsConfig.SetDisableIMDSv1(true)
	credentialClient, err := credentials.NewCredential(credentialsConfig)
	if err != nil {
		return
	}
	config := &openapi.Config{}
        config.Credential = credentialClient
        // The code for initializing a cloud product client using the config is omitted. For more information, see the API call example.
}

API call example

This example shows how to call the DescribeRegions operation of ECS. You must first install the ECS SDK.

package main

import (
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	ecs20140526 "github.com/alibabacloud-go/ecs-20140526/v7/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
	credentials "github.com/aliyun/credentials-go/credentials"
)

func main() {
	// Initialize the Credentials client with EcsRamRole.
	credentialsConfig := new(credentials.Config).
		// The credential type.
		SetType("ecs_ram_role").
		// Optional. The name of the ECS role. If you do not specify this parameter, the role name is automatically obtained. We recommend that you specify this parameter to reduce the number of requests. You can set RoleName using the ALIBABA_CLOUD_ECS_METADATA environment variable.
		SetRoleName("<RoleName>")
	credentialClient, _err := credentials.NewCredential(credentialsConfig)
	if _err != nil {
		panic(_err)
	}

	ecsConfig := &openapi.Config{}
	// Configure the endpoint of the cloud product.
	ecsConfig.Endpoint = tea.String("ecs.cn-beijing.aliyuncs.com")
	// Configure the credential using Credentials.
	ecsConfig.Credential = credentialClient
	// Initialize the ECS client.
	ecsClient, _err := ecs20140526.NewClient(ecsConfig)
	// Initialize the DescribeRegions request.
	describeInstancesRequest := &ecs20140526.DescribeRegionsRequest{}
	// Initialize the runtime configurations.
	runtime := &util.RuntimeOptions{}
	// Call the DescribeRegions operation and obtain the response.
	response, _err := ecsClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime)
	if _err != nil {
		panic(_err)
	}
	panic(response.Body.String())
}

Method 6: Use OIDCRoleArn

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. ACK creates and mounts corresponding OpenID Connect (OIDC) token files for different application pods, and passes relevant configuration information to environment variables. The Credentials tool obtains the configuration information from the environment variables and calls the AssumeRoleWithOIDC operation of STS to obtain the STS token for attached roles.

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.

package main

import (
	"fmt"
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	"github.com/aliyun/credentials-go/credentials"
	"os"
)

func main() {
	config := new(credentials.Config).
		SetType("oidc_role_arn").
		// The ARN of the OIDC IdP. You can set OidcProviderArn using the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
		SetOIDCProviderArn(os.Getenv("ALIBABA_CLOUD_OIDC_PROVIDER_ARN")).
		// The file path of the OIDC token. You can set OidcTokenFilePath using the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
		SetOIDCTokenFilePath(os.Getenv("ALIBABA_CLOUD_OIDC_TOKEN_FILE")).
		// The ARN of the RAM role. You can set RoleArn using the ALIBABA_CLOUD_ROLE_ARN environment variable.
		SetRoleArn(os.Getenv("ALIBABA_CLOUD_ROLE_ARN")).
		// The name of the role session. You can set RoleSessionName using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
		SetRoleSessionName(os.Getenv("ALIBABA_CLOUD_ROLE_SESSION_NAME")).
		// Optional. A smaller permission policy. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
		SetPolicy("<Policy>").
		// Optional. The session expiration time.
		SetRoleSessionExpiration(3600).
		// Optional. The default value is sts.aliyuncs.com. We recommend that you use a region-specific STS domain name. Select a region that is geographically closer to you to ensure network connectivity.
		SetSTSEndpoint("sts.cn-hangzhou.aliyuncs.com")
	oidcCredential, err := credentials.NewCredential(config)
	if err != nil {
		return
	}
	
	config := &openapi.Config{}
	config.Credential = oidcCredential
	// The code for initializing a cloud product client using the config is omitted. For more information, see the API call example.
}

API call example

This example shows how to call the DescribeRegions operation of ECS. You must first install the ECS SDK.

package main

import (
	"os"

	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	ecs20140526 "github.com/alibabacloud-go/ecs-20140526/v7/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
	credentials "github.com/aliyun/credentials-go/credentials"
)

func main() {
	// Initialize the Credentials client with OIDCRoleArn.
	credentialsConfig := new(credentials.Config).
		// The credential type.
		SetType("oidc_role_arn").
		// The ARN of the OIDC IdP. You can set OidcProviderArn using the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
		SetOIDCProviderArn(os.Getenv("ALIBABA_CLOUD_OIDC_PROVIDER_ARN")).
		// The file path of the OIDC token. You can set OidcTokenFilePath using the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
		SetOIDCTokenFilePath(os.Getenv("ALIBABA_CLOUD_OIDC_TOKEN_FILE")).
		// The ARN of the RAM role. You can set RoleArn using the ALIBABA_CLOUD_ROLE_ARN environment variable.
		SetRoleArn(os.Getenv("ALIBABA_CLOUD_ROLE_ARN")).
		// The name of the role session. You can set RoleSessionName using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
		SetRoleSessionName(os.Getenv("ALIBABA_CLOUD_ROLE_SESSION_NAME")).
		// Optional. A smaller permission policy. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
		SetPolicy("<Policy>").
		// The session expiration time.
		SetRoleSessionExpiration(3600)
	credentialClient, _err := credentials.NewCredential(credentialsConfig)
	if _err != nil {
		panic(_err)
	}

	ecsConfig := &openapi.Config{}
	// Configure the endpoint of the cloud product.
	ecsConfig.Endpoint = tea.String("ecs.cn-beijing.aliyuncs.com")
	// Configure the credential using Credentials.
	ecsConfig.Credential = credentialClient
	// Initialize the ECS client.
	ecsClient, _err := ecs20140526.NewClient(ecsConfig)
	// Initialize the DescribeRegions request.
	describeInstancesRequest := &ecs20140526.DescribeRegionsRequest{}
	// Initialize the runtime configurations.
	runtime := &util.RuntimeOptions{}
	// Call the DescribeRegions operation and obtain the response.
	response, _err := ecsClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime)
	if _err != nil {
		panic(_err)
	}
	panic(response.Body.String())
}

Method 7: Use a URI credential

This method lets you encapsulate an STS token in your application and provide a custom URI to external resources. Other services can obtain the STS token only through the URI. This minimizes the risk of AccessKey exposure. The Credentials tool lets you obtain the STS token by calling the service URI to initialize the Credentials client.

package main

import (
	"github.com/aliyun/credentials-go/credentials"
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
)

func main() {
	config := new(credentials.Config).
		SetType("credentials_uri").
                // The URI of the credential. The format is http://local_or_remote_uri/. You can set CredentialsUri using the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
		SetURLCredential("<CredentialsUri>")

	uriCredential, err := credentials.NewCredential(config)
	config := &openapi.Config{}
	config.Credential = uriCredential
	// The code for initializing a cloud product client using the config is omitted. For more information, see the API call example.
}

The address must meet the following conditions:

It must support GET requests.

The response body must have the following structure:

{
  "AccessKeySecret": "AccessKeySecret",
  "AccessKeyId": "AccessKeyId",
  "Expiration": "2021-09-26T03:46:38Z",
  "SecurityToken": "SecurityToken"
}

API call example

This example shows how to call the DescribeRegions operation of ECS. You must first install the ECS SDK.

package main

import (
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	ecs20140526 "github.com/alibabacloud-go/ecs-20140526/v7/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
	credentials "github.com/aliyun/credentials-go/credentials"
)

func main() {
	config := new(credentials.Config).
		SetType("credentials_uri").
		// The URI of the credential. The format is http://local_or_remote_uri/. You can set CredentialsUri using the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
		SetURLCredential("<CredentialsUri>")

	uriCredential, _err := credentials.NewCredential(config)
	if _err != nil {
		panic(_err)
	}

	ecsConfig := &openapi.Config{}
	// Configure the endpoint of the cloud product.
	ecsConfig.Endpoint = tea.String("ecs.cn-beijing.aliyuncs.com")
	// Configure the credential using Credentials.
	ecsConfig.Credential = uriCredential
	// Initialize the ECS client.
	ecsClient, _err := ecs20140526.NewClient(ecsConfig)
	// Initialize the DescribeRegions request.
	describeInstancesRequest := &ecs20140526.DescribeRegionsRequest{}
	// Initialize the runtime configurations.
	runtime := &util.RuntimeOptions{}
	// Call the DescribeRegions operation and obtain the response.
	response, _err := ecsClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime)
	if _err != nil {
		panic(_err)
	}
	panic(response.Body.String())
}

Method 8: Use a Bearer Token

Currently, only Cloud Call Center (CCC) supports initializing credentials with a Bearer Token.

package main

import (
	"fmt"
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	"github.com/aliyun/credentials-go/credentials"
)

func main() {
	config := new(credentials.Config).
		SetType("bearer").
		// Enter your Bearer Token.
		SetBearerToken("<BearerToken>")
	bearerCredential, err := credentials.NewCredential(config)
	if err != nil {
		return
	}
	config := &openapi.Config{}
	config.Credential = bearerCredential
	// The code for initializing a cloud product client using the config is omitted. For more information, see the API call example.
}

API call example

This example shows how to call the GetInstance operation of CCC. You must first install the CCC SDK.

package main

import (
	ccc20200701 "github.com/alibabacloud-go/ccc-20200701/v2/client"
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
	credentials "github.com/aliyun/credentials-go/credentials"
)

func _main() (_err error) {
	// Initialize the Credentials client with a Bearer Token.
	credentialsConfig := new(credentials.Config).
		// The credential type.
		SetType("bearer").
		SetBearerToken("<BearerToken>")
	credentialClient, _err := credentials.NewCredential(credentialsConfig)
	if _err != nil {
		return _err
	}

	// Initialize the CCC client with the Credentials client.
	config := &openapi.Config{}
	config.Endpoint = tea.String("ccc.cn-shanghai.aliyuncs.com") // Configure the endpoint of the cloud product.
	config.Credential = credentialClient                         // Configure the credential using Credentials.
	cccClient, _err := ccc20200701.NewClient(config)
	if _err != nil {
		return _err
	}
	getInstanceRequest := &ccc20200701.GetInstanceRequest{
		InstanceId: tea.String("ccc-test"),
	}
	runtime := &util.RuntimeOptions{}
	response, _err := cccClient.GetInstanceWithOptions(getInstanceRequest, runtime)
	if _err != nil {
		return _err
	}
	panic(response.Body.String())
}

func main() {
	err := _main()
	if err != nil {
		panic(err)
	}
}

Method 9: Use CLIProfileCredentialsProvider

You can obtain access credentials from the Alibaba Cloud CLI credential configuration file (config.json).

package main

import (
	"github.com/aliyun/credentials-go/credentials"
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	"github.com/aliyun/credentials-go/credentials/providers"
)

func main() {
	// CLIProfileCredentialsProvider
	provider, err := providers.NewCLIProfileCredentialsProviderBuilder().
	        // Optional. The name of the credential. You can configure this parameter in multiple ways. The priority is as follows: explicitly specified profileName > profileName specified by the ALIBABA_CLOUD_PROFILE environment variable > the current profile in config.json.
		WithProfileName("<PROFILE_NAME>"). 
		// Optional. The path of the configuration file, which must be a .json file. You can configure this parameter in multiple ways. The priority is as follows: explicitly specified profileFile > profileFile specified by the ALIBABA_CLOUD_CONFIG_FILE environment variable > the default path ~/.aliyun/config.json.
		WithProfileFile("<PROFILE_FILE_PATH>"). 
		Build()
	if err != nil {
		return
	}
	credential := credentials.FromCredentialsProvider("cli_profile", provider)
	config := &openapi.Config{}
	config.Credential = credential
	// The code for initializing a cloud product client using the config is omitted. For more information, see the API call example.
}

You can configure credentials using the Alibaba Cloud CLI or by manually creating a config.json configuration file in the following path:

Linux: ~/.aliyun/config.json
Windows: C:\Users\USER_NAME\.aliyun\config.json

The content format is as follows:

{
  "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
    },
    {
      "name": "<PROFILE_NAME6>",
      "mode": "CloudSSO",
      "cloud_sso_sign_in_url": "https://******/login",
      "access_token": "eyJraWQiOiJiYzViMzUwYy******",
      "cloud_sso_access_token_expire": 1754316142,
      "cloud_sso_access_config": "ac-00s1******",
      "cloud_sso_account_id": "151266******"
    }
  ]
}

In the config.json file, you can use the mode parameter to specify different credentials:

AK: Uses the user's AccessKey as the credential.
StsToken: Uses an STS token as the credential.
RamRoleArn: Uses the ARN of a RAM role to obtain the credential.
EcsRamRole: Uses the RAM role attached to an ECS instance to obtain the credential.
OIDC: Uses an OIDC ARN and an OIDC token to obtain the credential.
ChainableRamRoleArn: Uses a role chain. It specifies the name of another credential in the config.json file using source_profile to obtain a new credential.
CloudSSO: The credential that a CloudSSO user obtains using the Alibaba Cloud CLI.
Note
CloudSSO credentials require version 1.4.7 or later of github.com/aliyun/credentials-go. The configuration content can only be obtained using the Alibaba Cloud CLI. For more information, see Use the CLI to log on to CloudSSO and access Alibaba Cloud resources.

After the configuration is complete, the Credentials tool initializes the credential client based on the credential name specified by the `current` parameter.

API call example

This example shows how to call the DescribeRegions operation of ECS. You must first install the ECS SDK.

package main

import (
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	ecs20140526 "github.com/alibabacloud-go/ecs-20140526/v7/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
	"github.com/aliyun/credentials-go/credentials"
	"github.com/aliyun/credentials-go/credentials/providers"
)

func main() {
	// CLIProfileCredentialsProvider
	provider, err := providers.NewCLIProfileCredentialsProviderBuilder().
		WithProfileName("SSOProfile"). // Optional. The system reads the current profile from config.json by default.
		// WithProfileFile("/path/to/config.json"). // Optional. The system reads from ~/.aliyun/config.json by default.
		Build()
	if err != nil {
		return
	}

	credentialClient := credentials.FromCredentialsProvider("cli_profile", provider)

	// Initialize the ECS client with Credentials.
	ecsConfig := &openapi.Config{}
	ecsConfig.Endpoint = tea.String("ecs.cn-beijing.aliyuncs.com")
	ecsConfig.Credential = credentialClient
	ecsClient, _err := ecs20140526.NewClient(ecsConfig)
	describeInstancesRequest := &ecs20140526.DescribeRegionsRequest{}
	runtime := &util.RuntimeOptions{}
	response, _err := ecsClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime)
	if _err != nil {
		panic(_err)
	}
	panic(response.Body.String())
}

Default credential provider chain

When the credential types used in your development and production environments are different, you typically write branch code to obtain different credentials based on the current environment. The default credential provider chain of the Credentials tool lets you use the same code and control how credentials are obtained in different environments through external configurations. When you initialize the credential client using NewCredential() without passing any parameters, the Alibaba Cloud SDK attempts to find credentials in the following order.

1. Environment variables

If no credential information is found in the system attributes, the Credentials continues to check the environment variables.

If both the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are specified, they are used as the default credential.
If ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, and ALIBABA_CLOUD_SECURITY_TOKEN are specified, the STS token is used as the default credential.

2. OIDC RAM role

If no credentials with a higher priority are found, the Credentials tool checks the following environment variables that are related to the RAM role of the OIDC IdP:

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 file path of the OIDC token.

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

3. config.json configuration file

If no higher-priority credential is found, the Credentials tool attempts to load the config.json configuration file. The default full path of this configuration file is as follows:

Linux/macOS: ~/.aliyun/config.json
Windows: C:\Users\USER_NAME\.aliyun\config.json

Note

Starting from version github.com/aliyun/credentials-go@1.4.4, you can use the ALIBABA_CLOUD_CONFIG_FILE environment variable to customize the path of the config.json file. This environment variable has a higher priority than the default path.

To configure access credentials this way, you can use the Alibaba Cloud CLI to configure credentials or manually create a config.json file in the corresponding path. The following is an example of the content format:

{
    "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
        },
        {
            "name": "<PROFILE_NAME6>",
            "mode": "CloudSSO",
            "cloud_sso_sign_in_url": "https://******/login",
            "access_token": "eyJraWQiOiJiYzViMzUwYy******",
            "cloud_sso_access_token_expire": 1754316142,
            "cloud_sso_access_config": "ac-00s1******",
            "cloud_sso_account_id": "151266******"
        },
        {
            "name": "<PROFILE_NAME7>",
            "mode": "OAuth",
            "access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
            "access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
            "sts_token": "<SECURITY_TOKEN>",
            "region_id": "<REGION_ID>",
            "output_format": "json",
            "language": "<zh|en>",
            "sts_expiration": "<STS_EXPIRATION>",
            "oauth_access_token": "<OAUTH_ACCESS_TOKEN>",
            "oauth_refresh_token": "<OAUTH_REFRESH_TOKEN>",
            "oauth_access_token_expire": 1754316142,
            "oauth_site_type": "<CN|EN>"
        }
    ]
}

In the config.json file, you can use the mode parameter to specify different credentials:

AK: Uses the user's AccessKey as the credential.
StsToken: Uses an STS token as the credential.
RamRoleArn: Uses the ARN of a RAM role to obtain the credential.
EcsRamRole: Uses the RAM role attached to an ECS instance to obtain the credential.
OIDC: Uses an OIDC ARN and an OIDC token to obtain the credential.
ChainableRamRoleArn: Uses a role chain. It specifies the name of another credential in the config.json file using source_profile to obtain a new credential.
OAuth: The credential that is obtained using the CLI to log on with OAuth.
CloudSSO: The credential that a CloudSSO user obtains using the Alibaba Cloud CLI.

Note

OAuth credentials require version 1.4.8 or later of github.com/aliyun/credentials-go. The configuration content can only be obtained using the Alibaba Cloud CLI. For more information, see Use the CLI to obtain an OAuth credential.
CloudSSO credentials require version 1.4.7 or later of github.com/aliyun/credentials-go. The configuration content can only be obtained using the Alibaba Cloud CLI. For more information, see Use the CLI to log on to CloudSSO and access Alibaba Cloud resources.

After the configuration is complete, the Credentials tool initializes the credential client based on the credential name specified by the current parameter in the configuration file. You can also specify a credential name using the ALIBABA_CLOUD_PROFILE environment variable. For example, you can set the value of ALIBABA_CLOUD_PROFILE to client1.

4. Instance RAM role

If no higher-priority credential is found, the Credentials tool attempts to obtain a credential from the RAM role attached to an ECS instance. By default, the Credentials tool uses the secure mode (IMDSv2) to access the ECS metadata service to obtain the STS token of the instance RAM role as the default credential. The program automatically accesses the ECS metadata service to retrieve the RoleName and then obtains the credential, which involves two requests. To reduce this to one request, you can directly configure the ALIBABA_CLOUD_ECS_METADATA environment variable to specify the instance RAM role name. If an exception occurs in secure mode, the tool falls back to the normal mode to obtain the access credential. You can also set the ALIBABA_CLOUD_IMDSV1_DISABLE environment variable to execute different exception handling logic:

If the value is false, the tool continues to obtain the access credential in normal mode.
If the value is true, it means that the access credential can only be obtained in secure mode, and an exception will be thrown.

Whether the server-side supports IMDSv2 depends on your server configuration.

Additionally, you can disable credential access from ECS metadata by setting the environment variable ALIBABA_CLOUD_ECS_METADATA_DISABLED=true.

Note

For more information about ECS instance metadata, see Instance metadata.
For more information about how to grant a RAM role to an ECS or ECI instance, see Create a RAM role and grant it to an ECS instance and Grant an instance RAM role to an ECI instance.

5. Credentials tool URI

If no valid credential is obtained using the preceding methods, the Credentials tool checks the ALIBABA_CLOUD_CREDENTIALS_URI environment variable. If this environment variable exists and specifies a valid URI, the Credentials tool initiates an HTTP requests to obtain an STS token as the default credential.

Auto-refresh mechanism for session-based credentials

Session credentials include ARNs of RAM roles (RamRoleArn), RAM roles of ECS instances, RAM roles of OIDC IdPs (OIDCRoleArn), and credential URIs. The Credentials tool provides a built-in automatic update mechanism for session credentials. After a credential is obtained from the first call, the Credentials tool stores the credential in the cache. In subsequent calls, the credential is read from the cache as long as the credential is not expired. Otherwise, the Credentials tool makes a call to obtain the credential again, and updates the credential in the cache.

Note

For RAM roles of ECS instances, the Credentials tool updates the credential 15 minutes before the cache time-to-live (TTL) ends.

In the following example, the Credentials client is created in single-instance mode and is used to initialize the cloud service client. Then, an API operation is called during different time periods to check whether internal cache is used and whether the credential is refreshed after the cache expires.

package main

import (
	"fmt"
	"log"
	"os"
	"sync"
	"time"

	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	ecs20140526 "github.com/alibabacloud-go/ecs-20140526/v7/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
	"github.com/aliyun/credentials-go/credentials"
)

// Credential is a singleton struct used to manage the Alibaba Cloud credential instance.
type Credential struct {
	instance credentials.Credential
	once     sync.Once
}

var credentialInstance = &Credential{}

func GetCredentialInstance() credentials.Credential {
	credentialInstance.once.Do(func() {
		cfg := &credentials.Config{
			Type:                  tea.String("ram_role_arn"),
			AccessKeyId:           tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")),
			AccessKeySecret:       tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")),
			RoleArn:               tea.String(os.Getenv("ALIBABA_CLOUD_ROLE_ARN")),
			RoleSessionName:       tea.String("RamRoleArnTest"),
			RoleSessionExpiration: tea.Int(3600),
		}
		var err error
		credentialInstance.instance, err = credentials.NewCredential(cfg)
		if err != nil {
			log.Fatalf("Credential initialization failed: %v", err)
		}
	})
	return credentialInstance.instance
}

// EcsClient is a singleton struct used to manage the ECS client instance.
type EcsClient struct {
	instance *ecs20140526.Client
	once     sync.Once
}

var ecsClientInstance = &EcsClient{}

func GetEcsClientInstance(cred credentials.Credential) *ecs20140526.Client {
	ecsClientInstance.once.Do(func() {
		cfg := &openapi.Config{
			Endpoint:   tea.String("ecs.cn-hangzhou.aliyuncs.com"),
			Credential: cred,
		}
		var err error
		ecsClientInstance.instance, err = ecs20140526.NewClient(cfg)
		if err != nil {
			log.Fatalf("ECS client initialization failed: %v", err)
		}
	})
	return ecsClientInstance.instance
}

// Execute the main task.
func runTask() {
	cred := GetCredentialInstance()
	credentialModel, err := cred.GetCredential()
	if err != nil {
		log.Printf("Failed to get credential: %v", err)
		return
	}

	fmt.Println(time.Now())
	fmt.Printf("AK ID: %s, AK Secret: %s, STS Token: %s\n",
		*credentialModel.AccessKeyId,
		*credentialModel.AccessKeySecret,
		*credentialModel.SecurityToken)

	ecsClient := GetEcsClientInstance(cred)
	req := &ecs20140526.DescribeRegionsRequest{}
	runtime := &util.RuntimeOptions{}

	resp, err := ecsClient.DescribeRegionsWithOptions(req, runtime)
	if err != nil {
		log.Printf("ECS API call failed: %v", err)
		return
	}

	fmt.Printf("Invoke result: %d\n", *resp.StatusCode)
}

func main() {
	done := make(chan bool)

	// Start a goroutine to execute scheduled tasks.
	go func() {
		tick := time.NewTicker(1 * time.Second)
		defer tick.Stop()

		executionCount := 0
		delays := []time.Duration{0, 600, 3600, 100} // Delay time in seconds.

		for {
			select {
			case <-tick.C:
				if executionCount < len(delays) {
					delay := delays[executionCount]
					time.Sleep(delay * time.Second)
					runTask()
					executionCount++
				} else {
					close(done)
					return
				}
			}
		}
	}()

	<-done
	fmt.Println("All tasks completed. Exiting...")
}

Log analysis:

In the first call, the system obtains the credential based on the configurations because the credential is not cached. After the system obtains the credential, the credential is stored in the cache.
The second call uses the same credential as the first call, which indicates that the credential is obtained from the cache.
In the third call, the credential has expired because the third call is 4,200 seconds later than the first call while the credential TTL (RoleSessionExpiration) is set to 3,600 seconds. The SDK obtains the credential again based on the automatic update mechanism and stored the credential in the cache.
The fourth call uses the same credential as the third call, which indicates that the credential is updated after cache expiration.

References

For more information about RAM, see Terms.
For more information about how to create an AccessKey pair, see Create an AccessKey pair.
For more information about how to create a RAM user, an AccessKey pair, a RAM role, and a policy and grant permissions to a RAM user, see RAM SDK overview.
For more information about how to assume a role using a program, see STS SDK overview.
For more information about RAM and STS-related API operations, see API reference.
Best practices for using an access credential to call API operations
Solutions to AccessKey pair leaks