Todos os produtos
Search
Central de documentação

Alibaba Cloud SDK:Gerenciar credenciais de acesso

Última atualização: Jun 28, 2026

O Alibaba Cloud SDK usa a ferramenta Credentials para gerenciar credenciais centralmente, como AccessKey e STS Token. Este tópico descreve os tipos de credenciais compatíveis e seus métodos de configuração.

Contexto

As credenciais verificam a identidade do usuário ao acessar serviços da Alibaba Cloud. Os tipos comuns incluem:

  1. Um par de AccessKey fornece credenciais permanentes para uma conta Alibaba Cloud ou um usuário RAM. Ele consiste em um AccessKey ID e um AccessKey Secret.

  2. Um token STS fornece credenciais temporárias para uma função RAM com período de validade e escopo de permissões configuráveis. O que é o STS.

  3. Um bearer token é usado para autenticação e autorização.

Pré-requisitos

Instalar a ferramenta Credentials

Execute o comando npm a seguir para instalar o pacote.

npm install @alicloud/credentials

Use a versão mais recente para garantir compatibilidade com todos os tipos de credenciais. Releases · aliyun/credentials-nodejs · GitHub.

Parâmetros de credencial

Configure as credenciais pelo construtor Config do módulo @alicloud/credentials. O parâmetro type é obrigatório e determina quais outros parâmetros se aplicam. A tabela a seguir lista os valores válidos para type e seus respectivos parâmetros. = obrigatório, - = opcional, × = não compatível.

Nota

Somente os tipos de credenciais e parâmetros listados abaixo são compatíveis.

type

access_key

sts

ram_role_arn

ecs_ram_role

oidc_role_arn

credentials_uri

bearer

accessKeyId: O AccessKey ID.

×

×

×

×

accessKeySecret: O AccessKey Secret.

×

×

×

×

securityToken: O token do Security Token Service (STS).

×

-

×

×

×

×

roleArn: O Alibaba Cloud Resource Name (ARN) da função RAM.

×

×

×

×

×

roleSessionName: Um nome personalizado para a sessão. O formato padrão é credentials-nodejs-<timestamp>.

×

×

-

×

-

×

×

roleName: O nome da função RAM.

×

×

×

-

×

×

×

disableIMDSv1: Especifica se deve impor o modo de reforço de segurança (IMDSv2). Valor padrão: false.

×

×

×

-

×

×

×

bearerToken: O bearer token.

×

×

×

×

×

×

policy: Uma política personalizada.

×

×

-

×

-

×

×

roleSessionExpiration: O tempo de expiração da sessão, em segundos. Valor padrão: 3600.

×

×

-

×

-

×

×

oidcProviderArn: O ARN do provedor de identidade OpenID Connect (OIDC).

×

×

×

×

×

×

oidcTokenFilePath: O caminho para o arquivo de token OpenID Connect (OIDC).

×

×

×

×

×

×

externalId: Um ID externo para mitigar o problema de confused deputy. Usar um ID externo para prevenir o problema de confused deputy.

×

×

-

×

×

×

×

credentialsURI: A URI das credenciais.

×

×

×

×

×

×

O endpoint do STS. Compatível com endpoints VPC e públicos. Endpoints disponíveis: Endpoints. Padrão: sts.aliyuncs.com.

×

×

-

×

-

×

×

timeout: O tempo limite de leitura para solicitações HTTP, em milissegundos. O valor padrão é 5000.

×

×

-

-

-

-

×

connectTimeout: O tempo limite de conexão para solicitações HTTP, em milissegundos. O valor padrão é 10000.

×

×

-

-

-

-

×

Inicializar um cliente de credenciais

A seção anterior descreve os tipos de credenciais e os parâmetros de configuração compatíveis com a ferramenta Credentials. As seções a seguir fornecem exemplos de código sobre como usar a ferramenta. Selecione o método mais adequado ao seu cenário.

Importante
  • Nunca armazene um AccessKey em texto simples no código do projeto. Uma chave exposta compromete todos os recursos da conta. Armazene-a em variáveis de ambiente ou arquivos de configuração.

  • Implemente o singleton pattern para a credentials tool. Isso habilita o credential cache integrado, evitando rate limiting devido a chamadas excessivas de API. Mecanismo de atualização automática de credenciais para credenciais de sessão.

Método 1: Cadeia de provedores de credenciais padrão

Inicializar um cliente de credenciais sem parâmetros ativa a Cadeia de provedores de credenciais padrão.

const Credential = require('@alicloud/credentials');
// Use the default credential provider chain
const credentialClient = new Credential.default();
const credential = credentialClient.getCredential();
credential.then(credential => {
    console.log(credential);
});
import Credential from '@alicloud/credentials';
const credential = new Credential();
credential.getCredential().then(credential => {
    console.log(credential);
});

Chamada de API

Este exemplo mostra como chamar a operação DescribeRegions do ECS. Para executar o código, instale o ECS SDK.

const Ecs20140526 = require('@alicloud/ecs20140526');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');
async function main() {
    // Initialize the credential client with default credentials.
    const credentialClient = new Credential.default();
    const ecsConfig = new OpenApi.Config({
        endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // Configure the service endpoint.
        credential: credentialClient, // Specify the credential client.
    });
    const ecsClient = new Ecs20140526.default(ecsConfig);
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    const runtime = new Util.RuntimeOptions();
    ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime).then((result) => {
        console.log(JSON.stringify(result.body));
    });
}
main().catch(console.error);
import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';
import Credential from '@alicloud/credentials';
export default class Client {
    static async main(): Promise<$Ecs20140526.DescribeRegionsResponse> {
        // Initialize a credential instance with default credentials.
        let credential = new Credential();
        let config = new $OpenApi.Config({
            credential: credential, // Specify the credential instance.
            endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // Configure the service endpoint.
        });
        let client = new Ecs20140526(config);
        let describeRegionsRequest = new $Ecs20140526.DescribeRegionsRequest({});
        let runtime = new $Util.RuntimeOptions({});
        return await client.describeRegionsWithOptions(describeRegionsRequest, runtime);
    }
}
const response = Client.main();
response.then(res => {
    console.log(res.body?.regions);
});

Método 2: Usar um AccessKey

A ferramenta Credentials usa o AccessKey fornecido como credencial de acesso.

Aviso

Uma conta Alibaba Cloud (conta raiz) tem permissões totais sobre todos os recursos; portanto, um AK exposto representa um risco significativo de segurança. Não use o AK de uma conta raiz.

Use o AK de um usuário RAM com permissões de privilégio mínimo.

const Credential = require('@alicloud/credentials');
const credentialsConfig = new Credential.Config({
    // The credential type.
    type: 'access_key',
    // Your AccessKey ID, retrieved from an environment variable.
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    // Your AccessKey Secret, retrieved from an environment variable.
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
});
const credentialClient = new Credential.default(credentialsConfig);
import Credential, { Config } from '@alicloud/credentials';
const credentialsConfig  = new Config({
    // The credential type.
    type: 'access_key',
    // Your AccessKey ID, retrieved from an environment variable.
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    // Your AccessKey Secret, retrieved from an environment variable.
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
});
const credentialClient = new Credential(credentialsConfig);

Chamada de API

Este exemplo chama a operação DescribeRegions do ECS. Instale o ECS SDK para executar o código.

const Ecs20140526 = require('@alicloud/ecs20140526');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');
async function main() {
    const credentialsConfig = new Credential.Config({
        // The credential type.
        type: 'access_key',
        // The AccessKey ID, read from an environment variable.
        accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
        // The AccessKey secret, read from an environment variable.
        accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
    });
    const credentialClient = new Credential.default(credentialsConfig);
    const ecsConfig = new OpenApi.Config();
    ecsConfig.endpoint = 'ecs.cn-hangzhou.aliyuncs.com'; // The service endpoint.
    ecsConfig.credential = credentialClient; // The credential client for authentication.
    const ecsClient = new Ecs20140526.default(ecsConfig);
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    const runtime = new Util.RuntimeOptions();
    ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime).then((response) => {
        console.log(response.body.regions);
    });
}
main().catch(console.error);
import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import Credential, { Config } from '@alicloud/credentials';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';
export default class Client {
    static async main(): Promise<$Ecs20140526.DescribeRegionsResponse> {
        const credentialsConfig = new Config({
            // The credential type.
            type: 'access_key',
            // The AccessKey ID, read from an environment variable.
            accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
            // The AccessKey secret, read from an environment variable.
            accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
        });
        const credentialClient = new Credential(credentialsConfig);
        let config = new $OpenApi.Config({
            credential: credentialClient, // The credential client for authentication.
            endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // The service endpoint.
        });
        let client = new Ecs20140526(config);
        let describeRegionsRequest = new $Ecs20140526.DescribeRegionsRequest({});
        let runtime = new $Util.RuntimeOptions({});
        return await client.describeRegionsWithOptions(describeRegionsRequest, runtime);
    }
}
const response = Client.main();
response.then(res => {
    console.log(res.body?.regions);
});

Método 3: Usar um token STS

A ferramenta Credentials usa o token STS estático fornecido como credencial de acesso.

const Credential = require('@alicloud/credentials');
const credentialsConfig = new Credential.Config({
    type: 'sts',
    // Your AccessKey ID, retrieved from an environment variable.
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    // Your AccessKey Secret, retrieved from an environment variable.
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
    // Your security token, retrieved from an environment variable.
    securityToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN,
});
const cred = new Credential.default(credentialsConfig);
import Credential, { Config } from '@alicloud/credentials';
const credentialsConfig = new Config({
    // The credential type.
    type: 'access_key',
    // Your AccessKey ID, retrieved from an environment variable.
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    // Your AccessKey Secret, retrieved from an environment variable.
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
    // Your security token, retrieved from an environment variable.
    securityToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN,
});
const credentialClient = new Credential(credentialsConfig);

Chamada de API

Este exemplo chama a operação DescribeRegions do ECS. Para executar este código, instale o ECS SDK e o Security Token Service SDK.

const Ecs20140526 = require('@alicloud/ecs20140526');
const Sts20150401 = require('@alicloud/sts20150401');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');
async function assumeRole() {
    // Create an STS client to get an STS token.
    const stsConfig = new OpenApi.Config({
        endpoint: 'sts.cn-hangzhou.aliyuncs.com', // The endpoint for Security Token Service (STS).
        accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID, // Get the AccessKey ID from an environment variable.
        accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET, // Get the AccessKey secret from an environment variable.
    });
    const stsClient = new Sts20150401.default(stsConfig);
    const assumeRoleRequest = new Sts20150401.AssumeRoleRequest({
        durationSeconds: 3600, // The validity period of the STS token.
        roleArn: '<RoleArn>', // The ARN of the RAM role to assume. Example: acs:ram::123456789012****:role/adminrole. This can be set with the ALIBABA_CLOUD_ROLE_ARN environment variable. 
        roleSessionName: '<RoleSessionName>', // A custom name for the role session. This can be set with the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable. 
        policy: '', // Optional. A RAM policy. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    });
    try {
        const assumeRoleResponsePromise = await stsClient.assumeRole(assumeRoleRequest);
        const assumeRoleResponseBodyCredentials = assumeRoleResponsePromise.body.credentials;
        return {
            accessKeyId: assumeRoleResponseBodyCredentials.accessKeyId,
            accessKeySecret: assumeRoleResponseBodyCredentials.accessKeySecret,
            securityToken: assumeRoleResponseBodyCredentials.securityToken,
        };
    } catch (error) {
        console.error('The AssumeRole request failed:', error);
        throw error;
    }
}
async function main() {
    const stsToken = await assumeRole()
    const credentialsConfig = new Credential.Config({
        // The type of credential.
        type: 'sts',
        accessKeyId: stsToken.accessKeyId,
        accessKeySecret: stsToken.accessKeySecret,
        securityToken: stsToken.securityToken,
    });
    const credentialClient = new Credential.default(credentialsConfig);
    const ecsConfig = new OpenApi.Config({
        endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // The endpoint of the cloud service.
        credential: credentialClient, // The authentication credential.
    })
    const ecsClient = new Ecs20140526.default(ecsConfig);
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    const runtime = new Util.RuntimeOptions();
    // Call the DescribeRegions operation.
    ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime).then((response) => {
        console.log(response.body.regions);
    });
}
main().catch(console.error);
import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import Sts20150401, * as $Sts20150401 from '@alicloud/sts20150401';
import OpenApi, { Config } from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';
import Credential, { Config as CredentialConfig } from '@alicloud/credentials';
async function assumeRole() {
    // Create an STS client to get an STS token.
    const stsConfig = new Config({
        endpoint: 'sts.cn-hangzhou.aliyuncs.com', // The endpoint for Security Token Service (STS).
        accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID, // Get the AccessKey ID from an environment variable.
        accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET, // Get the AccessKey secret from an environment variable.
    });
    const stsClient = new Sts20150401(stsConfig);
    const assumeRoleRequest = new $Sts20150401.AssumeRoleRequest({
        durationSeconds: 3600, // The validity period of the STS token.
        roleArn: '<RoleArn>', // The ARN of the RAM role to assume. Example: acs:ram::123456789012****:role/adminrole. This can be set with the ALIBABA_CLOUD_ROLE_ARN environment variable.  
        roleSessionName: '<RoleSessionName>', // A custom name for the role session. This can be set with the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable. 
        policy: '', // Optional. A RAM policy. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    });
    try {
        const assumeRoleResponsePromise = await stsClient.assumeRole(assumeRoleRequest);
        const assumeRoleResponseBodyCredentials = assumeRoleResponsePromise.body?.credentials;
        return {
            accessKeyId: assumeRoleResponseBodyCredentials?.accessKeyId,
            accessKeySecret: assumeRoleResponseBodyCredentials?.accessKeySecret,
            securityToken: assumeRoleResponseBodyCredentials?.securityToken,
        };
    } catch (error) {
        console.error('The AssumeRole request failed:', error);
        throw error;
    }
}
async function main() {
    const stsToken = await assumeRole()
    const credentialsConfig = new CredentialConfig({
        // The type of credential.
        type: 'sts',
        accessKeyId: stsToken.accessKeyId,
        accessKeySecret: stsToken.accessKeySecret,
        securityToken: stsToken.securityToken,
    });
    const credentialClient = new Credential(credentialsConfig);
    const ecsConfig = new Config({
        endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // The endpoint of the cloud service.
        credential: credentialClient, // The authentication credential.
    })
    const ecsClient = new Ecs20140526(ecsConfig);
    const describeRegionsRequest = new $Ecs20140526.DescribeRegionsRequest();
    const runtime = new $Util.RuntimeOptions();
    // Call the DescribeRegions operation.
    ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime).then((response) => {
        console.log(response.body?.regions);
    });
}
main().catch(console.error);

Método 4: AccessKey e ARN de função RAM

Este método usa o STS internamente. Ao especificar um ARN de função RAM, a ferramenta Credentials obtém um token STS do serviço STS. Use o parâmetro policy para restringir ainda mais as permissões da função.

const Credential = require('@alicloud/credentials');
const credentialsConfig = new Credential.Config({
    type: 'ram_role_arn',
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
    // The RAM role ARN to assume. Example: acs:ram::123456789012****:role/adminrole. This can also be set using the `ALIBABA_CLOUD_ROLE_ARN` environment variable.
    roleArn: '<RoleArn>',
    // A custom role session name. This can also be set using the `ALIBABA_CLOUD_ROLE_SESSION_NAME` environment variable.
    roleSessionName: '<RoleSessionName>',
    // Optional. An inline policy to limit the permissions of the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    policy: '<Policy>',
    roleSessionExpiration: 3600,
});
const cred = new Credential.default(credentialsConfig);
import Credential, { Config } from '@alicloud/credentials';
const credentialsConfig = new Config({
    type: 'ram_role_arn',
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
    // The RAM role ARN to assume. Example: acs:ram::123456789012****:role/adminrole. This can also be set using the `ALIBABA_CLOUD_ROLE_ARN` environment variable.
    roleArn: '<RoleArn>',
    // A custom role session name. This can also be set using the `ALIBABA_CLOUD_ROLE_SESSION_NAME` environment variable.
    roleSessionName: '<RoleSessionName>',
    // Optional. An inline policy to limit the permissions of the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    policy: '<Policy>',
    roleSessionExpiration: 3600,
});
const credentialClient = new Credential(credentialsConfig);

Método de chamada de API

Este exemplo mostra como chamar a operação DescribeRegions do ECS. Para executar o código, instale o ECS SDK.

const Ecs20140526 = require('@alicloud/ecs20140526');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');
async function main() {
    const credentialsConfig = new Credential.Config({
        // Specifies the credential type.
        type: 'ram_role_arn',
        // Your AccessKey ID.
        accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
        // Your AccessKey Secret.
        accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
        // The ARN of the RAM role to assume. Example: acs:ram::123456789012****:role/adminrole. You can set this by using the ALIBABA_CLOUD_ROLE_ARN environment variable.
        roleArn: '<RoleArn>',
        // A custom name for the role session. You can set this by using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
        roleSessionName: '<RoleSessionName>',
        // Optional. An inline policy that limits the permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
        policy: '<Policy>',
        roleSessionExpiration: 3600,
    });
    const credentialClient = new Credential.default(credentialsConfig);
    const ecsConfig = new OpenApi.Config({
        endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // The service endpoint.
        credential: credentialClient, // Specifies the credential to use.
    });
    const ecsClient = new Ecs20140526.default(ecsConfig);
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    const runtime = new Util.RuntimeOptions();
    // Call the DescribeRegions operation.
    const response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
    console.log((await response).body.regions);
}
main().catch(console.error);
import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import Credential, { Config } from '@alicloud/credentials';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';
export default class Client {
    static async main(): Promise<$Ecs20140526.DescribeRegionsResponse> {
        const credentialsConfig = new Config({
            type: 'ram_role_arn',
            accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
            accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
            // The ARN of the RAM role to assume. Example: acs:ram::123456789012****:role/adminrole. You can set this by using the ALIBABA_CLOUD_ROLE_ARN environment variable.
            roleArn: '<RoleArn>',
            // A custom name for the role session. You can set this by using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
            roleSessionName: '<RoleSessionName>',
            // Optional. An inline policy that limits the permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
            policy: '<Policy>',
            roleSessionExpiration: 3600,
        });
        const credentialClient = new Credential(credentialsConfig);
        let config = new $OpenApi.Config({
            credential: credentialClient, // Specifies the credential to use.
            endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // The service endpoint.
        });
        let client = new Ecs20140526(config);
        let describeRegionsRequest = new $Ecs20140526.DescribeRegionsRequest({});
        let runtime = new $Util.RuntimeOptions({});
        return await client.describeRegionsWithOptions(describeRegionsRequest, runtime);
    }
}
const response = Client.main();
response.then(res => {
    console.log(res.body?.regions);
});

Método 5: Função RAM de instância ECS

Anexe uma função RAM de instância a uma instância ECS ou instância de contêiner elástico. Os aplicativos na instância podem então usar a ferramenta Credentials para obter automaticamente um token STS para a função.

Por padrão, a ferramenta Credentials acessa o servidor de metadados do ECS no modo de reforço de segurança (IMDSv2). Se ocorrer um erro, ela retorna ao modo normal. Controle esse comportamento com o parâmetro disableIMDSv1 ou a variável de ambiente ALIBABA_CLOUD_IMDSV1_DISABLE:

  • false (padrão): Retorna ao modo normal em caso de falha.

  • true: Usa apenas o modo de reforço de segurança e lança uma exceção em caso de falha.

A compatibilidade com IMDSv2 depende da configuração do servidor.

Também é possível desabilitar o acesso a credenciais via metadados do ECS definindo a variável de ambiente ALIBABA_CLOUD_ECS_METADATA_DISABLED=true.

Nota
const Credential = require('@alicloud/credentials');
const credentialsConfig = new Credential.Config({
    type: 'ecs_ram_role',
    // Optional. The name of the ECS RAM role. If unspecified, the system retrieves it automatically. Specifying a name is recommended to reduce requests. This can also be set via the ALIBABA_CLOUD_ECS_METADATA environment variable.
    roleName: '<RoleName>',
    // Optional. Default: false. If true, enforces security hardening mode. If false, the system tries security hardening mode first, falling back to normal mode (IMDSv1) on failure.
    // disableIMDSv1: true,
});
const cred = new Credential.default(credentialsConfig);
import Credential, { Config } from '@alicloud/credentials';
const credentialsConfig = new Config({
    type: 'ecs_ram_role',
    // Optional. The name of the ECS RAM role. If unspecified, the system retrieves it automatically. Specifying a name is recommended to reduce requests. This can also be set via the ALIBABA_CLOUD_ECS_METADATA environment variable.
    roleName: '<RoleName>',
    // Optional. Default: false. If true, enforces security hardening mode. If false, the system tries security hardening mode first, falling back to normal mode (IMDSv1) on failure.
    // disableIMDSv1: true,
});
const credentialClient = new Credential(credentialsConfig);

Chamada de API

Este exemplo chama a operação DescribeRegions do ECS. Para executar o código, primeiro instale o ECS SDK.

const Ecs20140526 = require('@alicloud/ecs20140526');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');
async function main() {
    const credentialsConfig = new Credential.Config({
        // The credential type.
        type: 'ecs_ram_role',
        // Optional. The name of the ECS RAM role. We recommend specifying this to reduce requests. If omitted, the system retrieves it automatically. You can also set the roleName parameter by using the ALIBABA_CLOUD_ECS_METADATA environment variable.
        roleName: '<RoleName>',
    });
    const credentialClient = new Credential.default(credentialsConfig);
    const ecsConfig = new OpenApi.Config({
        endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // The service endpoint.
        credential: credentialClient, // The credential to use for authentication.
    });
    const ecsClient = new Ecs20140526.default(ecsConfig);
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    const runtime = new Util.RuntimeOptions();
    // Call the DescribeRegions operation and obtain the response.
    const response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
    console.log((await response).body.regions);
}
main().catch(console.error);
import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import Credential, { Config } from '@alicloud/credentials';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';
export default class Client {
    static async main(): Promise<$Ecs20140526.DescribeRegionsResponse> {
        const credentialsConfig = new Config({
            type: 'ecs_ram_role',
            // Optional. The name of the ECS RAM role. We recommend specifying this to reduce requests. If omitted, the system retrieves it automatically. You can also set the roleName parameter by using the ALIBABA_CLOUD_ECS_METADATA environment variable.
            roleName: '<RoleName>',
            // Optional. Defaults to `false`. Setting this to `true` enforces security hardening mode. If this parameter is set to false, the system first attempts to get credentials in security hardening mode and falls back to normal mode (IMDSv1) if the attempt fails.
            // disableIMDSv1: true,
        });
        const credentialClient = new Credential(credentialsConfig);
        let config = new $OpenApi.Config({
            credential: credentialClient, // The credential to use for authentication.
            endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // The service endpoint.
        });
        let client = new Ecs20140526(config);
        let describeRegionsRequest = new $Ecs20140526.DescribeRegionsRequest({});
        let runtime = new $Util.RuntimeOptions({});
        return await client.describeRegionsWithOptions(describeRegionsRequest, runtime);
    }
}
const response = Client.main();
response.then(res => {
    console.log(res.body?.regions);
});

Método 6: Usar OIDCRoleArn

Se você usa OIDC e já criou uma função RAM para um provedor OIDC, passe um ARN de provedor OIDC, um token OIDC e um ARN de função RAM para o SDK Credentials. O SDK chama a operação AssumeRoleWithOIDC para obter um token STS. Essas credenciais oferecem suporte à atualização automática. Mecanismo de atualização automática para credenciais de sessão. Por exemplo, em um cluster ACK com RRSA habilitado, o SDK lê a configuração OIDC das variáveis de ambiente do Pod e obtém um token STS para acessar os serviços da Alibaba Cloud.

const Credential = require('@alicloud/credentials');
const credentialsConfig = new Credential.Config({
    type: 'oidc_role_arn',
    // The RAM role ARN to assume. You can also set this using the ALIBABA_CLOUD_ROLE_ARN environment variable.
    roleArn: '<RoleArn>',
    // The OIDC IdP ARN. You can also set this using the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
    oidcProviderArn: '<OidcProviderArn>',
    // The OIDC token file path. You can also set this using the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
    oidcTokenFilePath: '<OidcTokenFilePath>',
    // A custom role session name. You can also set this using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
    roleSessionName: '<RoleSessionName>',
    // Optional. A policy to scope down the permissions for the session. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    policy: '<Policy>',
    // The session duration in seconds.
    roleSessionExpiration: 3600,
});
const credentialClient = new Credential.default(credentialsConfig);
import Credential, { Config } from '@alicloud/credentials';
const credentialsConfig = new Config({
    type: 'oidc_role_arn',
    // The RAM role ARN to assume. You can also set this using the ALIBABA_CLOUD_ROLE_ARN environment variable.
    roleArn: '<RoleArn>',
    // The OIDC IdP ARN. You can also set this using the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
    oidcProviderArn: '<OidcProviderArn>',
    // The OIDC token file path. You can also set this using the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
    oidcTokenFilePath: '<OidcTokenFilePath>',
    // A custom role session name. You can also set this using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
    roleSessionName: '<RoleSessionName>',
    // Optional. A policy to scope down the permissions for the session. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    policy: '<Policy>',
    // The session duration in seconds.
    roleSessionExpiration: 3600,
});
const credentialClient = new Credential(credentialsConfig);

Chamada de API

Este exemplo mostra como chamar a operação DescribeRegions do ECS. Para executar o código, instale o ECS SDK.

const Ecs20140526 = require('@alicloud/ecs20140526');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');
async function main() {
    const credentialsConfig = new Credential.Config({
        // The credential type.
        type: 'oidc_role_arn',
        // The ARN of the RAM role to assume. You can also set this using the ALIBABA_CLOUD_ROLE_ARN environment variable.
        roleArn: '<RoleArn>',
        // The ARN of the OIDC provider. You can also set this using the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
        oidcProviderArn: '<OidcProviderArn>',
        // The OIDC token file path. You can also set this using the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
        oidcTokenFilePath: '<OidcTokenFilePath>',
        // A custom role session name. You can also set this using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
        roleSessionName: '<RoleSessionName>',
        // Optional. A policy that limits the permissions for the session. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
        policy: '<Policy>',
        // The session expiration in seconds.
        roleSessionExpiration: 3600,
    });
    const credentialClient = new Credential.default(credentialsConfig);
    const ecsConfig = new OpenApi.Config({
        endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // The service endpoint.
        credential: credentialClient, // The authentication credential.
    });
    const ecsClient = new Ecs20140526.default(ecsConfig);
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    const runtime = new Util.RuntimeOptions();
    // Call the DescribeRegions operation.
    const response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
    console.log((await response).body.regions);
}
main().catch(console.error);
import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import Credential, { Config } from '@alicloud/credentials';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';
export default class Client {
    static async main(): Promise<$Ecs20140526.DescribeRegionsResponse> {
        const credentialsConfig = new Config({
            type: 'oidc_role_arn',
            // The ARN of the RAM role to assume. You can also set this using the ALIBABA_CLOUD_ROLE_ARN environment variable.
            roleArn: '<RoleArn>',
            // The ARN of the OIDC provider. You can also set this using the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
            oidcProviderArn: '<OidcProviderArn>',
            // The OIDC token file path. You can also set this using the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
            oidcTokenFilePath: '<OidcTokenFilePath>',
            // A custom role session name. You can also set this using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
            roleSessionName: '<RoleSessionName>',
            // Optional. A policy that limits the permissions for the session. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
            policy: '<Policy>',
            // The session expiration in seconds.
            roleSessionExpiration: 3600,
        });
        const credentialClient = new Credential(credentialsConfig);
        let config = new $OpenApi.Config({
            credential: credentialClient, // The authentication credential.
            endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // The service endpoint.
        });
        let client = new Ecs20140526(config);
        let describeRegionsRequest = new $Ecs20140526.DescribeRegionsRequest({});
        let runtime = new $Util.RuntimeOptions({});
        return await client.describeRegionsWithOptions(describeRegionsRequest, runtime);
    }
}
const response = Client.main();
response.then(res => {
    console.log(res.body?.regions);
});

Método 7: Credencial URI

Exponha o serviço STS por meio de uma URI para que serviços externos obtenham um token STS sem lidar diretamente com pares de AccessKey. A ferramenta Credentials recupera um token STS da URI especificada e o usa como credencial de acesso, com suporte à atualização automática. Mecanismo de atualização automática para credenciais do tipo sessão.

const Credential = require('@alicloud/credentials');
const config = new Credential.Config({
    type: 'credentials_uri',
    // The endpoint to retrieve credentials, for example, http://local_or_remote_uri/. This can also be set with the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
    credentialsURI: '<CredentialsUri>',
});
const credentialClient = new Credential(config);
import Credential, { Config } from '@alicloud/credentials';
const credentialsConfig = new Config({
    type: 'credentials_uri',
    // The endpoint to retrieve credentials, for example, http://local_or_remote_uri/. This can also be set with the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
    credentialsURI: '<CredentialsUri>',
});
const credentialClient = new Credential(credentialsConfig);

A resposta da URI deve atender aos seguintes requisitos:

  • O código de status deve ser 200.

  • Formato do corpo da resposta:

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

Chamada de API

Este exemplo demonstra como chamar a operação DescribeRegions do ECS. Antes de executar o código, instale o ECS SDK.

const Ecs20140526 = require('@alicloud/ecs20140526');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');
async function main() {
    const credentialsConfig = new Credential.Config({
        // The credential type.
        type: 'credentials_uri',
        // The URI for obtaining the credential, formatted as http://local_or_remote_uri/. Alternatively, set the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
        credentialsURI: '<CredentialsUri>',
    });
    const credentialClient = new Credential.default(credentialsConfig);
    const ecsConfig = new OpenApi.Config({
        endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // The service endpoint.
        credential: credentialClient, // The credential client for authentication.
    });
    const ecsClient = new Ecs20140526.default(ecsConfig);
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    const runtime = new Util.RuntimeOptions();
    // Calls the DescribeRegions operation.
    const response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
    console.log((await response).body.regions);
}
main().catch(console.error);
import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import Credential, { Config } from '@alicloud/credentials';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';
export default class Client {
    static async main(): Promise<$Ecs20140526.DescribeRegionsResponse> {
        let credentialsConfig = new Config({
            type: 'credentials_uri',
            // The URI for obtaining the credential, formatted as http://local_or_remote_uri/. Alternatively, set the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
            credentialsURI: '<CredentialsUri>',
        });
        let credentialClient = new Credential(credentialsConfig);
        let config = new $OpenApi.Config({
            credential: credentialClient, // The credential client for authentication.
            endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // The service endpoint.
        });
        let client = new Ecs20140526(config);
        let describeRegionsRequest = new $Ecs20140526.DescribeRegionsRequest({});
        let runtime = new $Util.RuntimeOptions({});
        return await client.describeRegionsWithOptions(describeRegionsRequest, runtime);
    }
}
const response = Client.main();
response.then(res => {
    console.log(res.body?.regions);
});

Método 8: Usar um bearer token

Atualmente, apenas o Alibaba Cloud Call Center (CCC) oferece suporte à autenticação via bearer token.

const Credential = require('@alicloud/credentials');
const config = new Credential.Config({
    type: 'bearer',
    // Replace with your bearer token.
    bearerToken: '<BearerToken>',
});
const credentialClient = new Credential(config);
import Credential, { Config } from '@alicloud/credentials';
const credentialsConfig = new Config({
    type: 'bearer',
    // Replace with your bearer token.
    bearerToken: '<BearerToken>',
});
const credentialClient = new Credential(credentialsConfig);

Chamada de API

Este exemplo mostra como chamar a operação GetInstance do Cloud Call Center (CCC). Para executar o código, instale o Cloud Call Center SDK.

const CCC20200701 = require('@alicloud/ccc20200701');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');
async function main() {
    let credentialsConfig = new Credential.Config({
        // The credential type.
        type: 'bearer',
        // Specify your bearer token.
        bearerToken: '<BearerToken>',
    });
    let credentialClient = new Credential.default(credentialsConfig);
    let config = new OpenApi.Config({
        endpoint: 'ccc.cn-shanghai.aliyuncs.com',
        credential: credentialClient
    });
    let client = new CCC20200701.default(config);
    let getInstanceRequest = new CCC20200701.GetInstanceRequest({
        instanceId: 'ccc-test',
    });
    let runtime = new Util.RuntimeOptions({});
    let response = client.getInstanceWithOptions(getInstanceRequest, runtime);
    console.log((await response).body);
}
main().catch(console.error);
import ccc20200701, * as $ccc20200701 from '@alicloud/ccc20200701';
import Credential, { Config } from '@alicloud/credentials';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';
export default class Client {
    static async main(): Promise<$ccc20200701.GetInstanceResponse> {
        let credentialsConfig = new Config({
            type: 'bearer',
            // Specify your bearer token.
            bearerToken: '<BearerToken>',
        });
        let credentialClient = new Credential(credentialsConfig);
        let config = new $OpenApi.Config({
            credential: credentialClient, // Specify the credential.
            endpoint: 'ccc.cn-shanghai.aliyuncs.com', // Specify the endpoint.
        });
        let client = new ccc20200701(config);
        let GetInstanceRequest = new $ccc20200701.GetInstanceRequest({
            instanceId: 'ccc-test',
        });
        let runtime = new $Util.RuntimeOptions({});
        return await client.getInstanceWithOptions(GetInstanceRequest, runtime);
    }
}
let response = Client.main();
response.then(res => {
    console.log(res.body?.regions);
});

Cadeia de provedores de credenciais padrão

A cadeia de provedores de credenciais padrão permite usar o mesmo código em diferentes ambientes e controlar a obtenção de credenciais por meio de configuração externa. Ao chamar new Credential() sem parâmetros, o SDK busca credenciais na seguinte ordem.

1. Uso de variáveis de ambiente

Se nenhuma credencial for encontrada nas propriedades do sistema, a cadeia de provedores verifica as variáveis de ambiente.

  • Se ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET estiverem presentes e não vazias, a cadeia de provedores as usa como credencial padrão.

  • Caso ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET e ALIBABA_CLOUD_SECURITY_TOKEN também estejam definidas, a cadeia de provedores usa um token STS como credencial padrão.

2. Funções RAM OIDC

Se nenhuma credencial tiver sido encontrada, a cadeia de provedores verifica as seguintes variáveis de ambiente relacionadas a uma função RAM OIDC:

  • ALIBABA_CLOUD_ROLE_ARN: O ARN da função RAM.

  • ALIBABA_CLOUD_OIDC_PROVIDER_ARN: O ARN do provedor OIDC.

  • ALIBABA_CLOUD_OIDC_TOKEN_FILE: O caminho do arquivo de token OIDC.

Se todas as três variáveis de ambiente estiverem presentes e não vazias, a cadeia de provedores usa esses valores para chamar a API AssumeRoleWithOIDC do Security Token Service (STS) e obter um token STS.

3. Config.json

Caso nenhuma credencial tenha sido encontrada, a cadeia de provedores tenta carregar o arquivo de credenciais compartilhadas, config.json, de sua localização padrão e usa a credencial especificada no arquivo.

  • Linux/macOS: ~/.aliyun/config.json

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

Para configurar uma credencial dessa forma, use a Alibaba Cloud CLI ou crie manualmente um arquivo config.json no caminho apropriado. O exemplo a seguir mostra o formato do conteúdo:

{
  "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
    }
  ]
}

Parâmetro

Descrição

current

Especifique o nome da credencial para recuperar a configuração correspondente. O nome da credencial é o valor do parâmetro name em profiles. Por padrão, o sistema prioriza o nome da credencial especificado pela variável de ambiente ALIBABA_CLOUD_PROFILE. Se essa variável de ambiente não estiver configurada, o sistema usa o nome da credencial especificado por current.

profiles

Contém uma coleção de configurações de credenciais. O parâmetro mode especifica o tipo de credencial:

  • AK: Usa o AccessKey de um usuário RAM como credencial.

  • StsToken: Usa um token STS como credencial.

  • RamRoleArn: Assume uma função RAM usando as credenciais de um usuário RAM para obter uma credencial temporária.

  • EcsRamRole: Obtém uma credencial dos metadados da instância.

  • OIDC: Obtém uma credencial usando um ARN de provedor OIDC, um token OIDC e um ARN de função RAM.

  • ChainableRamRoleArn: Usa encadeamento de funções para obter uma nova credencial, utilizando uma credencial inicial de profiles especificada pelo parâmetro source_profile.

4. Função RAM de instância ECS

Se nenhuma credencial de maior prioridade for encontrada, o SDK recupera credenciais da função RAM da instância ECS. Ele acessa o serviço de metadados da instância no modo aprimorado (IMDSv2) para obter um token STS. Isso requer duas solicitações: uma para o nome da função e outra para as credenciais. Para reduzir isso a uma única solicitação, defina o nome da função na variável de ambiente ALIBABA_CLOUD_ECS_METADATA. Se o modo aprimorado falhar, o processo retorna ao modo normal. Controle esse comportamento com ALIBABA_CLOUD_IMDSV1_DISABLE:

  1. false: Retorna ao modo normal em caso de falha.

  2. true: Usa apenas o modo aprimorado e lança uma exceção em caso de falha.

A compatibilidade com IMDSv2 depende da configuração do serviço de metadados da instância.

Para desabilitar a recuperação de credenciais dos metadados da instância ECS, defina ALIBABA_CLOUD_ECS_METADATA_DISABLED=true.

Nota

5. URI de credenciais

Se nenhuma credencial tiver sido encontrada, a cadeia de provedores verifica a variável de ambiente ALIBABA_CLOUD_CREDENTIALS_URI. Caso esta variável esteja definida e aponte para uma URI válida, a cadeia acessa a URI para recuperar um token STS.

Atualização automática para credenciais de sessão

As credenciais de sessão (ram_role_arn, ecs_ram_role, oidc_role_arn e credentials_uri) incluem atualização automática integrada. Na primeira recuperação, a ferramenta Credentials armazena a credencial em cache. Solicitações subsequentes retornam o valor armazenado até que ele expire, momento em que uma nova credencial é buscada automaticamente.

Nota

Para credenciais ecs_ram_role, a ferramenta Credentials as atualiza proativamente 15 minutos antes da expiração.

O exemplo a seguir usa o padrão singleton para criar um cliente de credenciais, verificando a atualização automática ao recuperar credenciais em intervalos diferentes e confirmando a validade por meio de uma chamada OpenAPI.

const Credential = require('@alicloud/credentials');
const Ecs20140526 = require('@alicloud/ecs20140526');
const { Config } = require('@alicloud/openapi-client');
const { RuntimeOptions } = require('@alicloud/tea-util');
// Obtain environment variables.
const accessKeyId = process.env.ALIBABA_CLOUD_ACCESS_KEY_ID;
const accessKeySecret = process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET;
const roleArn = process.env.ALIBABA_CLOUD_ROLE_ARN;
/**
 * The Credential singleton class manages Alibaba Cloud credential instances.
 */
class CredentialClient {
    constructor() {
        if (!CredentialClient.instance) {
            var credentialsConfig = new Credential.Config({
                type: 'ram_role_arn',
                accessKeyId: accessKeyId,
                accessKeySecret: accessKeySecret,
                roleArn: roleArn,
                roleSessionName: 'RoleSessionNameTest',
                roleSessionExpiration: 3600,
            });
            this.credentialsClient = new Credential.default(credentialsConfig);
            CredentialClient.instance = this;
        }
        return CredentialClient.instance;
    }
    static getInstance() {
        return new CredentialClient().credentialsClient;
    }
}
/**
 * The ECS Client singleton class manages ECS client instances.
 */
class EcsClient {
    constructor(credentialClient) {
        if (!EcsClient.instance) {
            const config = new Config({
                endpoint: 'ecs.cn-hangzhou.aliyuncs.com',
                credential: credentialClient
            });
            this.ecsClient = new Ecs20140526.default(config);
            EcsClient.instance = this;
        }
        return EcsClient.instance;
    }
    static getInstance(credentialClient) {
        return new EcsClient(credentialClient).ecsClient;
    }
}
/**
 * Execute the task logic.
 */
async function executeTask() {
    try {
        const credentialClient = CredentialClient.getInstance();
        const credential = await credentialClient.getCredential();
        console.log(new Date());
        console.log(`AK ID: ${credential.accessKeyId}`);
        console.log(`AK Secret: ${credential.accessKeySecret}`);
        console.log(`STS Token: ${credential.securityToken}`);
        // This example calls an ECS API operation to verify the credential's validity. Modify this as needed.
        const ecsClient = EcsClient.getInstance(credentialClient);
        const request = new Ecs20140526.DescribeRegionsRequest();
        const runtime = new RuntimeOptions({});
        const response = await ecsClient.describeRegionsWithOptions(request, runtime);
        console.log(`Invoke result: ${response.statusCode}`);
    } catch (error) {
        throw new Error(`ECS client execution failed: ${error.message}`, { cause: error });
    }
}
/**
 * Schedule task execution by using a timer.
 */
function scheduleTasks() {
    // Immediately run the task once.
    executeTask();
    // Set a delay for subsequent tasks.
    setTimeout(executeTask, 600 * 1000); // Second run: after 600 seconds.
    setTimeout(executeTask, 4200 * 1000); // Third run: after 4,200 seconds.
    setTimeout(executeTask, 4300 * 1000); // Fourth run: after 4,300 seconds.
}
// Start task scheduling.
scheduleTasks();
import Credential, { Config as CredentialsConfig }  from '@alicloud/credentials';
import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import { Config } from '@alicloud/openapi-client';
import { RuntimeOptions } from '@alicloud/tea-util';
// Obtain environment variables.
const accessKeyId: string | undefined = process.env.ALIBABA_CLOUD_ACCESS_KEY_ID;
const accessKeySecret: string | undefined = process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET;
const roleArn: string | undefined = process.env.ALIBABA_CLOUD_ROLE_ARN;
if (!accessKeyId || !accessKeySecret || !roleArn) {
    throw new Error('Missing required environment variables.');
}
/**
 * The Credential singleton class manages Alibaba Cloud credential instances.
 */
class CredentialClient {
    private static instance: CredentialClient;
    private readonly credentialsClient: InstanceType<typeof Credential>;
    private constructor() {
        const credentialsConfig = new CredentialsConfig({
            type: 'ram_role_arn',
            accessKeyId,
            accessKeySecret,
            roleArn,
            roleSessionName: 'RoleSessionNameTest',
            roleSessionExpiration: 3600,
        });
        this.credentialsClient = new Credential(credentialsConfig);
    }
    static getInstance(): InstanceType<typeof Credential> {
        if (!CredentialClient.instance) {
            CredentialClient.instance = new CredentialClient();
        }
        return CredentialClient.instance.credentialsClient;
    }
}
/**
 * The ECS Client singleton class manages ECS client instances.
 */
class EcsClient {
    private static instance: EcsClient;
    private readonly ecsClient: InstanceType<typeof Ecs20140526>;
    private constructor(credentialClient: InstanceType<typeof Credential>) {
        const config = new Config({
            endpoint: 'ecs.cn-hangzhou.aliyuncs.com',
            credential: credentialClient
        });
        this.ecsClient = new Ecs20140526(config);
    }
    static getInstance(credentialClient: InstanceType<typeof Credential>): InstanceType<typeof Ecs20140526> {
        if (!EcsClient.instance) {
            EcsClient.instance = new EcsClient(credentialClient);
        }
        return EcsClient.instance.ecsClient;
    }
}
/**
 * Execute the task logic.
 */
async function executeTask(): Promise<void> {
    try {
        const credentialClient = CredentialClient.getInstance();
        const credential = await credentialClient.getCredential();
        console.log(new Date());
        console.log(`AK ID: ${credential.accessKeyId}`);
        console.log(`AK Secret: ${credential.accessKeySecret}`);
        console.log(`STS Token: ${credential.securityToken}`);
        // This example calls an ECS API operation to verify the credential's validity. Modify this as needed.
        const ecsClient = EcsClient.getInstance(credentialClient);
        const request = new $Ecs20140526.DescribeRegionsRequest();
        const runtime = new RuntimeOptions({});
        const response = await ecsClient.describeRegionsWithOptions(request, runtime);
        console.log(`Invoke result: ${response.statusCode}`);
    } catch (error) {
        throw new Error(`ECS client execution failed: ${error}`);
    }
}
/**
 * Schedule task execution by using a timer.
 */
function scheduleTasks(): void {
    // Immediately run the task once.
    executeTask();
    // Set a delay for subsequent tasks.
    setTimeout(executeTask, 600 * 1000); // Second run: after 600 seconds.
    setTimeout(executeTask, 4200 * 1000); // Third run: after 4,200 seconds.
    setTimeout(executeTask, 4300 * 1000); // Fourth run: after 4,300 seconds.
}
// Start task scheduling.
scheduleTasks();
2025-05-28T09:22:29.584Z
AK ID: STS.NVS9xxx7DRbao
AK Secret: 9SoQxxxmVjVsED9ad47rcgMaw5XyQyXx
STS Token:
CAISyQJ1q6Ft5B2yfSjIr5Xmcu/irrxq0pWvU0PZhvVtS7hovafKjTz2IHhMeXZoA+4YsPw2mmFW6/sdlrpJTJtIfkHfdsp36LJe9A6dbpHd4xc1LGed0s/LI3OaLjKm9u2wCryLYbGwU/OpbE++5U0X6LDmdDKkckW40JmS8/BOZcgWWQ/KB1gvRq
0hRG1YpdQdKGHa0xxxWg0/ks0aH1war1bBL+tqofMP9MfMBZskvD42Hu8VtbbfE3SJq7BxHybx71qQs+02c5onAXAELvUvYa7OKo4MyCVBjBKEhALNBoeL7kfBobmFAAkgwYnynVMMisES3LOiIqKOsk1MdI9Cywly2y
vfiZZ1prmk1pV68xxxczc4yvhD2nuNe7rmc9Z3/JHusVmo7LiTxqAARdkoKCeYBvLk0ZFWccCiM0ZvdnRtv0VDOUfD1zQELQGL+xB5NrBmdzq2ePjFJbrkBGmy5EXD714jknyzM4lFic2dUQMi14NCHMVDVjGAf0qUs
F+PQW58jGb32fmFxxxTXOx82sdRQqW0/vTd2KQmIAA=
Invoke result: 200
2025-05-28T09:32:28.137Z
AK ID: STS.NVS9xxx7DRbao
AK Secret: 9SoQxxxmVjVsED9ad47rcgMaw5XyQyXx
STS Token:
CAISyQJ1q6Ft5B2yfSjIr5Xmcu/irrxq0pWvU0PZhvVtS7hovafKjTz2IHhMeXZoA+4YsPw2mmFW6/sdlrpJTJtIfkHfdsp36LJe9A6dbpHd4xc1LGed0s/LI3OaLjKm9u2wCryLYbGwU/OpbE++5U0X6LDmdDKkckW40JmS8/BOZcgWWQ/KB1gvRq
0hRG1YpdQdKGHa0xxxWg0/ks0aH1war1bBL+tqofMP9MfMBZskvD42Hu8VtbbfE3SJq7BxHybx71qQs+02c5onAXAELvUvYa7OKo4MyCVBjBKEhALNBoeL7kfBobmFAAkgwYnynVMMisES3LOiIqKOsk1MdI9Cywly2y
vfiZZ1prmk1pV68xxxczc4yvhD2nuNe7rmc9Z3/JHusVmo7LiTxqAARdkoKCeYBvLk0ZFWccCiM0ZvdnRtv0VDOUfD1zQELQGL+xB5NrBmdzq2ePjFJbrkBGmy5EXD714jknyzM4lFic2dUQMi14NCHMVDVjGAf0qUs
F+PQW58jGb32fmFxxxTXOx82sdRQqW0/vTd2KQmIAA=
Invoke result: 200
2025-05-28T10:32:29.771Z
AK ID: STS.NVuaxxxLFiPw8
AK Secret: 5dsoxxxpA5pCzfrek4KforS8MnJ6qHR9
STS Token:
CAISyQJ1q6Ft5B2yfSjIr5XAKsjd241w4PqgY1P2gDUvb8NqhpXc2jz2IHhMeXZoA+4YsPw2mmFW6/sdlrpJTJtIfkHfdsp36LJe9A6dbpHd4yVKL2Gd0s/LI3OaLjKm9u2wCryLYbGwU/OpbE++5U0X6LDmdDKkckW40JmS8/BOZcgWWQ/KB1gvRq
0hRG1YpdQdKGHa0xxxWg0/ks0aH1war1bBL+tqofMP9MfMBZskvD42Hu8VtbbfE3SJq7BxHybx71qQs+02c5onAXAELvUvYa7OKo4MyCVBjBKEhALNBoeL7kfBobmFAAkgwYnynVMMisES3LOjIqKOsk+Mdk9CiWv2y
vfiZZ1prmk1pV68xxxczc4yvhD2nuNe7rmc9Z3/KpUoQEo7LiTxqAAUyV7F+kpLHRG/yHw3JaVz14hqSj2hmxxkwgczUWIkpBLKHLeW0iI3sp2LNQO6iEAImLpSE0nRVBbcutIqxEuFzAs607jgOjHakTF7UZNoKVV
wb42xR4s4ThGd2PxxxqoUsrKfCq5lHiUiDq6L1VIAA=
Invoke result: 200
2025-05-28T10:34:08.130Z
AK ID: STS.NVuaxxxLFiPw8
AK Secret: 5dsoxxxpA5pCzfrek4KforS8MnJ6qHR9
STS Token:
CAISyQJ1q6Ft5B2yfSjIr5XAKsjd241w4PqgY1P2gDUvb8NqhpXc2jz2IHhMeXZoA+4YsPw2mmFW6/sdlrpJTJtIfkHfdsp36LJe9A6dbpHd4yVKL2Gd0s/LI3OaLjKm9u2wCryLYbGwU/OpbE++5U0X6LDmdDKkckW40JmS8/BOZcgWWQ/KB1gvRq
0hRG1YpdQdKGHa0xxxWg0/ks0aH1war1bBL+tqofMP9MfMBZskvD42Hu8VtbbfE3SJq7BxHybx71qQs+02c5onAXAELvUvYa7OKo4MyCVBjBKEhALNBoeL7kfBobmFAAkgwYnynVMMisES3LOjIqKOsk+Mdk9CiWv2y
vfiZZ1prmk1pV68xxxczc4yvhD2nuNe7rmc9Z3/KpUoQEo7LiTxqAAUyV7F+kpLHRG/yHw3JaVz14hqSj2hmxxkwgczUWIkpBLKHLeW0iI3sp2LNQO6iEAImLpSE0nRVBbcutIqxEuFzAs607jgOjHakTF7UZNoKVV
wb42xR4s4ThGd2PxxxqoUsrKfCq5lHiUiDq6L1VIAA=
Invoke result: 200

Análise baseada na saída do log:

  • Na primeira chamada, o cache está vazio. O sistema recupera uma credencial com base na configuração e a armazena no cache.

  • A segunda chamada usa a mesma credencial da primeira, indicando que foi recuperada do cache.

  • Na terceira chamada, a credencial em cache expirou. Seu tempo de expiração (RoleSessionExpiration) é de 3.600 segundos, mas esta chamada ocorre 4.200 segundos após a primeira. Consequentemente, o mecanismo de atualização automática do SDK busca uma nova credencial e atualiza o cache.

  • A quarta chamada usa a mesma credencial da terceira, confirmando que o cache foi atualizado.

Documentos relacionados