Configure Go SDK Access Credentials for Authentication - MaxCompute

Before sending MaxCompute requests with the Go SDK, configure an access credential to initialize a credential provider. Alibaba Cloud uses these credentials to authenticate identity and verify access permissions.

Six configuration methods are available. Choose based on where your application runs and your security requirements.

Prerequisites

Before you begin, ensure that you have:

The Go SDK installed. For more information, see Install the Go SDK.

Choose a credential method

Where your application runs determines which method to use:

Deployment environment	Recommended method	Requires pre-provisioned credentials	Underlying implementation	Validity	Rotation/refresh
Applications in untrusted environments requiring controlled access	Method 2: STS token	Yes	STS token	Temporary	Manual
Applications requiring cross-account access (e.g., cross-account access to OSS)	Method 3: RAMRoleARN	Yes	STS token	Temporary	Auto
Applications on ECS instances, ECI instances, or Container Service for Kubernetes worker nodes	Method 4: ECSRAMRole	No	STS token	Temporary	Auto
Applications that fetch credentials from an external system	Method 5: CredentialsURI	No	STS token	Temporary	Auto
Secure environments with no need for frequent credential updates	Method 1: AccessKey	Yes	AccessKey	Long-term	Manual
None of the above fit your requirements	Method 6: Custom credentials	Custom	STS token	Custom	Custom

Important

Methods 4 (ECSRAMRole) and 5 (CredentialsURI) require no pre-provisioned AccessKey or STS token, which eliminates the security risks of managing long-term credentials manually. Use these methods whenever your deployment environment supports them.

Method 1: AccessKey

Warning

AccessKey credentials are long-term and must be rotated manually. Exposure of an AccessKey ID or AccessKey secret gives full account access. Use STS-based methods (Methods 3–5) for production workloads whenever possible.

Use this method only for applications deployed in a secure, stable environment that is unlikely to be exposed to external attacks and requires long-term, infrequent access to MaxCompute. To get an AccessKey, see CreateAccessKey.

Two sub-methods are available: environment variables and configuration files.

Using environment variables

Add the credentials library to your project.

go get github.com/aliyun/credentials-go/credentials

Set the following environment variables. On macOS, Linux, or Unix:

export ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>

On Windows:

set ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
set ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>

Initialize the credential provider in your application. credentials.NewCredential(nil) reads ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET from environment variables automatically.

package main

import (
    "fmt"
    "github.com/aliyun/aliyun-odps-go-sdk/odps"
    "github.com/aliyun/aliyun-odps-go-sdk/odps/account"
    "github.com/aliyun/credentials-go/credentials"
)

func main() {
    // Read AccessKey credentials from environment variables:
    // ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET
    credential, err := credentials.NewCredential(nil)
    if err != nil {
        return
    }

    aliyunAccount := account.NewStsAccountWithCredential(credential)

    // Endpoint format: http://service.<region-id>.maxcompute.aliyun.com/api
    endpoint := "http://service.cn-hangzhou.maxcompute.aliyun.com/api"
    defaultProject := "<your-project-name>"

    odpsIns := odps.NewOdps(aliyunAccount, endpoint)
    odpsIns.SetDefaultProjectName(defaultProject)

    fmt.Printf("odps:%#v\n", odpsIns)
}

Using a configuration file

Create a configuration file with an .ini extension, for example, config.ini.

Important

Do not add comments after key-value pairs in the file.

[odps]
access_id = "<your-access-key-id>"
access_key = "<your-access-key-secret>"
endpoint = "<your-endpoint>"
project = "<your-project-name>"

Load the configuration file in your application.

package main

import (
    "fmt"
    "github.com/aliyun/aliyun-odps-go-sdk/odps"
    "github.com/aliyun/aliyun-odps-go-sdk/odps/account"
    "log"
)

func main() {
    // Load credentials from the configuration file
    configPath := "./config.ini"
    conf, err := odps.NewConfigFromIni(configPath)
    if err != nil {
        log.Fatalf("%+v", err)
    }

    aliAccount := account.NewAliyunAccount(conf.AccessId, conf.AccessKey)
    odpsIns := odps.NewOdps(aliAccount, conf.Endpoint)
    odpsIns.SetDefaultProjectName(conf.ProjectName)

    fmt.Printf("odps:%#v\n", odpsIns)
}

Method 2: STS token

Use this method when your application needs temporary access to MaxCompute in an untrusted environment with controlled permissions. You must manage and refresh the STS token manually each time it expires. To get an STS token, see AssumeRole.

Two sub-methods are available: environment variables and configuration files.

Using environment variables

Add the credentials library to your project.

go get github.com/aliyun/credentials-go/credentials

Set the following environment variables. On macOS, Linux, or Unix:

export ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>
export ALIBABA_CLOUD_SECURITY_TOKEN=<your-security-token>

On Windows:

set ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
set ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>
set ALIBABA_CLOUD_SECURITY_TOKEN=<your-security-token>

Initialize the credential provider in your application. credentials.NewCredential(nil) reads ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, and ALIBABA_CLOUD_SECURITY_TOKEN from environment variables automatically.

package main

import (
    "fmt"
    "github.com/aliyun/aliyun-odps-go-sdk/odps"
    "github.com/aliyun/aliyun-odps-go-sdk/odps/account"
    "github.com/aliyun/credentials-go/credentials"
)

func main() {
    // Read STS token from environment variables:
    // ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, ALIBABA_CLOUD_SECURITY_TOKEN
    credential, err := credentials.NewCredential(nil)
    if err != nil {
        return
    }

    aliyunAccount := account.NewStsAccountWithCredential(credential)

    endpoint := "http://service.cn-hangzhou.maxcompute.aliyun.com/api"
    defaultProject := "<your-project-name>"

    odpsIns := odps.NewOdps(aliyunAccount, endpoint)
    odpsIns.SetDefaultProjectName(defaultProject)

    fmt.Printf("odps:%#v\n", odpsIns)
}

Using a configuration file

Create a configuration file with an .ini extension, for example, config.ini.

Important

Do not add comments after key-value pairs in the file.

[odps]
access_id = "<your-access-key-id>"
access_key = "<your-access-key-secret>"
sts_token = "<your-security-token>"
endpoint = "<your-endpoint>"
project = "<your-project-name>"

Load the configuration file in your application.

package main

import (
    "fmt"
    "github.com/aliyun/aliyun-odps-go-sdk/odps"
    "github.com/aliyun/aliyun-odps-go-sdk/odps/account"
    "log"
)

func main() {
    configPath := "./config.ini"
    conf, err := odps.NewConfigFromIni(configPath)
    if err != nil {
        log.Fatalf("%+v", err)
    }

    aliAccount := account.NewAliyunAccount(conf.AccessId, conf.AccessKey)
    odpsIns := odps.NewOdps(aliAccount, conf.Endpoint)
    odpsIns.SetDefaultProjectName(conf.ProjectName)

    fmt.Printf("odps:%#v\n", odpsIns)
}

Method 3: RAMRoleARN

Use this method for applications that require authorized access, such as cross-account access to OSS. The SDK calls the Security Token Service (STS) using the RAM role ARN you specify, obtains an STS token, and refreshes it automatically before it expires. You can also attach a policy to restrict the token's permissions.

This method requires an AccessKey or an existing STS token. To get them, see CreateAccessKey or AssumeRole. To get a RAM role ARN, see CreateRole.

Add the credentials library to your project.

go get github.com/aliyun/credentials-go/credentials

Configure the credential provider using ram_role_arn.

package main

import (
    "fmt"
    "github.com/aliyun/aliyun-odps-go-sdk/odps"
    "github.com/aliyun/aliyun-odps-go-sdk/odps/account"
    "github.com/aliyun/credentials-go/credentials"
    "log"
)

func main() {
    accessKeyId := "<your-access-key-id>"
    accessKeySecret := "<your-access-key-secret>"

    config := new(credentials.Config).
        SetType("ram_role_arn").
        SetAccessKeyId(accessKeyId).
        SetAccessKeySecret(accessKeySecret).
        // Format: acs:ram::<account-id>:role/<role-name>
        SetRoleArn("<your-role-arn>").
        SetRoleSessionName("<your-role-session-name>").
        // Optional: restrict the permissions of the STS token
        SetPolicy("<your-policy>").
        // Optional: restrict the token validity period, in seconds
        SetRoleSessionExpiration(3600)

    credential, err := credentials.NewCredential(config)
    if err != nil {
        log.Fatalf("%+v", err)
    }

    stsAccount := account.NewStsAccountWithCredential(credential)

    endpoint := "http://service.cn-hangzhou.maxcompute.aliyun.com/api"
    defaultProject := "<your-project-name>"

    odpsIns := odps.NewOdps(stsAccount, endpoint)
    odpsIns.SetDefaultProjectName(defaultProject)

    fmt.Printf("odps:%#v\n", odpsIns)
}

Method 4: ECSRAMRole

Use this method for applications running on ECS instances, ECI instances, or Container Service for Kubernetes worker nodes. No AccessKey or STS token is required — the SDK retrieves temporary credentials from the instance metadata service and refreshes them automatically. To create a RAM role, see CreateRole.

Add the credentials library to your project.

go get github.com/aliyun/credentials-go/credentials

Configure the credential provider using ecs_ram_role.

Setting SetDisableIMDSv1(true) enforces Instance Metadata Service v2 (IMDSv2), which uses session-based tokens and is more secure than IMDSv1. IMDSv1 allows any process on the instance to access metadata without authentication. Disable it unless your environment specifically requires it.

package main

import (
    "fmt"
    "log"

    "github.com/aliyun/aliyun-odps-go-sdk/odps"
    "github.com/aliyun/aliyun-odps-go-sdk/odps/account"
    "github.com/aliyun/credentials-go/credentials"
)

func main() {
    config := new(credentials.Config).
        SetType("ecs_ram_role").
        // Optional but recommended: set the role name to reduce metadata requests
        SetRoleName("<your-role-name>").
        // Recommended: disable IMDSv1 to enforce the more secure IMDSv2
        // Alternatively, set the ALIBABA_CLOUD_IMDSV1_DISABLED environment variable
        SetDisableIMDSv1(true)

    credential, err := credentials.NewCredential(config)
    if err != nil {
        log.Fatalf("%+v", err)
    }

    stsAccount := account.NewStsAccountWithCredential(credential)

    endpoint := "http://service.cn-hangzhou.maxcompute.aliyun.com/api"
    defaultProject := "<your-project-name>"

    odpsIns := odps.NewOdps(stsAccount, endpoint)
    odpsIns.SetDefaultProjectName(defaultProject)

    fmt.Printf("odps:%#v\n", odpsIns)
}

Method 5: CredentialsURI

Use this method when your application retrieves credentials from an external system. The SDK fetches an STS token from the URI you provide and uses it for authentication. No AccessKey or STS token needs to be embedded in your application.

Your backend service must implement the STS token refresh logic to ensure the credentials URI always returns valid credentials.

URI response protocol

The credentials URI must return HTTP 200 with a JSON body in the following format:

{
    "Code": "Success",
    "AccessKeyId": "<access-key-id>",
    "AccessKeySecret": "<access-key-secret>",
    "SecurityToken": "<security-token>",
    "Expiration": "2024-10-09T16:39:33Z"
}

The Expiration field is required. The SDK uses it to determine when to refresh credentials. If Expiration is absent, the SDK treats the credentials as long-term and does not attempt to refresh them automatically.

Configure the credential provider

Add the credentials library to your project.

go get github.com/aliyun/credentials-go/credentials

Configure the credential provider using credentials_uri.

package main

import (
    "fmt"
    "github.com/aliyun/aliyun-odps-go-sdk/odps"
    "github.com/aliyun/aliyun-odps-go-sdk/odps/account"
    "github.com/aliyun/credentials-go/credentials"
)

func main() {
    config := new(credentials.Config).
        SetType("credentials_uri").
        SetURLCredential("<your-credentials-uri>")

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

    stsAccount := account.NewStsAccountWithCredential(credential)

    endpoint := "http://service.cn-hangzhou.maxcompute.aliyun.com/api"
    defaultProject := "<your-project-name>"

    odpsIns := odps.NewOdps(stsAccount, endpoint)
    odpsIns.SetDefaultProjectName(defaultProject)

    fmt.Printf("odps:%#v\n", odpsIns)
}

Method 6: Custom credentials

If none of the above methods meet your requirements, implement the CredentialProvider interface to define your own credential logic.

package main

import (
    "fmt"
    "github.com/aliyun/aliyun-odps-go-sdk/odps"
    "github.com/aliyun/aliyun-odps-go-sdk/odps/account"
    "github.com/aliyun/credentials-go/credentials"
)

// CustomCredentialProvider implements the CredentialProvider interface
type CustomCredentialProvider struct{}

func (cp *CustomCredentialProvider) GetType() (*string, error) {
    s := "CustomProvider"
    return &s, nil
}

func (cp *CustomCredentialProvider) GetCredential() (*credentials.CredentialModel, error) {
    // Add your credential retrieval logic here
    accessKeyId := "<your-access-key-id>"
    accessKeySecret := "<your-access-key-secret>"
    securityToken := "<your-security-token>"

    return &credentials.CredentialModel{
        AccessKeyId:     &accessKeyId,
        AccessKeySecret: &accessKeySecret,
        SecurityToken:   &securityToken,
    }, nil
}

func main() {
    provider := &CustomCredentialProvider{}

    stsAccount := account.NewStsAccountWithProvider(provider)

    endpoint := "http://service.cn-hangzhou.maxcompute.aliyun.com/api"
    defaultProject := "<your-project-name>"

    odpsIns := odps.NewOdps(stsAccount, endpoint)
    odpsIns.SetDefaultProjectName(defaultProject)

    fmt.Printf("odps:%#v\n", odpsIns)
}

What's next

After configuring access credentials, initialize the MaxCompute SDK. For detailed instructions, see Initialize the MaxCompute SDK.