AWS Command Line Interface
Guia do usuário

Assumir uma função do IAM na AWS CLI

Uma função do AWS Identity and Access Management (IAM) é uma ferramenta de autorização que permite que um usuário do IAM obtenha permissões adicionais (ou diferentes) ou obtenha permissões para executar ações em uma conta diferente da AWS.

Você pode configurar a AWS Command Line Interface (AWS CLI) para usar uma função do IAM definindo um perfil para a função no arquivo ~/.aws/config.

O exemplo a seguir mostra um perfil de função chamado marketingadmin. Se você executar comandos com --profile marketingadmin (ou especificá-los com a variável de ambiente AWS_DEFAULT_PROFILE), a CLI usará as permissões atribuídas ao perfil user1 para assumir a função com o nome de recurso da Amazon (ARN) arn:aws:iam::123456789012:role/marketingadminrole. Você pode executar quaisquer operações que forem permitidas pelas permissões atribuídas a essa função.

[profile marketingadmin] role_arn = arn:aws:iam::123456789012:role/marketingadminrole source_profile = user1

Você deve especificar um source_profile que aponte para um perfil nomeado separado que contenha credenciais de usuário do IAM com permissão para assumir a função. No exemplo anterior, o perfil marketingadmin usa as credenciais no perfil user1. Quando você especifica que um comando da AWS CLI deve usar o perfil marketingadmin, a CLI automaticamente procura as credenciais para o perfil user1 vinculado e as utiliza para solicitar credenciais temporárias para a função especificada do IAM. A CLI usa a operação sts:AssumeRole em segundo plano para fazer isso. Essas credenciais temporárias são usadas para executar o comando de CLI solicitado. A função especificada deve ter políticas de permissão do IAM associadas que permitam a execução do comando de CLI solicitado.

Se você deseja executar um comando de CLI de dentro de uma instância do Amazon EC2, use uma função do IAM associada a um perfil de instância do Amazon EC2 ou uma função de contêiner do Amazon ECS. Isso permite que você evite armazenar chaves de acesso de longa duração em suas instâncias. Para isso, use credential_source (em vez de source_profile) para especificar como localizar as credenciais. O atributo credential_source oferece suporte aos seguintes valores:

  • Environment – para recuperar as credenciais de variáveis de ambiente.

  • Ec2InstanceMetadata – para usar a função do IAM associada ao perfil de instância do Amazon EC2.

  • EcsContainer – para usar a função do IAM associada ao contêiner do Amazon ECS.

O exemplo a seguir mostra a mesma função marketingadminrole assumida fazendo referência a um perfil de instância do Amazon EC2:

[profile marketingadmin] role_arn = arn:aws:iam::123456789012:role/marketingadminrole credential_source = Ec2InstanceMetadata

Para obter mais informações, consulte Variáveis de configuração da CLI da AWS.

Configurar e usar uma função

Ao executar comandos usando um perfil que especifica uma função do IAM, a AWS CLI usa as credenciais do perfil de origem para chamar AWS Security Token Service (AWS STS) e solicitar credenciais temporárias para a função especificada. O usuário no perfil de origem deve ter permissão para chamar sts:assume-role para a função no perfil especificado. A função deve ter uma relação de confiança que permita que o usuário no perfil de origem assuma a função. Geralmente, o processo de recuperar e depois usar credenciais temporárias para uma função é chamado de assumir a função.

Você pode criar uma nova função no IAM com as permissões que você deseja que os usuários assumam. Para isso, siga o procedimento em Como criar uma função para conceder permissões a um usuário do IAM no Guia do usuário do AWS Identity and Access Management. Se a função e o usuário do IAM do perfil de origem estão na mesma conta, é possível inserir seu próprio ID de conta ao configurar a relação de confiança da função.

Depois de criar a função, modifique a relação de confiança para permitir que o usuário do IAM (ou os usuários da conta da AWS) a assumam.

O exemplo a seguir mostra uma política de confiança que pode ser associada a uma função. Essa política permite que a função seja assumida por qualquer usuário do IAM na conta 123456789012, se o administrador dessa conta explicitamente conceder a permissão sts:assumerole ao usuário.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:root" }, "Action": "sts:AssumeRole" } ] }

A política de confiança não concede permissões. O administrador da conta deve delegar a permissão para assumir a função para usuários individuais, anexando uma política com as permissões apropriadas. O exemplo a seguir mostra uma política que pode ser associada a um usuário do IAM permitindo que o usuário assuma apenas a função marketingadminrole. Para obter mais informações sobre como conceder a um usuário acesso para assumir uma função, consulte Como conceder a um usuário permissão para alternar funções no Guia do usuário do IAM.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::123456789012:role/marketingadminrole" } ] }

O usuário do IAM não precisa ter permissões adicionais para executar os comandos da CLI usando o perfil da função. Em vez disso, as permissões para executar o comando vêm das associadas à função. Você pode associar políticas à função para especificar quais ações podem ser executadas em quais recursos da AWS. Para obter mais informações sobre como associar permissões a uma função (que funciona de maneira idêntica a um usuário do IAM), consulte Alteração de permissões para um usuário do IAM no Guia do usuário do IAM.

Agora que você tem o perfil de função, permissões de função, relação de confiança de função e permissões de usuário configuradas corretamente, é possível usar a função na linha de comando invocando a opção --profile. Por exemplo, o comando a seguir chama o comando do Amazon S3 ls usando as permissões anexadas à função marketingadmin conforme definido no exemplo no início desse tópico.

$ aws s3 ls --profile marketingadmin

Para usar a função para várias chamadas, defina a variável de ambiente AWS_DEFAULT_PROFILE para a sessão atual na linha de comando. Enquanto essa variável de ambiente é definida, você não precisa especificar a opção --profile em cada comando.

Linux, macOS, or Unix

$ export AWS_DEFAULT_PROFILE=marketingadmin

Windows

C:\> setx AWS_DEFAULT_PROFILE=marketingadmin

Para obter mais informações sobre como configurar usuários e funções do IAM, consulte Usuários e grupos e Funções no Guia do usuário do IAM.

Uso de autenticação multifator

Para segurança adicional, você pode exigir que os usuários forneçam uma chave única gerada a partir de um dispositivo de autenticação multifator (MFA), um dispositivo U2F ou um aplicativo móvel quando eles tentarem fazer uma chamada usando o perfil de função.

Primeiro, modifique a relação de confiança na função do IAM para exigir MFA. Por exemplo, veja a linha Condition no exemplo a seguir.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:user/jonsmith" }, "Action": "sts:AssumeRole", "Condition": { "Bool": { "aws:multifactorAuthPresent": true } } } ] }

Depois, adicione uma linha à função que especifica o perfil do usuário ARN do dispositivo MFA.

[profile marketingadmin] role_arn = arn:aws:iam::123456789012:role/marketingadmin source_profile = default mfa_serial = arn:aws:iam::123456789012:mfa/saanvi

A configuração mfa_serial pode precisar de um ARN, conforme mostrado, ou o número de série de um token MFA de hardware.

Funções entre contas

Você pode permitir que os usuários do IAM assumam funções que pertencem a diferentes contas ao configurar a função como uma função entre contas. Durante a criação da função, defina o tipo de função como Another AWS account (Outra conta da AWS), conforme descrito em Criação de uma função para delegar permissões a um usuário do IAM. Como opção, selecione Require MFA (Exigir MFA). A opção Require MFA (Exigir MFA) configura a condição apropriada na relação de confiança, conforme descrito em Uso de autenticação multifator.

Se usar um ID externo para fornecer mais controle sobre quem pode assumir uma função em todas as contas, você também deverá adicionar o parâmetro external_id ao perfil da função. Normalmente, você usa isso somente quando a outra conta é controlada por alguém de fora da sua empresa ou organização.

[profile crossaccountrole] role_arn = arn:aws:iam::234567890123:role/SomeRole source_profile = default mfa_serial = arn:aws:iam::123456789012:mfa/saanvi external_id = 123456

Para obter mais informações, consulte Variáveis de configuração da CLI da AWS.

Limpeza de credenciais em cache

Quando você assume uma função, a AWS CLI armazena em cache as credenciais temporárias localmente até que elas expirem. Se as credenciais temporárias da sua função forem revogadas, você poderá excluir o cache para forçar a AWS CLI a recuperar novas credenciais.

Linux, macOS, or Unix

$ rm -r ~/.aws/cli/cache

Windows

C:\> del /s /q %UserProfile%\.aws\cli\cache