Credenciais compartilhadas no AWS Tools for PowerShell

O Tools for Windows PowerShell oferece suporte ao uso do arquivo de credenciais compartilhadas da AWS, de forma semelhante à AWS CLI e a outros AWS SDKs. O Tools for Windows PowerShell agora oferece suporte à leitura e à gravação dos perfis de credenciais basic, session e assume role no arquivo de credenciais do .NET e no arquivo de credenciais compartilhadas da AWS. Essa funcionalidade é ativada por um novo namespace Amazon.Runtime.CredentialManagement.

Atenção

Para evitar riscos de segurança, não use usuários do IAM para autenticação ao desenvolver software com propósito específico ou trabalhar com dados reais. Em vez disso, use federação com um provedor de identidade, como AWS IAM Identity Center.

nota

As informações neste tópico são para circunstâncias em que você precisa obter e gerenciar manualmente as credenciais de curto ou longo prazo. Para obter informações adicionais sobre credenciais de curto e longo prazo, consulte Outras formas de autenticação no Guia de referência de AWS SDKs e ferramentas.

Para as práticas recomendadas de segurança, use o AWS IAM Identity Center, conforme descrito em Configurar autenticação nas ferramentas.

Os novos tipos de perfil e o acesso ao arquivo de credenciais compartilhadas da AWS são compatíveis com os seguintes parâmetros que foram adicionados aos cmdlets relacionados a credenciais: Initialize-AWSDefaultConfiguration, New-AWSCredential e Set-AWSCredential. Nos cmdlets de serviço, é possível fazer referência ao seus perfis adicionando o parâmetro comum, -ProfileName.

Uso de uma função de IAM com o AWS Tools for PowerShell

O arquivo de credenciais compartilhadas da AWS permite tipos adicionais de acesso. Por exemplo, é possível acessar seus recursos da AWS usando uma função do IAM em vez das credenciais de longo prazo de um usuário do IAM. Para fazer isso, é necessário ter um perfil padrão que tenha permissões para assumir a função. Quando você instrui o AWS Tools for PowerShell para usar um perfil que especificou uma função, o AWS Tools for PowerShell procura o perfil identificado pelo parâmetro SourceProfile. Essas credenciais são usadas para solicitar credenciais temporárias para a função especificada pelo parâmetro RoleArn. Opcionalmente, é possível exigir o uso de um dispositivo de autenticação multifator (MFA) ou de um código de ExternalId quando a função é assumida por terceiros.

Nome do parâmetro	Descrição
ExternalId	O ID externo definido pelo usuário a ser usado ao assumir uma função, se for necessário para a função. Normalmente, isso só é necessário quando você delega o acesso à sua conta a terceiros. O terceiro deverá incluir o ExternalID como parâmetro ao assumir a função atribuída. Para obter mais informações, consulte Como usar um ID externo ao conceder acesso aos recursos da AWS para terceiros no Manual do usuário do IAM.
MfaSerial	O número de série MFA a ser usado ao assumir uma função, se for necessário para a função. Para obter mais informações, consulte Uso da autenticação multifator (MFA) na AWS no Manual do ujsuário do IAM.
RoleArn	O ARN da função a ser assumida para credenciais assume role. Para obter mais informações sobre como criar e usar funções do IAM, consulte Funções do IAM no Manual do usuário do IAM.
SourceProfile	O nome do perfil de origem a ser usado pelas credenciais assume role. As credenciais encontradas neste perfil são usadas para assumir a função especificada pelo parâmetro RoleArn.

Configuração de perfis para assumir uma função

Veja a seguir um exemplo que mostra como configurar um perfil de origem que permite assumir diretamente uma função do IAM.

O primeiro comando cria um perfil de origem que é referenciado pelo perfil de função. O segundo comando cria o perfil de função a ser assumido pela função. O terceiro comando mostra as credenciais para o perfil de função.

PS > Set-AWSCredential -StoreAs my_source_profile -AccessKey access_key_id -SecretKey secret_key
PS > Set-AWSCredential -StoreAs my_role_profile -SourceProfile my_source_profile -RoleArn arn:aws:iam::123456789012:role/role-i-want-to-assume
PS > Get-AWSCredential -ProfileName my_role_profile

SourceCredentials                  RoleArn                                              RoleSessionName                           Options
-----------------                  -------                                              ---------------                           -------
Amazon.Runtime.BasicAWSCredentials arn:aws:iam::123456789012:role/role-i-want-to-assume aws-dotnet-sdk-session-636238288466144357 Amazon.Runtime.AssumeRoleAWSCredentialsOptions

Para usar esse perfil de função com os cmdlets de serviço do Tools for Windows PowerShell, adicione o parâmetro comum -ProfileName ao comando para fazer referência ao perfil de função. O exemplo a seguir usa o perfil de função definido no exemplo anterior para acessar o cmdlet Get-S3Bucket. O AWS Tools for PowerShell procura as credenciais em my_source_profile, usa essas credenciais para chamar AssumeRole em nome do usuário e usa essas credenciais de função temporárias para chamar Get-S3Bucket.

PS > Get-S3Bucket -ProfileName my_role_profile

CreationDate           BucketName
------------           ----------
2/27/2017 8:57:53 AM   4ba3578c-f88f-4d8b-b95f-92a8858dac58-bucket1
2/27/2017 10:44:37 AM  2091a504-66a9-4d69-8981-aaef812a02c3-bucket2

Uso dos tipos de perfil de credencial

Para definir um tipo de perfil de credencial, entenda quais parâmetros fornecem as informações necessárias ao tipo de perfil.

Tipo de credenciais	Parâmetros que você deve usar
Basic Estas são as credenciais de longo prazo para um usuário do IAM	-AccessKey -SecretKey
Sessão: Essas são as credenciais de curto prazo para uma função do IAM que você recupera manualmente, por exemplo, chamando diretamente o cmdlet Use-STRole.	-AccessKey -SecretKey -SessionToken
Função: Estas são credenciais de curto prazo para uma função do IAM que o AWS Tools for PowerShell recupera para você.	-SourceProfile -RoleArn opcional: -ExternalId opcional: -MfaSerial

O parâmetro comum ProfilesLocation

Você pode usar -ProfileLocation para gravar no arquivo de credenciais compartilhadas, bem como instruir um cmdlet para ler o arquivo de credenciais. A inclusão do parâmetro -ProfileLocation determina se o Tools for Windows PowerShell usa o arquivo de credenciais compartilhadas ou o arquivo de credenciais do .NET. A tabela a seguir descreve como o parâmetro funciona no Tools for Windows PowerShell.

Valor do local do perfil	Comportamento da resolução do perfil
nulo (não definido) ou vazio	Primeiro, pesquise o arquivo de credenciais do .NET para um perfil com o nome especificado. Se o perfil não for encontrado, pesquise o arquivo de credenciais compartilhadas da AWS em (user's home directory)\.aws\credentials.
O caminho para um arquivo no formato de arquivo de credenciais compartilhadas da AWS	Pesquise apenas o arquivo especificado para um perfil com o nome fornecido.

Salvar credenciais em um arquivo de credenciais

Para gravar e salvar as credenciais em um dos dois arquivos de credenciais, execute o cmdlet Set-AWSCredential. O exemplo a seguir mostra como fazer isso. O primeiro comando usa Set-AWSCredential com -ProfileLocation para adicionar chaves de acesso e secretas a um perfil especificado pelo parâmetro -ProfileName. Na segunda linha, execute o cmdlet Get-Content para exibir o conteúdo do arquivo de credenciais.

PS > Set-AWSCredential -ProfileLocation C:\Users\auser\.aws\credentials -ProfileName basic_profile -AccessKey access_key2 -SecretKey secret_key2
PS > Get-Content C:\Users\auser\.aws\credentials

aws_access_key_id=access_key2
aws_secret_access_key=secret_key2

Exibir seus perfis de credenciais

Execute o cmdlet Get-AWSCredential e adicione o parâmetro -ListProfileDetail para retornar tipos de arquivos de credenciais e locais, bem como uma lista de nomes de perfil.

PS > Get-AWSCredential -ListProfileDetail

ProfileName                     StoreTypeName         ProfileLocation
-----------                     -------------         ---------------
source_profile                  NetSDKCredentialsFile
assume_role_profile             NetSDKCredentialsFile
basic_profile                   SharedCredentialsFile C:\Users\auser\.aws\credentials

Remoção de perfis de credencial

Para remover perfis de credencial, execute o novo cmdlet Remove-AWSCredentialProfile. Clear-AWSCredential está obsoleto, mas ainda está disponível para compatibilidade com versões anteriores.

Observações importantes

Somente Initialize-AWSDefaultConfiguration, New-AWSCredential e Set-AWSCredential oferecem suporte aos parâmetros para perfis de função. Não é possível especificar os parâmetros de função diretamente em um comando, como Get-S3Bucket -SourceProfile source_profile_name -RoleArn arn:aws:iam::999999999999:role/role_name. Isso não funciona porque os cmdlets de serviço não oferecem suporte direto aos parâmetros SourceProfile ou RoleArn. Em vez disso, armazene esses parâmetros em um perfil chame o comando com o parâmetro -ProfileName.