Todos os produtos
Search
Central de documentação

Key Management Service:Plug-in de segredo RAM

Última atualização: Jun 27, 2026

Após armazenar a AccessKey de um usuário RAM no Key Management Service (KMS) como um segredo RAM, instale o plug-in de segredo RAM para permitir que qualquer Alibaba Cloud SDK recupere e faça a rotação dessa AccessKey automaticamente. Sua aplicação referencia apenas o nome do segredo — o plug-in gerencia o cache, a atualização de credenciais e as novas tentativas em caso de falha, eliminando a necessidade de codificar credenciais diretamente ou rotacioná-las manualmente.

Como funciona

O plug-in obtém o valor do segredo RAM do KMS pelo nome do segredo e o armazena em cache na memória da aplicação. Todas as chamadas de saída do SDK utilizam a AccessKey presente nesse cache local.

Quando o KMS rotaciona o segredo, a AccessKey em cache eventualmente se torna inválida. O plug-in detecta essa situação monitorando os códigos de erro InvalidAccessKeyId ou InvalidAccessKeyId.NotFound na resposta da API. Em seguida, busca imediatamente o novo segredo, atualiza o cache e tenta novamente a chamada que falhou, conforme o comportamento de nova tentativa configurado.

Comportamento de atualização de credenciais por linguagem:

Linguagem

Gatilho de atualização

Intervalo de atualização agendada

Java

Erro InvalidAccessKeyId ou InvalidAccessKeyId.NotFound

Python

Erro InvalidAccessKeyId ou InvalidAccessKeyId.NotFound

Go

Apenas agendada — sem nova tentativa automática em caso de InvalidAccessKeyId

A cada 6 horas

O plug-in de segredo RAM para Go não oferece suporte a novas tentativas automáticas em caso de InvalidAccessKeyId . A atualização agendada ocorre a cada 6 horas. Consulte Comportamento específico do Go para soluções alternativas.

SDKs suportados

Importante

O plug-in de segredo RAM destina-se a Alibaba Cloud SDKs específicos. Se nenhum dos plug-ins listados abaixo atender ao seu caso de uso, utilize o cliente de segredos ou um Alibaba Cloud SDK padrão. Consulte a referência do SDK para obter a lista completa.

Java (Java 8 e posterior)

SDK

Módulo do plug-in

Alibaba Cloud SDK for Java (V2.0)

aliyun-java-tea-openapi-sdk-managed-credentials-provider

Alibaba Cloud SDK for Java (V1.0)

aliyun-java-sdk-managed-credentials-provider

OSS SDK for Java V1

aliyun-oss-java-sdk-managed-credentials-provider

Message Queue for Apache RocketMQ TCP SDK for Java

ons-client-managed-credentials-provider

Python

SDK

Módulo do plug-in

Observações

Alibaba Cloud SDK for Python (V1.0)

aliyun-openapi-python-sdk-managed-credentials-provider

Apenas V1.0. Para V2.0, use o cliente de segredos ou o Alibaba Cloud SDK.

OSS Python SDK

aliyun-oss-python-sdk-managed-credentials-provider

Go

SDK

Módulo do plug-in

Observações

Alibaba Cloud SDK for Go (V1.0)

alibaba-cloud-sdk-go-managed-credentials-provider

Apenas V1.0. Para V2.0, use o cliente de segredos ou o Alibaba Cloud SDK.

OSS Go SDK

aliyun-oss-go-sdk-managed-credentials-provider

Pré-requisitos

Antes de começar, verifique se você tem:

  • Um usuário RAM cuja AccessKey seja gerenciada no KMS como um segredo RAM

  • Um Alibaba Cloud SDK listado em SDKs suportados

Etapa 1: Criar uma credencial de acesso

Escolha o cenário de acesso correspondente à sua configuração de rede.

Cenário 1: Gateway compartilhado (endpoint público ou VPC)

Utilize este cenário se sua aplicação se conectar ao KMS por meio de um endpoint público ou de um endpoint VPC. Há suporte a dois tipos de credenciais: função RAM de instância ECS e ClientKey.

Função RAM de instância ECS

Uma função RAM de instância ECS concede à instância ECS credenciais temporárias do Security Token Service (STS), permitindo que sua aplicação chame APIs do KMS sem uma AccessKey estática.

  1. Faça login no RAM console e crie uma função RAM com uma entidade confiável do tipo Elastic Compute Service.

    • Trusted Entity Type: Elastic Compute Service

    • Principal: Elastic Compute Service (ECS)

  2. Conceda permissão à função RAM para acessar o KMS. Estão disponíveis dois métodos:

  3. Faça login no ECS Management Console e anexe a função RAM à instância ECS.image

Para instruções detalhadas, consulte Funções RAM de instância.

ClientKey

Crie uma ClientKey usando o método padrão descrito em Criar um ponto de acesso de aplicação.

Importante

Ao configurar o ponto de acesso de aplicação (AAP):

  • Defina Network Type como Public ou VPC.

  • Defina o escopo da regra de permissão como Shared KMS Gateway.

Cenário 2: Gateway dedicado (não recomendado)

Use este cenário apenas se sua aplicação acessar o KMS por meio de um gateway dedicado de rede privada. Há suporte apenas a ClientKey.

Crie uma ClientKey usando um dos métodos a seguir. Para informações básicas sobre ClientKeys e AAPs, consulte Visão geral dos pontos de acesso de aplicação.

Método 1: Criação rápida

A criação rápida é adequada para testes e desenvolvimento. A ClientKey concede acesso a todos os recursos na instância KMS selecionada.

  1. Faça login no console do Key Management Service. Na barra de navegação superior, selecione uma região. No painel de navegação à esquerda, escolha Application Access > Multi-Cloud Access (formerly AAP).

  2. Na aba Application Access, clique em Create AAP e configure os seguintes parâmetros no painel Create AAP.

    Parâmetro

    Descrição

    Mode

    Selecione Quick Creation.

    Scope (KMS Instance)

    Selecione a instância KMS que sua aplicação precisa acessar.

    Application Access Point Name

    Insira um nome para o AAP.

    Authentication Method

    O padrão é ClientKey e não pode ser alterado.

    Default Permission Policy

    O padrão é key/* e secret/*, que concede acesso a todas as chaves e segredos na instância KMS. Não pode ser alterado.

  3. Clique em OK. Seu navegador baixará automaticamente os arquivos da ClientKey:

    • Credential (ClientKeyContent): clientKey_****.json

    • Password (ClientKeyPassword): clientKey_****_Password.txt

    Importante

    O arquivo da ClientKey e a senha são pareados e só podem ser baixados no momento da criação. Se você não os salvou, crie uma nova ClientKey.

Método 2: Criação padrão

A criação padrão permite configurar permissões de acesso refinadas. Siga as instruções em Criar um ponto de acesso de aplicação.

Importante

Ao configurar o AAP:

  • Defina Network Type como Private.

  • Defina o escopo da regra de permissão como o ID da instância KMS correspondente.

Etapa 2: Configurar parâmetros de tempo de execução

O plug-in lê sua configuração de um arquivo chamado managed_credentials_providers.properties no diretório de tempo de execução da sua aplicação. Crie o arquivo com o conteúdo mostrado abaixo para o seu tipo de credencial.

Se sua aplicação não conseguir localizar automaticamente o arquivo de configuração padrão, especifique o caminho do arquivo no código. Consulte os exemplos do SDK para detalhes.

Função RAM de instância ECS

credentials_type=ecs_ram_role
## The name of the ECS RAM role.
credentials_role_name=#credentials_role_name#
## The region of the associated KMS service.
cache_client_region_id=[{"regionId":"#regionId#"}]

ClientKey (gateway compartilhado)

## The type of the access credential.
credentials_type=client_key

## The password for the ClientKey.
## Provide one of the following — read from an environment variable or from a file.
client_key_password_from_env_variable=#your_client_key_private_key_password_environment_variable_name#
client_key_password_from_file_path=#your_client_key_private_key_password_file_path#

## The path to the ClientKey file (clientKey_******.json).
client_key_private_key_path=#your_client_key_private_key_file_path#

## The region of the associated KMS service.
cache_client_region_id=[{"regionId":"#regionId#"}]

ClientKey (gateway dedicado)

Use o parâmetro cache_client_dkms_config_info, que aceita um array JSON. Listar várias instâncias KMS melhora a disponibilidade e oferece suporte à recuperação de desastres.

Método 1: Ler a senha da ClientKey de uma variável de ambiente

cache_client_dkms_config_info=[{"regionId":"<your dkms regionId >","endpoint":"<your dkms endpoint>","passwordFromEnvVariable":"<YOUR_PASSWORD_ENV_VARIABLE>","clientKeyFile":"<your ClientKey file path>","ignoreSslCerts":false,"caFilePath":"<your CA certificate file path>"}]

Exemplo:

cache_client_dkms_config_info=[{"regionId":"cn-hangzhou","endpoint":"kst-hzz634e67d126u9p9****.cryptoservice.kms.aliyuncs.com","passwordFromEnvVariable":"passwordFromEnvVariable","clientKeyFile":"C:\RamSecretPlugin\src\main\resources\clientKey_KAAP.json","ignoreSslCerts":false,"caFilePath":"C:\RamSecretPlugin\src\main\resources\PrivateKmsCA_kst-hzz634e67d126u9p9****.pem"}]

Método 2: Ler a senha da ClientKey de um arquivo

O nome de arquivo padrão da senha é clientKey_****_Password.txt. Se você renomeou o arquivo, atualize o caminho adequadamente.

cache_client_dkms_config_info=[{"regionId":"<your dkms regionId >","endpoint":"<your dkms endpoint>","passwordFromFilePath":"< your password file path >","clientKeyFile":"<your Client Key file path>","ignoreSslCerts":false,"caFilePath":"<your CA certificate file path>"}]

Exemplo:

cache_client_dkms_config_info=[{"regionId":"cn-hangzhou","endpoint":"kst-hzz634e67d126u9p9****.cryptoservice.kms.aliyuncs.com","passwordFromFilePath":"C:\RamSecretPlugin\src\main\resources\clientKeyPassword.txt","clientKeyFile":"C:\RamSecretPlugin\src\main\resources\clientKey_KAAP.json","ignoreSslCerts":false,"caFilePath":"C:\RamSecretPlugin\src\main\resources\PrivateKmsCA_kst-hzz634e67d126u9p9****.pem"}]

Parâmetros de configuração

Parâmetro

Descrição

regionId

ID da região da instância KMS. Consulte Regiões e zonas.

endpoint

Nome de domínio da instância KMS no formato {instance ID}.kms.aliyuncs.com. Encontre-o na página Instances em Instance VPC Endpoint.

clientKeyFile

Caminho absoluto ou relativo para o arquivo JSON da ClientKey (clientKey_******.json).

passwordFromFilePath

Caminho para o arquivo contendo a ClientKeyPassword (clientKey_****_Password.txt por padrão).

passwordFromEnvVariable

Nome da variável de ambiente que contém a ClientKeyPassword.

ignoreSslCerts

Indica se deve ignorar a validação de certificado SSL. Defina como false em produção. Quando true, caFilePath não é obrigatório.

caFilePath

Caminho absoluto ou relativo para o arquivo de certificado CA da instância KMS. Baixe-o na página Instances em Instance CA Certificate > Download.

Importante

O arquivo da ClientKey e sua senha possuem uma correspondência biunívoca. Ambos estão disponíveis apenas no momento da criação da ClientKey. Se você não os salvou, crie uma nova ClientKey no AAP. Consulte Criar um ponto de acesso de aplicação.

Etapa 3: Usar o plug-in de segredo RAM

Todos os exemplos seguem o mesmo padrão: crie um cliente proxy usando o nome do segredo e, em seguida, chame as APIs de serviço de nuvem normalmente. O plug-in gerencia a recuperação e a atualização de credenciais de forma transparente.

Java

Alibaba Cloud SDK for Java (V2.0)

Compatibilidade com Java 9+

Este plug-in usa CGLIB para proxy dinâmico de classes. No Java 9 ou posterior, adicione o seguinte parâmetro JVM na inicialização para evitar java.lang.reflect.InaccessibleObjectException:

--add-opens java.base/java.lang=ALL-UNNAMED

Pela linha de comando:

java --add-opens java.base/java.lang=ALL-UNNAMED -jar your-application.jar

Para IDEs como IntelliJ IDEA ou Eclipse, adicione este parâmetro às opções da VM.

Instalação

Adicione o plug-in ao seu pom.xml. Instale a versão mais recente — consulte o repositório source para a versão atual.

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-tea-openapi-sdk-managed-credentials-provider</artifactId>
    <version>[1.3.5,]</version>
</dependency>

Exemplo de uso: chamar ECS DescribeInstances

Adicione a dependência do ECS SDK:

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>ecs20140526</artifactId>
    <version>7.1.0</version>
</dependency>

Em seguida, crie um cliente proxy e chame a API:

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeInstancesResponse;
import com.aliyun.kms.secretsmanager.plugin.tea.openapi.ProxyClientCreator;
import com.google.gson.Gson;

public class AliyunTeaOpenApiProviderSample {

    public static void main(String[] args) throws Exception {
        // The name of the RAM secret you created in KMS.
        String secretName = "your-secret-name";

        /*
          If the application cannot read the default configuration file
          (managed_credentials_providers.properties) from the classpath or the
          executable JAR file, or if you need a custom file name, uncomment the
          following line. The file is resolved in this order:
          1. If "your-config-name" is an absolute path, that file is read.
          2. If "your-config-name" is a filename only, the classpath is checked
             first, then the executable JAR file.
        */
        //ConfigLoader.setConfigName("your-config-name");

        // Configure the OpenAPI client endpoint.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.endpoint = "your-product-endpoint"; // Replace with the actual service endpoint.

        // Create a proxy client backed by the RAM secret plug-in.
        Client client = ProxyClientCreator.createClient(config, Client.class, secretName);

        // Call the cloud service API.
        com.aliyun.ecs20140526.models.DescribeInstancesRequest request =
            new com.aliyun.ecs20140526.models.DescribeInstancesRequest();
        request.setRegionId("cn-hangzhou");
        DescribeInstancesResponse response = client.describeInstances(request);

        System.out.println(new Gson().toJson(response.getBody()));
    }
}

Alibaba Cloud SDK for Java (V1.0)

Instalação

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>[4.3.2,5.0.0]</version>
</dependency>
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core-managed-credentials-provider</artifactId>
    <version>[1.3.1,]</version>
</dependency>

Instale a versão mais recente. Consulte o repositório source para a versão atual.

Exemplo de uso: chamar ECS DescribeInstanceStatus

Adicione a dependência do ECS SDK:

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-ecs</artifactId>
    <version>5.11.20</version>
</dependency>

Em seguida, crie um cliente proxy e chame a API:

import com.aliyuncs.IAcsClient;
import com.aliyuncs.ecs.model.v20140526.DescribeInstanceStatusRequest;
import com.aliyuncs.ecs.model.v20140526.DescribeInstanceStatusResponse;
import com.aliyun.kms.secretsmanager.plugin.sdkcore.ProxyAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;

public class AliyunSdkProviderSample {
    public static void main(String[] args) {
        String secretName = "******";

        /*
          To use a custom configuration file name, uncomment the following line.
          File resolution order:
          1. Absolute path — read that file directly.
          2. Filename only — check the classpath, then the executable JAR file.
        */
        //ConfigLoader.setConfigName("your-config-name");

        // Create a proxy ACS client backed by the RAM secret plug-in.
        IAcsClient client = null;
        try {
            client = new ProxyAcsClient("<the regionId of ECS>", secretName);
        } catch (ClientException e) {
            e.printStackTrace();
        }

        // Call the ECS API.
        DescribeInstanceStatusRequest request = new DescribeInstanceStatusRequest();
        try {
            DescribeInstanceStatusResponse response = client.getAcsResponse(request);
        } catch (ServerException e) {
            e.printStackTrace();
        } catch (ClientException e) {
            e.printStackTrace();
        }

        // Release plug-in resources.
        client.shutdown();
    }
}

OSS SDK for Java

Instalação

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>4.5.17</version>
</dependency>
<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>[2.1.0,3.10.2]</version>
    <exclusions>
        <exclusion>
            <groupId>com.aliyun</groupId>
            <artifactId>aliyun-java-sdk-kms</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-sdk-oss-managed-credentials-provider</artifactId>
    <version>[1.3.1,]</version>
</dependency>

Instale a versão mais recente. Consulte o repositório source para a versão atual.

Exemplo de uso: chamar OSS listBuckets

import com.aliyun.kms.secretsmanager.plugin.oss.ProxyOSSClientBuilder;
import com.aliyun.oss.OSS;
import com.aliyun.oss.model.Bucket;

import java.util.List;

public class OssProviderSample {

    public static void main(String[] args) throws Exception {
        String secretName = "******";
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";

        /*
          To use a custom configuration file name, uncomment the following line.
          File resolution order:
          1. Absolute path — read that file directly.
          2. Filename only — check the classpath, then the executable JAR file.
        */
        //ConfigLoader.setConfigName("your-config-name");

        // Create a proxy OSS client backed by the RAM secret plug-in.
        OSS ossClient = new ProxyOSSClientBuilder().build(endpoint, secretName);

        // Call the OSS API.
        List<Bucket> buckets = ossClient.listBuckets();
        for (Bucket bucket : buckets) {
            if (bucket != null) {
                // Your business logic goes here.
            }
        }

        // Release plug-in resources.
        ossClient.shutdown();
    }
}

Python

Alibaba Cloud SDK for Python (V1.0)

Instalação

pip install aliyun-openapi-python-sdk-managed-credentials-provider

É necessária a versão 0.1.0 ou posterior. Consulte o repositório source para a versão atual.

Exemplo de uso

from aliyun_sdk_secretsmanager_sdk_core_plugin.proxy_acs_client import ProxyAcsClient

region = "cn-hangzhou"
secretName = "******"

# Create a proxy ACS client backed by the RAM secret plug-in.
client = ProxyAcsClient(region_id=region, secret_name=secretName)

# Call Alibaba Cloud services using the client — no other code changes required.
...

# Release plug-in resources.
client.shutdown()

OSS Python SDK

Instalação

pip install aliyun-oss-python-sdk-managed-credentials-provider

É necessária a versão 0.1.0 ou posterior. Consulte o repositório source para a versão atual.

Exemplo de uso

from aliyun_sdk_secretsmanager_oss_plugin.proxy_bucket import ProxyBucket
from itertools import islice

endpoint = "******"
secret_name = "******"
bucket_name = "******"

bucket = ProxyBucket(secret_name=secret_name, endpoint=endpoint, bucket_name=bucket_name)
objects = bucket.list_objects()
for b in islice(objects.object_list, 10):
    print(b.key)
bucket.shutdown()

Go

Comportamento específico do Go

O plug-in de segredo RAM para Go não realiza novas tentativas automaticamente ao detectar um erro InvalidAccessKeyId. A atualização de credenciais depende de um mecanismo agendado executado a cada 6 horas.

Se você rotacionar segredos manualmente, defina a janela de rotação para pelo menos 12 horas a fim de evitar interrupções de tarefas devido a credenciais expiradas. Para janelas de rotação mais curtas, use uma das soluções alternativas nas Perguntas frequentes.

Alibaba Cloud SDK for Go (V1.0)

Instalação

Importante

Este plug-in requer alibaba-cloud-sdk-go em uma versão inferior a v1.63.0. Verifique a versão no arquivo go.mod do plug-in antes de instalar.

Instale a versão mais recente do repositório source.

Método 1 — Adicionar ao go.mod:

require (
    github.com/aliyun/aliyun-sdk-managed-credentials-providers-go/aliyun-sdk-managed-credentials-providers/alibaba-cloud-sdk-go-managed-credentials-provider vX.X.X
)

Método 2 — Usar go get:

go get -u github.com/aliyun/aliyun-sdk-managed-credentials-providers-go/aliyun-sdk-managed-credentials-providers/alibaba-cloud-sdk-go-managed-credentials-provider

Exemplo de uso: chamar ECS DescribeInstances

package sample

import (
    "fmt"
    "github.com/aliyun/alibaba-cloud-sdk-go/services/ecs"
    sdkcoreprovider "github.com/aliyun/aliyun-sdk-managed-credentials-providers-go/aliyun-sdk-managed-credentials-providers/alibaba-cloud-sdk-go-managed-credentials-provider/sdk"
)

func main() {
    secretName := "********"
    regionId := "cn-hangzhou"

    // Create a proxy client backed by the RAM secret plug-in.
    client, err := sdkcoreprovider.GetClient(&ecs.Client{}, regionId, secretName)
    if err != nil {
        fmt.Println(err)
        return
    }
    ecsClient := client.(*ecs.Client)

    request := ecs.CreateDescribeInstancesRequest()
    instancesResponse, err := ecsClient.DescribeInstances(request)
    if err != nil {
        fmt.Println(err)
        return
    }

    for _, instance := range instancesResponse.Instances.Instance {
        // Your business logic goes here.
    }
}

OSS Go SDK

Instalação

Importante

Este plug-in requer alibaba-cloud-sdk-go em uma versão inferior a v1.63.0. Verifique a versão no arquivo go.mod do plug-in antes de instalar.

Instale a versão mais recente do repositório source.

Método 1 — Adicionar ao go.mod:

require (
    github.com/aliyun/aliyun-sdk-managed-credentials-providers-go/aliyun-sdk-managed-credentials-providers/aliyun-oss-go-sdk-managed-credentials-provider vX.X.X
)

Método 2 — Usar go get:

go get -u github.com/aliyun/aliyun-sdk-managed-credentials-providers-go/aliyun-sdk-managed-credentials-providers/aliyun-oss-go-sdk-managed-credentials-provider

Exemplo de uso

package sample

import (
    "fmt"
    ossprovider "aliyun-oss-go-sdk-managed-credentials-provider/sdk"
)

func main() {
    secretName := "********"
    endpoint := "https://oss-cn-hangzhou.aliyuncs.com"

    // Create a proxy OSS client backed by the RAM secret plug-in.
    client, err := ossprovider.New(endpoint, secretName)
    if err != nil {
        fmt.Println(err)
        return
    }

    result, err := client.ListBuckets()
    if err != nil {
        fmt.Println(err)
        return
    }
    for _, bucket := range result.Buckets {
        // Your business logic goes here.
    }

    // Release plug-in resources.
    client.Shutdown()
}

Perguntas frequentes

O plug-in de segredo RAM para Go retorna InvalidAccessKeyId após a expiração de uma credencial. O que devo fazer?

O plug-in Go não realiza novas tentativas automaticamente em caso de InvalidAccessKeyId, portanto, um segredo rotacionado manualmente pode expirar antes que a atualização agendada de 6 horas ocorra. Use uma das seguintes abordagens:

  1. Aguardar a atualização automática — Para segredos rotacionados automaticamente, o mecanismo de atualização agendada do plug-in (executado a cada 6 horas) busca o novo segredo automaticamente.

  2. Atualização sob demanda — Capture a exceção e chame sdk.RefreshSecretInfo(secretName) para buscar o segredo mais recente imediatamente.

  3. Atualização agendada — Configure uma tarefa periódica que chame sdk.RefreshSecretInfo(secretName) com uma frequência correspondente à sua janela de rotação, garantindo que o novo segredo seja sempre buscado antes que o atual expire.

  4. Ajustar a janela de rotação — Para segredos rotacionados manualmente, defina a janela de rotação para pelo menos 12 horas. Isso proporciona tempo suficiente para que a atualização agendada de 6 horas atualize o cache antes que a credencial antiga expire.