Pré-requisitos Visão geral do uso de IAM funções Configurar e usar uma função Usando MFA Funções entre contas e ID externo Especificar um nome de sessão de função para facilitar a auditoria Assumir a função com a identidade da web Limpar as credenciais em cache

Usando uma IAM função no AWS CLI

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

Tópicos

Pré-requisitos
Visão geral do uso de IAM funções
Configurar e usar uma função
Usar autenticação multifator
Funções entre contas e ID externo
Especificar um nome de sessão de função para facilitar a auditoria
Assumir a função com a identidade da web
Limpar as credenciais em cache

Pré-requisitos

Para executar os comandos iam, você precisa instalar e configurar a AWS CLI. Para obter mais informações, consulte Instalando, atualizando e desinstalando o AWS CLI.

Visão geral do uso de IAM funções

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

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 AWS_PROFILE ambiente), eles AWS CLI usarão as credenciais definidas em um perfil separado user1 para assumir a função com o Amazon Resource Name (ARN)arn:aws:iam::123456789012:role/marketingadminrole. É possível 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

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

Para executar um AWS CLI comando de dentro de uma instância do Amazon Elastic Compute Cloud (AmazonEC2) ou de um contêiner do Amazon Elastic Container Service (AmazonECS), você pode usar uma IAM função anexada ao perfil da 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 IAM função anexada ao perfil da EC2 instância da Amazon.
EcsContainer— Usa a IAM função anexada ao ECS contêiner da Amazon.

O exemplo a seguir mostra a mesma marketingadminrole função usada ao referenciar um perfil de EC2 instância da Amazon.


[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). Você também pode especificar nomes de sessão de função exclusivos que podem ser auditados com mais facilidade nos AWS CloudTrail registros.

Configurar e usar uma função

Quando você executa comandos usando um perfil que especifica uma IAM função, ele 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.

Você pode criar uma função IAM com as permissões que deseja que os usuários assumam seguindo o procedimento em Criação de uma função para delegar permissões a um IAM usuário no Guia do AWS Identity and Access Management usuário. Se a função e o usuário do 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 assumir .

O exemplo a seguir mostra uma política de confiança que pode ser associada a uma função. Essa política permite que o perfil seja assumido por qualquer usuário na conta 123456789012, se o administrador dessa conta conceder explicitamente 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, permitindo que ele assuma apenas o perfil marketingadminrole. Para obter mais informações sobre como conceder a um usuário acesso para assumir uma função, consulte Conceder permissão ao usuário para trocar de função no Guia do IAMusuário.


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

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

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


$ export AWS_PROFILE=marketingadmin

Windows


C:\> setx AWS_PROFILE marketingadmin

Para obter mais informações sobre como configurar usuários e funções, consulte IAMIdentidades (usuários, grupos de usuários e funções) e IAMfunções no Guia do IAMusuário.

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 aplicativo móvel quando tentarem fazer uma chamada usando o perfil da função.

Primeiro, você pode optar por modificar a relação de confiança na IAM função a ser exigidaMFA. Isso impede que qualquer pessoa use a função sem primeiro se autenticar usandoMFA. Por exemplo, veja a linha Condition no exemplo a seguir. Essa política permite que o usuário nomeado assuma a função anika à qual a política está vinculada, mas somente se ele se autenticar usandoMFA.


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

Em seguida, adicione uma linha ao perfil da função que especifica o ARN MFA dispositivo do usuário. As entradas do exemplo de arquivo config a seguir mostram dois perfis que usam as chaves de acesso para o usuário anika solicitar credenciais temporárias para o perfil cli-role. O usuário anika tem permissão para assumir a função, concedida 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 cli-user]
region = us-west-2
output = json

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

O primeiro perfilrole-without-mfa,, não exigeMFA. No entanto, como o exemplo anterior da política de confiança anexada à função exigeMFA, qualquer tentativa de executar um comando com esse perfil falha.


$ 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 MFA dispositivo a ser usado. Quando o usuário tenta executar um AWS CLI comando com esse perfil, ele AWS CLI solicita que o usuário insira a senha de uso único (OTP) fornecida pelo MFA dispositivo. Se a MFA autenticação for bem-sucedida, o comando executará a operação solicitada. O não OTP é exibido 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 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 Outra AWS conta, conforme descrito em Criação de uma função para delegar permissões a um IAM usuário. Opcionalmente, selecione Exigir MFA. Exigir MFA configura a condição apropriada na relação de confiança, conforme descrito emUsar 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 role_session_name valor é passado para a AssumeRole operação e se torna parte da ARN sessão da função. Também está incluído nos AWS CloudTrail registros 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 de função tenha o seguinteARN.


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

Além disso, todos os AWS CloudTrail registros 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

Você pode configurar um perfil para indicar que eles AWS CLI devem assumir uma função usando a federação de identidade da web e o Open ID Connect (OIDC). Quando você especifica isso em um perfil, ele faz AWS CLI automaticamente a AWS STS AssumeRoleWithWebIdentity chamada correspondente para você.

nota

Quando você especifica um perfil que usa uma IAM função, ele AWS CLI faz as chamadas apropriadas para recuperar credenciais temporárias. Essas credenciais são armazenadas em ~/.aws/cli/cache. AWS CLI Os comandos subsequentes que especificam o mesmo perfil usam as credenciais temporárias em cache até que elas expirem. Nesse ponto, ele atualiza AWS CLI 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 a função ARN a ser assumida.
web_identity_token_file: Especifica o caminho para um arquivo que contém um token de acesso 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 do papel a ser assumido.
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, ele armazena em AWS CLI cache as credenciais temporárias localmente até que elas expirem. Na próxima vez que você tentar usá-los, eles AWS CLI tentarão renová-los 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, você pode excluir o cache para forçar o AWS CLI a recuperar novas credenciais.

Linux ou macOS


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

Windows


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

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Credenciais de curto prazo

IAMusuários