Todos os produtos
Search
Central de documentação

Terraform:Autenticação do Terraform

Última atualização: Jun 28, 2026

O Alibaba Cloud Terraform Provider oferece suporte a diversos métodos de autenticação. Escolha um deles com base no seu ambiente de execução e nos requisitos de segurança.

Prioridade dos métodos de autenticação

Ao configurar o provedor da Alibaba Cloud, selecione um método de autenticação. O provedor busca as credenciais na seguinte ordem e interrompe a busca na primeira correspondência encontrada:

  1. Configuração estática: O provedor lê primeiramente os parâmetros access_key, secret_key, security_token ou ecs_role_name, caso estejam especificados explicitamente no bloco do provedor.

  2. Variáveis de ambiente: Se nenhuma configuração estática for encontrada, o provedor lê as variáveis de ambiente do sistema, como ALICLOUD_ACCESS_KEY e ALICLOUD_SECRET_KEY.

  3. Arquivo de configuração compartilhada:

    1. Configuração estática: O provedor lê as informações de autenticação do perfil especificado no arquivo de configuração compartilhada local. Essas informações podem incluir um par de AccessKey, ram_role_arn, ram_role_name ou sts_token.

    2. Configuração avançada: Caso o arquivo de configuração compartilhada não contenha uma configuração estática, mas esteja configurado com CloudSSO, OAuth, um programa externo ou uma função RAM encadeável (ChainableRamRoleArn), o provedor invoca o plugin correspondente para obter uma credencial temporária do Security Token Service (STS).

  4. Credencial via URL: Se nenhum dos métodos acima fornecer uma credencial, o provedor tenta recuperar as credenciais da URL especificada por credentials_uri.

Recomendações de segurança

Para ambientes de produção, utilize estes métodos baseados em credenciais temporárias:

  • Função RAM de instância para ECS

  • Assunção de função RAM (AssumeRole)

  • Assunção de função via IdP OIDC

Vantagens de segurança:

  • Elimina AccessKeys de longa duração codificadas diretamente no código, reduzindo o risco de comprometimento de chaves.

  • Limita a duração das permissões por meio da expiração das credenciais.

Suporte a autorização refinada

Para um controle de acesso refinado por aplicação, equipe ou projeto, utilize a assunção de função RAM e a assunção de função via IdP OIDC. Associe funções e políticas dedicadas a cada carga de trabalho do Terraform para aplicar o princípio do menor privilégio.

Métodos de autenticação do Terraform

O Alibaba Cloud Terraform Provider oferece suporte aos seguintes métodos de autenticação:

Método de autenticação

Instruções

Casos de uso

Configuração estática

(access_key)

Defina um par de AccessKey diretamente no arquivo de configuração.

  • Desenvolvimento e testes.

  • Fluxos de trabalho de CI/CD.

Variáveis de ambiente

(ALIBABA_CLOUD_ACCESS_KEY)

Lê as informações do AccessKey a partir de variáveis de ambiente.

  • Desenvolvimento e testes.

  • Ambientes de execução isolados, como instâncias ECS.

Função RAM de instância para ECS

(ecs_role_name)

Obtém credenciais temporárias dos metadados da instância ECS por meio da função RAM associada.

Execução do Terraform em uma instância ECS.

Assunção de função OIDC (assume_role_with_oidc)

Assume uma função RAM por meio de um provedor de identidade OIDC para obter credenciais temporárias.

Execução do Terraform em um cluster Kubernetes com suporte a OIDC, como o Alibaba Cloud ACK.

Assunção de função

(assume_role)

Assume uma função RAM para obter credenciais temporárias.

  • Gerenciamento de recursos em múltiplas contas.

  • Fluxos de trabalho de CI/CD.

Credencial via URL

(credentials_uri)

Recupera credenciais temporárias de uma URI especificada.

Serviços personalizados de credenciais.

Arquivo de configuração compartilhada

(profile)

Gerencie múltiplos perfis de credenciais em um único arquivo de configuração da CLI da Alibaba Cloud. Métodos suportados:

  • AK

  • STSToken

  • ECSRamRole

  • CloudSSO

  • ChainableRamRoleArn

  • External

  • OAuth

  • Gerenciamento de recursos em múltiplas contas e regiões.

  • Gerenciamento de recursos em múltiplos ambientes.

Configuração estática

Defina as credenciais de acesso diretamente no bloco provider de um arquivo de configuração do Terraform.

Parâmetros

Parâmetro

Descrição

Valor de exemplo

access_key

O ID do AccessKey.

abcd***

secret_key

O segredo do AccessKey.

abcd***

security_token (Opcional)

O token de segurança de uma credencial STS temporária.

abcd***

provider "alicloud" {
  access_key = "<Your AccessKey ID>"
  secret_key = "<Your AccessKey secret>"
  # If you use an STS credential, configure security_token.
  # security_token = "<Your STS token>"
}

Exemplo de configuração

Por questões de segurança, passe as credenciais como variáveis em vez de codificá-las diretamente. Não defina valores padrão:

variable "access_key_id" {
  description = "The AccessKey ID for operating your infrastructure"
}
variable "access_key_secret" {
  description = "The AccessKey Secret for operating your infrastructure"
}
variable "security_token" {
  description = "The Security Token for operating your infrastructure"
}
provider "alicloud" {
  access_key = var.access_key_id
  secret_key = var.access_key_secret
  # If you use an STS credential, configure security_token.
  # security_token = var.security_token
}

Use o comando terraform com a opção -var para passar os valores das variáveis:

$ terraform plan -var access_key_id="<Your AccessKey ID>" -var access_key_secret="<Your AccessKey secret>" -var security_token="<Your STS token>"

Variáveis de ambiente

Armazene as credenciais em variáveis de ambiente. O Terraform faz a leitura dessas variáveis quando não existe nenhuma configuração estática.

Parâmetros

Parâmetro

Descrição

Valor de exemplo

ALICLOUD_ACCESS_KEY

O ID do AccessKey.

abcd***

ALICLOUD_SECRET_KEY

O segredo do AccessKey.

abcd***

ALICLOUD_SECURITY_TOKEN (Opcional)

O token de segurança de uma credencial STS temporária.

abcd***

Exemplo de configuração

Linux/macOS
Nota

As variáveis de ambiente definidas com export são válidas apenas para a sessão atual do shell. Para torná-las persistentes, adicione o comando export ao arquivo .bash_profile ou .zshrc.

# AccessKey ID
$ export ALICLOUD_ACCESS_KEY="<Your AccessKey ID>"
# AccessKey Secret
$ export ALICLOUD_SECRET_KEY="<Your AccessKey secret>"
# If you use an STS credential, configure security_token.
$ export ALICLOUD_SECURITY_TOKEN="<Your STS token>"
Windows
  1. Clique com o botão direito em This PC na área de trabalho e selecione Properties > Advanced system settings > Environment Variables.

  2. Em System variables ou User variables, clique em New para criar as seguintes variáveis de ambiente: ALICLOUD_ACCESS_KEY, ALICLOUD_SECRET_KEY e ALICLOUD_SECURITY_TOKEN (opcional).

Após definir as variáveis de ambiente, declare apenas as informações que não sejam credenciais no bloco provider:

provider "alicloud" {
  region = "cn-hangzhou"
}

Também é possível definir a região por meio da variável de ambiente ALICLOUD_REGION. Caso nenhuma região seja especificada no bloco provider ou na variável de ambiente, cn-beijing será usado por padrão.

As variáveis de ambiente são mais práticas e seguras do que a configuração estática.

Função RAM de instância para ECS

Quando o Terraform é executado em uma instância ECS, autentique-se usando uma função RAM de instância. A instância obtém e renova automaticamente as credenciais temporárias, eliminando a necessidade de configurar o AccessKey. Funções RAM de instância.

Parâmetros

Nome do parâmetro

Descrição

Valor de exemplo

ecs_role_name

O nome da função RAM associada à instância ECS.

terraform-ecs-role

Exemplo de configuração

  1. Prepare uma instância ECS com acesso à rede pública.

  2. Crie uma função RAM e associe-a à instância ECS.

  3. No bloco provider, defina o parâmetro ecs_role_name com o nome da função RAM:

provider "alicloud" {
  ecs_role_name = "<Name of the RAM role attached to the ECS instance>"
}

Você também pode definir esse parâmetro usando a variável de ambiente ALICLOUD_ECS_ROLE_NAME.

A autenticação por função RAM de instância é recomendada ao executar o Terraform no ECS.

Assunção de função OIDC

A assunção de função OIDC obtém credenciais temporárias assumindo uma função RAM por meio de uma identidade OIDC, em vez de usar um AccessKey. Gerenciar IdPs OIDC.

Parâmetros

Configure os seguintes parâmetros no bloco assume_role_with_oidc:

Nome do parâmetro

Descrição

Valor de exemplo

oidc_provider_arn (Obrigatório)

O ARN do provedor de identidade OIDC, no formato: acs:ram::<Alibaba Cloud account ID>:oidc-provider/<RAM Provider role name>. Também configurável via ALIBABA_CLOUD_OIDC_PROVIDER_ARN.

acs:ram::151192xxxxxx:oidc-provider/ackrole

oidc_token (Opcional)

Um token OIDC emitido por um IdP externo. Defina oidc_token ou oidc_token_file. Também configurável via ALIBABA_CLOUD_OIDC_TOKEN.

eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.**

oidc_token_file (Opcional)

O caminho absoluto do arquivo que armazena o token OIDC. Defina oidc_token ou oidc_token_file. Também configurável via ALIBABA_CLOUD_OIDC_TOKEN_FILE.

/var/run/secrets/oidc/token

role_arn (Obrigatório)

O ARN da função RAM a ser assumida, no formato acs:ram::<Alibaba Cloud account ID>:role/<RAM role name>. Também configurável via ALIBABA_CLOUD_ROLE_ARN.

acs:ram::151192xxxxxx:role/k8srole

policy (Opcional)

Uma política de acesso RAM. Se definida, as permissões efetivas serão a interseção entre esta política e as políticas associadas a role_arn. Se não for definida, aplicam-se as permissões da função role_arn.

{"Version":"1","Statement":[{"Effect":"Allow","Action":"oss:ListBuckets","Resource":"acs:oss:oss-cn-hangzhou::"}]}

role_session_name (Opcional)

Um nome personalizado para a sessão da função, geralmente definido como a identidade do chamador. Padrão: terraform. Pode ser definido via ALIBABA_CLOUD_ROLE_SESSION_NAME.

username

session_expiration (Opcional)

Período de validade em segundos. Intervalo: de 900 até MaxSessionDuration da função (padrão: 3600). Aumente para até 43.200 segundos atualizando as informações da função.

900

Exemplo de configuração

Este método chama a API AssumeRoleWithOIDC - Obter uma credencial temporária para uma função RAM de um IdP OIDC para SSO baseado em função. Antes de configurar, prepare o seguinte:

  1. Crie um IdP OIDC, obtenha um token OIDC do IdP externo e registre o ARN do IdP OIDC e o token OIDC.

  2. Crie uma função RAM com um provedor de identidade como entidade confiável, conceda à função as permissões necessárias (como AliyunOSSFullAccess) e registre o ARN da função.

  3. (Opcional) Escreva uma política RAM personalizada para controle de acesso refinado. Essa política fará interseção com as permissões associadas à função.

Adicione o seguinte ao bloco provider:

provider "alicloud" {
  assume_role_with_oidc {
    oidc_provider_arn  = "<ARN of the OIDC IdP>"
    oidc_token         = "<OIDC token issued by the external IdP>"
    role_arn           = "<ARN of the RAM role>"
    policy             = "<Content of the RAM access policy>"
    role_session_name  = "<Custom role session name>"
    session_expiration = <Maximum validity period of the temporary access credential>
  }
}

O ACK oferece suporte a RRSA (RAM Roles for Service Accounts) para criar automaticamente IdPs OIDC e emitir tokens. Usar RRSA para autorizar diferentes pods a acessar diferentes serviços de nuvem. Após ativar o RRSA, o componente ack-pod-identity-webhook injeta as variáveis de ambiente ALIBABA_CLOUD_OIDC_PROVIDER_ARN, ALIBABA_CLOUD_OIDC_TOKEN_FILE e ALIBABA_CLOUD_ROLE_ARN nos pods. Em um pod do ACK, a configuração simplifica-se para:

provider "alicloud" {
  region = "cn-hangzhou"
  assume_role_with_oidc {
    policy             = <<EOF
    {
      "Version": "1",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "oss:ListBuckets",
          "Resource": "acs:oss:oss-cn-hangzhou:*:*"
        }
      ]
    }
    EOF
    session_name = "terraform-assume-role-session"
    session_expiration = 1000
  }
}

Sem uma policy personalizada, conceda permissões diretamente à função RAM:

provider "alicloud" {
  region = "cn-hangzhou"
  assume_role_with_oidc {
    session_name = "terraform-assume-role-session"
    session_expiration = 1000
  }
}

Assunção de função

A assunção de função (AssumeRole) permite a separação de permissões e o acesso entre contas. Uma identidade existente (usuário RAM ou função de instância ECS) assume uma função RAM para obter credenciais temporárias.

Parâmetros

Parâmetros suportados:

  1. access_key e secret_key: O AccessKey do usuário RAM que assume a função. O usuário deve ter a permissão sts:AssumeRole. Também pode ser definido via variáveis de ambiente.

  2. assume_role: Um bloco de configuração com os seguintes parâmetros:

Parâmetro

Descrição

Valor de exemplo

role_arn (Obrigatório)

O ARN da função RAM a ser assumida, no formato acs:ram::1234567890123456:role/<RAM role name>.

acs:ram::151192xxxxxx:role/k8srole

policy (Opcional)

Uma política de acesso RAM. Se definida, as permissões efetivas serão a interseção entre esta política e as políticas associadas a role_arn. Se não for definida, aplicam-se as permissões da função role_arn.

{"Version":"1","Statement":[{"Effect":"Allow","Action":"oss:ListBuckets","Resource":"acs:oss:oss-cn-hangzhou::"}]}

session_name (Opcional)

O nome personalizado da sessão da função, usado para distinguir operadores nos logs de auditoria. Padrão: terraform.

terraform

session_expiration (Opcional)

Período de validade em segundos. Intervalo: de 900 até MaxSessionDuration da função (padrão: 3600). Aumente para até 43.200 segundos Atualizar informações da função.

3600

external_Id (Opcional)

Um ID externo para a função, usado para evitar o problema de deputado confuso. Usar um ID externo para evitar o problema de deputado confuso.

ID

Exemplo de configuração

Este método chama a API AssumeRole - Obter uma credencial temporária para uma função RAM. Antes de configurar, prepare o seguinte:

  1. Crie um usuário RAM e conceda a política AliyunSTSAssumeRoleAccess (ou uma política personalizada que contenha a permissão sts:AssumeRole).

  2. Crie um AccessKey para o usuário RAM.

  3. Crie uma função RAM cuja entidade confiável seja uma conta Alibaba Cloud, conceda a ela as permissões necessárias (como AliyunOSSFullAccess) e registre seu ARN.

  4. (Opcional) Escreva uma política RAM personalizada para controle de acesso refinado.

Configure o bloco provider:

provider "alicloud" {
  # The AccessKey ID of the RAM user that calls AssumeRole.
  access_key = "<AccessKey ID of the RAM user>"
  # The AccessKey secret of the RAM user that calls AssumeRole.
  secret_key = "<AccessKey secret of the RAM user>"
  assume_role {
    role_arn           = "<ARN of a RAM role>"
    policy             = "<Content of a RAM access policy>"
    session_name       = "<Custom role session name>"
    session_expiration = <Maximum validity period of the temporary access credential>
  }
}

Este exemplo lista buckets do OSS em cn-hangzhou usando assunção de função. Os parâmetros access_key e secret_key são definidos via variáveis de ambiente:

provider "alicloud" {
  # For security, the access_key and secret_key here are set as environment variables.
  region = "cn-hangzhou"
  assume_role {
    role_arn           = "acs:ram::11827xxxxxx:role/tf-assume-role"
    policy             = <<EOF
    {
      "Version": "1",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "oss:ListBuckets",
          "Resource": "acs:oss:oss-cn-hangzhou:*:*"
        }
      ]
    }
    EOF
    session_name       = "terraform-assume-role-session"
    session_expiration = 1000
  }
}
Nota

Antes de executar este exemplo, certifique-se de que a função tf-assume-role tenha a permissão AliyunOSSFullAccess. Caso contrário, o acesso ao OSS falhará.

Em uma instância ECS, use uma função RAM de instância em vez de codificar credenciais diretamente. Conceda AliyunSTSAssumeRoleAccess à função RAM da instância:

provider "alicloud" {
  ecs_role_name = "<Name of the RAM role attached to the ECS instance>"
  region        = "cn-hangzhou"
  assume_role {
    role_arn           = "acs:ram::11827xxxxxx:role/tf-assume-role"
    policy             = <<EOF
    {
      "Version": "1",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "oss:ListBuckets",
          "Resource": "acs:oss:oss-cn-hangzhou:*:*"
        }
      ]
    }
    EOF
    session_name       = "terraform-assume-role-session"
    session_expiration = 1000
  }
}

Credencial via URL

Recupera credenciais de uma URI especificada.

Parâmetros

Parâmetro

Descrição

Valor de exemplo

credentials_url

Uma URI que retorna uma credencial temporária. Deve retornar HTTP 200 com conteúdo de credencial válido.

http://credentials.uri/

region

A região e zona padrão.

Alguns serviços não oferecem suporte a acesso entre regiões. Defina este valor como a região do seu recurso.

cn-hangzhou

Exemplo de configuração

provider "alicloud" {
  region = "cn-hangzhou"
  credentials_url= "http://credentials.uri/"
}

Arquivo de configuração compartilhada

O Terraform lê as credenciais do arquivo config.json da CLI da Alibaba Cloud. Configure vários tipos de credenciais em um único arquivo e referencie-os pelo nome do profile. Configurar credenciais.

Caminhos padrão dos arquivos:

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

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

Exemplo de configuração

Use profile para especificar o nome da credencial no bloco provider. Se o arquivo não estiver no caminho padrão, defina shared_credentials_file:

provider "alicloud" {
  region                  = "cn-hangzhou"
  shared_credentials_file = "~/.aliyun/config.json"
  profile                 = "TerraformTest"
}

Exemplo de config.json:

{
    "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": "External",
            "process_command": "<YOUR_COMMAND>",
            "region_id": "<REGION_ID>",
            "output_format": "json",
            "language": "en"
        },
        {
            "name": "<PROFILE_NAME5>",
            "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_NAME6>",
            "mode": "ChainableRamRoleArn",
            "source_profile": "<PROFILE_NAME>",
            "ram_role_arn": "<ROLE_ARN>",
            "ram_session_name": "<ROLE_SESSION_NAME>",
            "expired_seconds": 3600
        },
        {
            "name": "<PROFILE_NAME7>",
            "mode": "CloudSSO",
            "cloud_sso_sign_in_url": "https://******/login",
            "access_token": "eyJraWQiOiJiYzViMzUwYy******",
            "cloud_sso_access_token_expire": 1754316142,
            "cloud_sso_access_config": "ac-00s1******",
            "cloud_sso_account_id": "151266******"
        },
        {
            "name": "<PROFILE_NAME8>",
            "mode": "OAuth",
            "access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
            "access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
            "sts_token": "<SECURITY_TOKEN>",
            "region_id": "<REGION_ID>",
            "output_format": "json",
            "language": "<zh|en>",
            "sts_expiration": "<STS_EXPIRATION>",
            "oauth_access_token": "<OAUTH_ACCESS_TOKEN>",
            "oauth_refresh_token": "<OAUTH_REFRESH_TOKEN>",
            "oauth_access_token_expire": 1754316142,
            "oauth_site_type": "<CN|EN>"
        }
    ]
}

No arquivo config.json, o parâmetro mode especifica o tipo de credencial:

  • AK: Usa o AccessKey do usuário como credencial.

  • StsToken: Usa um token STS como credencial.

  • RamRoleArn: Obtém a credencial usando o ARN de uma função RAM.

  • EcsRamRole: Obtém a credencial usando a função RAM associada a uma instância ECS.

  • External: Obtém uma credencial executando um comando externo.

  • OIDC: Obtém a credencial usando um ARN de IdP OIDC e um token OIDC.

  • ChainableRamRoleArn: Cadeia de funções. Usa source_profile para referenciar outra credencial no config.json e obtém uma nova credencial por meio de assunção de função.

  • OAuth: Credencial obtida fazendo login na CLI usando OAuth.

  • CloudSSO: Credencial obtida por um usuário do CloudSSO via CLI da Alibaba Cloud.