Usar uma função do IAM na AWS CLI - AWS Command Line Interface

O Python 2.7, 3.4 e 3.5 está sendo defasado para o AWS CLI versão 1. Para obter mais informações, consulte a AWS CLI versão 1 seção de Sobre as AWS CLI versões.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Usar 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_PROFILE), a CLI usará as credenciais definidas em um perfil separado user1 para assumir a função com o nome de recurso da Amazon (ARN) arn:aws:iam::123456789012:role/marketingadminrole. É possível executar qualquer operação permitida pelas permissões atribuídas a essa função.

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

Então, é possível especificar um source_profile que aponte para um perfil nomeado separado que contenha credenciais de usuário do IAM com permissão para usar 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.

Para executar um comando da CLI de dentro de uma instância do Amazon Elastic Compute Cloud (Amazon EC2) ou um contêiner do Amazon Elastic Container Service (Amazon ECS), você pode usar uma função do IAM associada ao perfil de instância ou ao contêiner. Se você não especificar nenhum perfil ou não definir variáveis de ambiente, essa função será usada diretamente. Isso permite que você evite armazenar chaves de acesso de longa duração em suas instâncias. Também é possível usar essas funções de instância ou contêiner apenas para obter credenciais para outra função. 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 – recupera as credenciais de origem de variáveis de ambiente.

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

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

O exemplo a seguir mostra a mesma função marketingadminrole usada 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

Ao invocar uma função, você tem opções adicionais que podem ser exigidas, como o uso de autenticação multifator e um ID externo (usado por empresas de terceiros para acessar os recursos de seus clientes). Também é possível especificar nomes de sessão de função exclusivos que possam ser auditados com mais facilidade nos logs do AWS CloudTrail.

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 use a função. Geralmente, o processo de recuperar e depois usar credenciais temporárias para uma função é chamado de assumir a função.

É possível criar uma função no IAM com as permissões que você deseja que os usuários assumam seguindo o procedimento em 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 o perfil de função, as permissões de função, a relação de confiança de função e as permissões de usuário estão configurados corretamente, é possível usar a função na linha de comando invocando a opção --profile. Por exemplo, o indicado a seguir chama o comando ls do Amazon S3 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_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 ou macOS X

$ export AWS_PROFILE=marketingadmin

Windows

C:\> setx AWS_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.

Usar 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, você pode optar por modificar a relação de confiança na função do IAM para exigir MFA. Isso impede que alguém usando a função sem antes autenticar usando MFA. Por exemplo, veja a linha Condition no exemplo a seguir. Essa política permite que o usuário do IAM chamado anika assuma a função à qual a política está anexada, mas somente se ela autenticar usando MFA.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:user/anika" }, "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. As entradas do arquivo config de exemplo a seguir mostram dois perfis de função que usam as chaves de acesso para o usuário do IAM para solicitar credenciais temporárias para a função anika.cli-role O usuário anika tem permissões para assumir a função, concedidas pela política de confiança da função.

[profile role-without-mfa] region = us-west-2 role_arn= arn:aws:iam::128716708097:role/cli-role source_profile=cli-user [profile role-with-mfa] region = us-west-2 role_arn= arn:aws:iam::128716708097:role/cli-role source_profile = cli-user mfa_serial = arn:aws:iam::128716708097:mfa/cli-user [profile anika] region = us-west-2 output = json

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

O primeiro perfil, role-without-mfa, não exige MFA. No entanto, como a política de confiança do exemplo anterior anexada à função requer MFA, qualquer tentativa de executar um comando com esse perfil vai falhar.

$ aws iam list-users --profile role-without-mfa An error occurred (AccessDenied) when calling the AssumeRole operation: Access denied

A segunda entrada do perfil, role-with-mfa, identifica um dispositivo MFA para usar. Quando o usuário tenta executar um comando da CLI com esse perfil, a CLI solicita que o usuário insira a senha de uso único (OTP) que o dispositivo MFA fornece. Se a autenticação de MFA for bem-sucedida, o comando executará a operação solicitada. A OTP não é exibida na tela.

$ aws iam list-users --profile role-with-mfa Enter MFA code for arn:aws:iam::123456789012:mfa/cli-user: { "Users": [ { ...

Funções entre contas e ID externo

É possível permitir que os usuários do IAM usem funções que pertençam 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 Criar uma função para delegar permissões a um usuário do IAM. Como opção, selecione Require MFA (Exigir MFA). Require MFA (Exigir MFA) configura a condição apropriada na relação de confiança, conforme descrito em Usar autenticação multifator.

Se usar um ID externo para fornecer mais controle sobre quem pode usar uma função em todas as contas, você também deverá adicionar o parâmetro external_id ao perfil da função. Normalmente, isso é usado 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

Especificar um nome de sessão de função para facilitar a auditoria

Quando muitos indivíduos compartilham uma função, a auditoria torna-se um desafio. É recomendável associar cada operação invocada ao indivíduo que invocou a ação. No entanto, quando o indivíduo usa uma função, a assunção da função por ele é uma ação separada da invocação de uma operação, e é necessário correlacionar manualmente as duas.

É possível simplificar isso especificando nomes de sessão de função exclusivos quando os usuários assumem uma função. Para fazer isso, adicione um parâmetro role_session_name a cada perfil nomeado no arquivo config que especifica uma função. O valor role_session_name é transmitido para a operação AssumeRole e se torna parte do ARN da sessão da função. Ele também é incluído nos logs do AWS CloudTrail de todas as operações registradas.

Por exemplo, é possível criar um perfil baseado em função da maneira a seguir.

[profile namedsessionrole] role_arn = arn:aws:iam::234567890123:role/SomeRole source_profile = default role_session_name = Session_Maria_Garcia

Isso faz com que a sessão da função tenha o ARN a seguir.

arn:aws:iam::234567890123:assumed-role/SomeRole/Session_Maria_Garcia

Além disso, todos os logs do AWS CloudTrail incluem o nome da sessão da função nas informações capturadas para cada operação.

Assumir a função com a identidade da web

É possível configurar um perfil para indicar que a AWS CLI deve assumir uma função usando a federação de identidades da web e o Open ID Connect (OIDC). Quando isso é especificado em um perfil, a AWS CLI faz automaticamente a chamada AWS STS AssumeRoleWithWebIdentity correspondente para você.

nota

Quando é especificado um perfil que usa uma função do IAM, a AWS CLI faz as chamadas apropriadas para recuperar credenciais temporárias. Essas credenciais são armazenadas em ~/.aws/cli/cache. Os comandos subsequentes da AWS CLI que especificam o mesmo perfil usam as credenciais temporárias armazenadas em cache até que elas expirem. Nesse ponto, a AWS CLI atualiza automaticamente as credenciais.

Para recuperar e usar credenciais temporárias usando a federação de identidades da web, é possível especificar os valores de configuração a seguir em um perfil compartilhado.

role_arn

Especifica o ARN da função a assumir.

web_identity_token_file

Especifica o caminho para um arquivo que contém um token de acesso do OAuth 2.0 ou token de ID do OpenID Connect fornecido pelo provedor de identidade. A AWS CLI carrega esse arquivo e transmite seu conteúdo como o argumento WebIdentityToken da operação AssumeRoleWithWebIdentity.

role_session_name

Especifica um nome opcional aplicado a essa sessão assume-role.

Veja a seguir um exemplo da configuração mínima necessária para uma função de admissão com o perfil de identidade da web:

# In ~/.aws/config [profile web-identity] role_arn=arn:aws:iam:123456789012:role/RoleNameToAssume web_identity_token_file=/path/to/a/token

Também é possível fornecer essa configuração usando variáveis de ambiente.

AWS_ROLE_ARN

O ARN da função a ser assumida

AWS_WEB_IDENTITY_TOKEN_FILE

O caminho para o arquivo de token de identidade da web.

AWS_ROLE_SESSION_NAME

O nome aplicado a essa sessão assume-role.

nota

No momento, essas variáveis de ambiente se aplicam somente à função de admissão com o provedor de identidade da web. Elas não se aplicam à configuração geral do provedor de função.

Limpar as credenciais em cache

Quando você usa uma função, a AWS CLI armazena em cache as credenciais temporárias localmente até que elas expirem. Na próxima vez que você tentar usá-las, a AWS CLI tentará renová-las em seu nome.

Se as credenciais temporárias da função forem revogadas, elas não serão renovadas automaticamente, e as tentativas de usá-las falharão. No entanto, é possível excluir o cache para forçar a AWS CLI a recuperar novas credenciais.

Linux ou macOS X

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

Windows

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