Usar credenciais da AWS

Cada comando do Ferramentas da AWS para PowerShell deve incluir um conjunto de credenciais da AWS, que são usadas de forma criptográfica para assinar a solicitação de web service correspondente. Você pode especificar credenciais por comando, por sessão ou para todas as sessões.

Como melhor prática, para evitar expor suas credenciais, não coloque credenciais literais em um comando. Em vez disso, crie um perfil para cada conjunto de credenciais que você deseja usar e armazene o perfil em um dos dois armazenamentos de credenciais. Especifique o nome correto do perfil no comando e o Ferramentas da AWS para PowerShell recuperará as credenciais associadas. Para ver uma discussão geral sobre como gerenciar com segurança as credenciais da AWS, consulte Práticas recomendadas para gerenciar as chaves de acesso da AWS na Referência geral da Amazon Web Services.

Locais de armazenamento de credenciais

O Ferramentas da AWS para PowerShell pode usar qualquer um dos dois armazenamentos de credenciais.

Como gerenciar perfis

Os perfis permitem que você faça referência a diferentes conjuntos de credenciais com Ferramentas da AWS para PowerShell. Você pode usar os cmdlets do Ferramentas da AWS para PowerShell para gerenciar seus perfis no armazenamento do AWS SDK. Você também pode gerenciar perfis no armazenamento do AWS SDK usando o Toolkit for Visual Studio ou programaticamente usando o AWS SDK para .NET. Para obter instruções sobre como gerenciar perfis no arquivo de credenciais, consulte Práticas recomendadas para gerenciar chaves de acesso da AWS.

Adicionar um novo perfil

Para adicionar um novo perfil para o armazenamento do AWS SDK, execute o comando Set-AWSCredential. Ele armazena sua chave de acesso e a chave secreta no arquivo de credenciais padrão sob o nome de perfil especificado.

PS > Set-AWSCredential `
                 -AccessKey AKIA0123456787EXAMPLE `
                 -SecretKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY `
                 -StoreAs MyNewProfile

Atualizar um perfil

O armazenamento da AWS SDK deve ser mantido manualmente. Se você alterar posteriormente as credenciais no serviço, por exemplo, usando o Console do IAM, ocorrerá falha na execução de um comando com as credenciais armazenadas exibindo a seguinte mensagem de erro:

The Access Key Id you provided does not exist in our records.

Você pode atualizar um perfil repetindo o comando Set-AWSCredential para o perfil e passando para ele a novas chaves de acesso e chaves secretas.

Listar perfis

Você pode verificar a lista atual de nomes com o comando a seguir. Nesse exemplo, uma usuária chamada Shirley tem acesso a três perfis que são armazenados no arquivo de credenciais compartilhadas (~/.aws/credentials).

PS > Get-AWSCredential -ListProfileDetail

ProfileName  StoreTypeName         ProfileLocation
-----------  -------------         ---------------
default      SharedCredentialsFile /Users/shirley/.aws/credentials
production   SharedCredentialsFile /Users/shirley/.aws/credentials
test         SharedCredentialsFile /Users/shirley/.aws/credentials

Remover um perfil

Para remover um perfil que você não precisa mais, use o comando a seguir.

PS > Remove-AWSCredentialProfile -ProfileName an-old-profile-I-do-not-need

O parâmetro -ProfileName especifica o perfil que você deseja excluir.

O comando obsoleto Clear-AWSCredential ainda está disponível para assegurar a compatibilidade com versões anteriores, mas Remove-AWSCredentialProfile é o preferencial.

Especificação de credenciais

Há várias maneiras de especificar credenciais. A melhor maneira é identificar um perfil em vez de incorporar credenciais literais na linha de comando. O Ferramentas da AWS para PowerShell localiza o perfil usando uma ordem de pesquisa descrita na Ordem de pesquisa de credenciais.

No Windows, as credenciais da AWS armazenadas no AWS SDK são criptografadas com a identidade de usuário do Windows que fez login. Elas não podem ser descriptografadas usando outra conta, ou usadas em um dispositivo diferente daquele no qual foram criadas originalmente. Para executar tarefas que exigem as credenciais de outro usuário, como uma conta de usuário na qual uma tarefa programada será executada, configure um perfil de credenciais criptografadas, conforme descrito na seção anterior, que você pode usar ao fazer login no computador como esse usuário. Faça login como o usuário que executa tarefas para concluir as etapas de configuração de credenciais e crie um perfil que funcione para esse usuário. Em seguida, faça logout e depois faça login novamente com as suas credenciais para configurar a tarefa agendada.

Perfil padrão (recomendado)

Todos os AWS SDKs e as ferramentas de gerenciamento poderão encontrar suas credenciais automaticamente no computador local se as credenciais estiverem armazenadas em um perfil chamado default. Por exemplo, caso você tenha um perfil nomeado como default no computador local, não é necessário executar o cmdlet Initialize-AWSDefaultConfiguration nem o cmdlet Set-AWSCredential. As ferramentas usam automaticamente os dados de chave secreta e chave de acesso. armazenados nesse perfil. Para usar a região da AWS em vez da região padrão (os resultados do Get-DefaultAWSRegion), você pode executar Set-DefaultAWSRegion e especificar uma região.

Se o perfil não foi nomeado default, mas você deseja usá-lo como perfil padrão para a sessão atual, execute Set-AWSCredential para defini-lo como perfil padrão.

Embora a execução Initialize-AWSDefaultConfiguration permita que você especifique um perfil padrão para cada sessão do PowerShell, o cmdlet carrega as credenciais do seu perfil de nome personalizado, mas substitui o perfil default pelo perfil nomeado.

Recomendamos que não executar Initialize-AWSDefaultConfiguration a menos que você esteja executando uma sessão do PowerShell em uma instância do Amazon EC2 que não foi iniciada com um perfil de instância e deseje configurar o perfil de credencial manualmente. Observe que, nesse caso, o perfil de credencial não contém credenciais. O perfil de credencial resultante da execução de Initialize-AWSDefaultConfiguration em uma instância do EC2 não armazena credenciais diretamente, mas aponta para os metadados da instância (que fornecem credenciais temporárias que são alternadas automaticamente). No entanto, ele armazena a região da instância. Outro cenário que pode exigir a execução de Initialize-AWSDefaultConfiguration ocorre se você deseja executar uma chamada em uma região diferente da região em que a instância está em execução. Executar esse comando substitui permanentemente a região armazenada nos metadados da instância.

PS > Initialize-AWSDefaultConfiguration -ProfileName MyProfileName -Region us-west-2

Se a instância do EC2 foi iniciada com um perfil de instância, o PowerShell obtém as informações de credenciais e região da AWS no perfil de instância. Não é necessário executar Initialize-AWSDefaultConfiguration. Não é necessário executar o cmdlet Initialize-AWSDefaultConfiguration em uma instância do EC2 iniciada com um perfil de instância, pois ele usa os mesmos dados de perfil de instância que o PowerShell já usa por padrão.

Perfil de sessão

Use Set-AWSCredential para especificar um perfil padrão para uma sessão específica. Esse perfil substitui todos os perfis padrão durante a sessão. Isso é recomendado se você deseja usar um perfil com nome personalizado em sua sessão em vez do perfil default atual.

PS > Set-AWSCredential -ProfileName MyProfileName

Perfil de comando

Em comandos individuais, você pode adicionar o parâmetro -ProfileName para especificar um perfil que se aplique apenas a esse comando. Esse perfil substitui todos os perfis padrão ou de sessão, conforme exibido no exemplo a seguir.

PS > Get-EC2Instance -ProfileName MyProfileName

PS > Initialize-AWSDefaultConfiguration -ProfileName MyProfileName -Region us-west-2

Por padrão, considera-se que o arquivo de credenciais compartilhadas da AWS esteja na pasta inicial do usuário (C:\Users\username\.aws no Windows ou ~/.aws no Linux). Para especificar um arquivo de credenciais em um local diferente, inclua o parâmetro -ProfileLocation e especifique o caminho do arquivo de credenciais. O exemplo a seguir especifica um arquivo de credenciais não padrão para um comando específico.

PS > Get-EC2Instance -ProfileName MyProfileName -ProfileLocation C:\aws_service_credentials\credentials

Ordem de pesquisa de credenciais

Quando você executa um comando, o Ferramentas da AWS para PowerShell procura credenciais na ordem a seguir. Ele para ao encontrar credenciais utilizáveis.

Se essa pesquisa não conseguir localizar as credenciais especificadas, o comando lançará uma exceção.

Tratamento de credenciais no AWS Tools for PowerShell Core

Os cmdlets no AWS Tools for PowerShell Core aceitam o acesso da AWS e chaves secretas ou os nomes de perfis de credenciais ao serem executados, de forma semelhante ao AWS Tools for Windows PowerShell. Quando forem executados no Windows, os dois módulos têm acesso ao arquivo de armazenamento de credenciais do AWS SDK para .NET (armazenado no arquivo AppData\Local\AWSToolkit\RegisteredAccounts.json por usuário).

Esse arquivo armazena suas chaves em formato criptografado e não pode ser usado em outro computador. Ele é o primeiro arquivo no qual o Ferramentas da AWS para PowerShell procura por um perfil de credencial, e também é o arquivo em que o Ferramentas da AWS para PowerShell armazena perfis de credenciais. Para obter mais informações sobre o arquivo de armazenamento de credenciais do AWS SDK para .NET, consulte Configuração das credenciais da AWS. O módulo Tools for Windows PowerShell no momento não oferece suporte à gravação de credenciais em outros arquivos ou locais.

Os dois módulos podem ler perfis do arquivo de credenciais compartilhadas da AWS que é usado por outros AWS SDKs e pela AWS CLI. No Windows, o local padrão para esse arquivo é C:\Users\<userid>\.aws\credentials. Em plataformas diferentes do Windows, esse arquivo é armazenado em ~/.aws/credentials. O parâmetro -ProfileLocation pode ser usado para apontar para um nome de arquivo padrão ou local do arquivo.

O armazenamento de credenciais de SDKs mantém suas credenciais no formato criptografado usando as APIs criptografadas do Windows. Essas APIs não estão disponíveis em outras plataformas, de modo que o módulo AWS Tools for PowerShell Core usa o arquivo de credenciais compartilhadas da AWS de forma exclusiva e oferece suporte à gravação de novos perfis de credencial no arquivo de credenciais compartilhadas.

Os scripts de exemplo a seguir que usam o cmdlet Set-AWSCredential mostram as opções para lidar com perfis de credenciais no Windows com os módulos AWSPowerShell ou AWSPowerShell.NetCore.

# Writes a new (or updates existing) profile with name "myProfileName"
# in the encrypted SDK store file

Set-AWSCredential -AccessKey akey -SecretKey skey -StoreAs myProfileName

# Checks the encrypted SDK credential store for the profile and then
# falls back to the shared credentials file in the default location

Set-AWSCredential -ProfileName myProfileName

# Bypasses the encrypted SDK credential store and attempts to load the
# profile from the ini-format credentials file "mycredentials" in the
# folder C:\MyCustomPath

Set-AWSCredential -ProfileName myProfileName -ProfileLocation C:\MyCustomPath\mycredentials

Os exemplos a seguir mostram o comportamento do módulo AWSPowerShell.NetCore nos sistemas operacionais Linux ou macOS.

# Writes a new (or updates existing) profile with name "myProfileName"
# in the default shared credentials file ~/.aws/credentials

Set-AWSCredential -AccessKey akey -SecretKey skey -StoreAs myProfileName

# Writes a new (or updates existing) profile with name "myProfileName"
# into an ini-format credentials file "~/mycustompath/mycredentials"

Set-AWSCredential -AccessKey akey -SecretKey skey -StoreAs myProfileName -ProfileLocation ~/mycustompath/mycredentials

# Reads the default shared credential file looking for the profile "myProfileName"

Set-AWSCredential -ProfileName myProfileName

# Reads the specified credential file looking for the profile "myProfileName"

Set-AWSCredential -ProfileName myProfileName -ProfileLocation ~/mycustompath/mycredentials