A versão 5 (V5) do Ferramentas da AWS para PowerShell foi lançada\$1
Para obter informações sobre mudanças significativas e migrar seus aplicativos, consulte o [tópico de migração](https://docs.aws.amazon.com/powershell/v5/userguide/migrating-v5.html).
[https://docs.aws.amazon.com/powershell/v5/userguide/migrating-v5.html](https://docs.aws.amazon.com/powershell/v5/userguide/migrating-v5.html)
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á.
# Configure a identidade federada com o Ferramentas da AWS para PowerShell
Para permitir que os usuários da sua organização acessem AWS os recursos, você deve configurar um método de autenticação padrão e repetível para fins de segurança, auditabilidade, conformidade e capacidade de oferecer suporte à separação de funções e contas. Embora seja comum fornecer aos usuários a capacidade de acessar AWS APIs, sem o acesso federado à API, você também precisaria criar usuários AWS Identity and Access Management (IAM), o que anula o propósito de usar a federação. Este tópico descreve o suporte ao SAML (Security Assertion Markup Language) no Ferramentas da AWS para PowerShell que facilita sua solução de acesso federado.
O suporte SAML no Ferramentas da AWS para PowerShell permite que você forneça aos usuários acesso federado aos AWS serviços. O SAML é um formato de padrão aberto baseado em XML para transmitir dados de autenticação e autorização do usuário entre serviços; em particular, entre um provedor de identidade (como os Serviços de [Federação do Active Directory) e um provedor de serviços](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/ad-fs-overview) (como). AWS Para obter mais informações sobre SAML e como ele funciona, consulte [SAML](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language) na Wikipédia ou [Especificações técnicas do SAML](https://www.oasis-open.org/standard/saml/) no site da OASIS (Organization for the Advancement of Structured Information Standards). O suporte ao SAML no Ferramentas da AWS para PowerShell é compatível com o SAML 2.0.
## Pré-requisitos
Você deve ter o seguinte antes de tentar usar o suporte a SAML pela primeira vez.
+ Uma solução de identidade federada corretamente integrada com sua conta da AWS para acesso ao console usando apenas as credenciais da sua organização. Para obter mais informações sobre como fazer isso especificamente para os Serviços de Federação do Active Directory, consulte [Sobre a Federação do SAML 2.0](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml.html) no *Guia do Usuário do IAM* e a postagem do blog, [Habilitando a federação para AWS usar o Windows Active Directory, o AD FS e o SAML](https://aws.amazon.com/blogs/security/enabling-federation-to-aws-using-windows-active-directory-adfs-and-saml-2-0/) 2.0. Embora a publicação do blog aborde o AD FS 2.0, as etapas serão semelhantes se você estiver executando o AD FS 3.0.
+ Versão 3.1.31.0 ou mais recente da Ferramentas da AWS para PowerShell instalada em sua estação de trabalho local.
## Como um usuário federado por identidade obtém acesso federado ao serviço AWS APIs
O processo a seguir descreve, em alto nível, como um usuário do Active Directory (AD) é federado pelo AD FS para obter acesso aos AWS recursos.
![\[Diagram showing federated user access flow to AWS resources via AD FS and Security Token Service.\]](http://docs.aws.amazon.com/pt_br/powershell/v5/userguide/images/powershell_ADFSauth_using_vsd.png)
1. O cliente no computador do usuário federado autentica em relação ao AD FS.
1. Se a autenticação for bem-sucedida, o AD FS enviará ao usuário uma declaração do SAML.
1. O cliente do usuário envia a declaração SAML para o AWS Security Token Service (STS) como parte de uma solicitação de federação SAML.
1. O STS retorna uma resposta SAML que contém credenciais AWS temporárias para uma função que o usuário pode assumir.
1. O usuário acessa o AWS serviço APIs incluindo essas credenciais temporárias na solicitação feita por. Ferramentas da AWS para PowerShell
## Como funciona o SAML Support no Ferramentas da AWS para PowerShell
Esta seção descreve como os Ferramentas da AWS para PowerShell cmdlets permitem a configuração da federação de identidades baseada em SAML para usuários.
![\[Diagram showing SAML-based federation flow between organization, AD FS, AWS, and service APIs.\]](http://docs.aws.amazon.com/pt_br/powershell/v5/userguide/images/Powershell_SamlAuth_using_vsd.png)
1. Ferramentas da AWS para PowerShell autentica no AD FS usando as credenciais atuais do usuário do Windows, ou interativamente, quando o usuário tenta executar um cmdlet que exige credenciais para ligar. AWS
1. O AD FS autentica o usuário.
1. O AD FS gera uma resposta de autenticação SAML 2.0 que inclui uma declaração; o objetivo da afirmação é identificar e fornecer informações sobre o usuário. Ferramentas da AWS para PowerShell extrai a lista das funções autorizadas do usuário da declaração SAML.
1. Ferramentas da AWS para PowerShell encaminha a solicitação SAML, incluindo os Amazon Resource Names (ARN) da função solicitada, para o STS fazendo a chamada de API. `AssumeRoleWithSAMLRequest`
1. Se a solicitação do SAML for válida, o STS retornará uma resposta que contém AWS , `AccessKeyId` e `SecretAccessKey` da `SessionToken`. Essas credenciais duram 3.600 segundos (1 hora).
1. O usuário agora tem credenciais válidas para trabalhar com qualquer AWS serviço APIs que a função do usuário esteja autorizada a acessar. Ferramentas da AWS para PowerShell aplica automaticamente essas credenciais a todas as chamadas de AWS API subsequentes e as renova automaticamente quando elas expiram.
**nota**
Quando as credenciais expiram e novas credenciais são necessárias, o Ferramentas da AWS para PowerShell reautentica automaticamente com o AD FS e obtém novas credenciais para a próxima hora. Para usuários de contas associadas a um domínio, esse processo ocorre silenciosamente. Para contas que não são associadas a um domínio, Ferramentas da AWS para PowerShell solicita que os usuários insiram suas credenciais antes de poderem se autenticar novamente.
## Como usar os cmdlets de configuração PowerShell SAML
Ferramentas da AWS para PowerShell inclui dois novos cmdlets que oferecem suporte ao SAML.
+ O `Set-AWSSamlEndpoint` configura o endpoint do AD FS, atribui um nome amigável ao endpoint e, opcionalmente, descreve o tipo de autenticação do endpoint.
+ O `Set-AWSSamlRoleProfile` cria ou edita um perfil de conta de usuário que você deseja associar a um endpoint do AD FS, identificado ao especificar o nome amigável fornecido ao cmdlet `Set-AWSSamlEndpoint`. Cada perfil de função é mapeado para uma única função que um usuário está autorizado a executar.
Assim como nos perfis de AWS credenciais, você atribui um nome amigável ao perfil da função. Você pode usar o mesmo nome amigável com o `Set-AWSCredential` cmdlet ou como o valor do `-ProfileName` parâmetro para qualquer cmdlet que invoque o serviço. AWS APIs
Abra uma nova Ferramentas da AWS para PowerShell sessão. Se você estiver executando a PowerShell versão 3.0 ou mais recente, o Ferramentas da AWS para PowerShell módulo será importado automaticamente quando você executar qualquer um de seus cmdlets. Se você estiver executando a PowerShell versão 2.0, deverá importar o módulo manualmente executando o cmdlet ``Import-Module``, conforme mostrado no exemplo a seguir.
```
PS > Import-Module "C:\Program Files (x86)\AWS Tools\PowerShell\AWSPowerShell\AWSPowerShell.psd1"
```
### Como executar os cmdlets `Set-AWSSamlEndpoint` e `Set-AWSSamlRoleProfile`
1. Primeiro, defina as configurações de endpoint para o sistema do AD FS. A maneira mais simples de fazer isso é armazenar o endpoint em uma variável, como mostrado nesta etapa. Certifique-se de substituir a conta de espaço reservado IDs e o nome do host do AD FS pela sua própria conta IDs e nome do host do AD FS. Especifique o nome de host do AD FS no parâmetro `Endpoint`.
```
PS > $endpoint = "https://adfs.example.com/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=urn:amazon:webservices"
```
1. Para criar as configurações de endpoint, execute o cmdlet `Set-AWSSamlEndpoint`, especificando o valor correto para o parâmetro `AuthenticationType`. Os valores válidos incluem `Basic`, `Digest`, `Kerberos`, `Negotiate` e `NTLM`. Se você não especificar esse parâmetro, o valor padrão será `Kerberos`.
```
PS > $epName = Set-AWSSamlEndpoint -Endpoint $endpoint -StoreAs ADFS-Demo -AuthenticationType NTLM
```
O cmdlet retorna o nome amigável atribuídos usando o parâmetro `-StoreAs`, para que você possa usá-lo ao executar `Set-AWSSamlRoleProfile` na próxima linha.
1. Agora, execute o cmdlet `Set-AWSSamlRoleProfile` para fazer a autenticação com o provedor de identidade do AD FS e obter o conjunto de funções (na declaração do SAML) que o usuário está autorizado a executar.
O cmdlet `Set-AWSSamlRoleProfile` usa o conjunto retornado de funções para solicitar que o usuário selecione uma função a ser associada ao perfil especificado ou confirme que os parâmetros de dados fornecidos nos parâmetros estão presentes (se não estiverem, será solicitado que o usuário escolha). Se o usuário estiver autorizado para apenas uma função, o cmdlet associará a função ao perfil automaticamente, sem fazer a solicitação ao usuário. Não há necessidade de fornecer uma credencial para configurar um perfil para uso associado a um domínio.
```
PS > Set-AWSSamlRoleProfile -StoreAs SAMLDemoProfile -EndpointName $epName
```
Como alternativa, para non-domain-joined contas, você pode fornecer credenciais do Active Directory e, em seguida, selecionar uma AWS função à qual o usuário tenha acesso, conforme mostrado na linha a seguir. Isso será útil se você tiver contas de usuário diferentes do Active Directory para diferenciar funções em sua organização (por exemplo, funções administrativas).
```
PS > $credential = Get-Credential -Message "Enter the domain credentials for the endpoint"
PS > Set-AWSSamlRoleProfile -EndpointName $epName -NetworkCredential $credential -StoreAs SAMLDemoProfile
```
1. Em qualquer um dos casos, o cmdlet `Set-AWSSamlRoleProfile` solicita que você escolha a função que deve ser armazenada no perfil. O exemplo a seguir mostra duas funções disponíveis: `ADFS-Dev` e `ADFS-Production`. As funções do IAM são associadas às credenciais de login do AD pelo administrador do AD FS.
```
Select Role
Select the role to be assumed when this profile is active
[1] 1 - ADFS-Dev [2] 2 - ADFS-Production [?] Help (default is "1"):
```
Como alternativa, é possível especificar uma função sem o prompt, inserindo o `RoleARN`, o `PrincipalARN` e os parâmetros opcionais `NetworkCredential`. Se a função especificada não estiver listada na declaração retornada pela autenticação, o usuário será solicitado a escolher entre as funções disponíveis.
```
PS > $params = @{ "NetworkCredential"=$credential, "PrincipalARN"="{arn:aws:iam::012345678912:saml-provider/ADFS}", "RoleARN"="{arn:aws:iam::012345678912:role/ADFS-Dev}"
}
PS > $epName | Set-AWSSamlRoleProfile @params -StoreAs SAMLDemoProfile1 -Verbose
```
1. Você pode criar perfis para todas as funções em um único comando ao adicionar o parâmetro `StoreAllRoles`, conforme mostrado no código a seguir. Observe que o nome da função é usado como o nome do perfil.
```
PS > Set-AWSSamlRoleProfile -EndpointName $epName -StoreAllRoles
ADFS-Dev
ADFS-Production
```
### Como usar perfis de função para executar cmdlets que exigem credenciais AWS
Para executar cmdlets que exigem AWS credenciais, você pode usar perfis de função definidos no arquivo de credencial AWS compartilhado. Forneça o nome de um perfil de função para `Set-AWSCredential` (ou como o valor de qualquer `ProfileName` parâmetro no Ferramentas da AWS para PowerShell) para obter AWS credenciais temporárias automaticamente para a função descrita no perfil.
Embora você use apenas um perfil de função por vez, pode alternar entre os perfis em uma sessão de shell. O cmdlet `Set-AWSCredential` não faz a autenticação e não obtém credenciais quando você o executa sozinho; o cmdlet registra que você deseja usar um perfil de função especificado. Até que você execute um cmdlet que exija credenciais da AWS , não ocorrerá nenhuma autenticação ou solicitação de credenciais.
Agora você pode usar as AWS credenciais temporárias obtidas com o `SAMLDemoProfile` perfil para trabalhar com o AWS serviço APIs. As seções a seguir mostram exemplos de como usar os perfis de função.
### Exemplo 1: Definir uma função padrão com `Set-AWSCredential`
Este exemplo define uma função padrão para uma Ferramentas da AWS para PowerShell sessão usando`Set-AWSCredential`. Em seguida, você pode executar cmdlets que exijam credenciais e sejam autorizados pela função especificada. Este exemplo lista todas as instâncias do Amazon Elastic Compute Cloud na região Oeste dos EUA (Oregon) que estão associadas ao perfil especificado com o cmdlet `Set-AWSCredential`.
```
PS > Set-AWSCredential -ProfileName SAMLDemoProfile
PS > Get-EC2Instance -Region us-west-2 | Format-Table -Property Instances,GroupNames
Instances GroupNames
--------- ----------
{TestInstance1} {default}
{TestInstance2} {}
{TestInstance3} {launch-wizard-6}
{TestInstance4} {default}
{TestInstance5} {}
{TestInstance6} {AWS-OpsWorks-Default-Server}
```
### Exemplo 2: Alterar perfis de função durante uma PowerShell sessão
Este exemplo lista todos os buckets do Amazon S3 disponíveis na AWS conta da função associada ao perfil. `SAMLDemoProfile` O exemplo mostra que, embora você possa ter usado outro perfil no início da Ferramentas da AWS para PowerShell sessão, você pode alterar os perfis especificando um valor diferente para o `-ProfileName` parâmetro com cmdlets que o suportam. Essa é uma tarefa comum para administradores que gerenciam o Amazon S3 a partir PowerShell da linha de comando.
```
PS > Get-S3Bucket -ProfileName SAMLDemoProfile
CreationDate BucketName
------------ ----------
7/25/2013 3:16:56 AM amzn-s3-demo-bucket
4/15/2015 12:46:50 AM amzn-s3-demo-bucket1
4/15/2015 6:15:53 AM amzn-s3-demo-bucket2
1/12/2015 11:20:16 PM amzn-s3-demo-bucket3
```
Observe que o cmdlet `Get-S3Bucket` especifica o nome do perfil criado executando o cmdlet `Set-AWSSamlRoleProfile`. Este comando poderá ser útil se você tiver configurado um perfil de função anteriormente em sua sessão (por exemplo, ao executar o cmdlet `Set-AWSCredential`) e quiser usar um perfil de função diferente para o cmdlet `Get-S3Bucket`. O gerenciador de perfil disponibiliza credenciais temporárias para o cmdlet `Get-S3Bucket`.
Embora as credenciais expirem após uma hora (um limite imposto pelo STS), o Ferramentas da AWS para PowerShell atualizará automaticamente as credenciais solicitando uma nova declaração do SAML quando a ferramenta detectar que as credenciais atuais expiraram.
Para usuários associados a um domínio, esse processo ocorre sem interrupção, porque a identidade do Windows do usuário atual é usada durante a autenticação. Para contas de non-domain-joined usuário, Ferramentas da AWS para PowerShell mostra uma solicitação de PowerShell credencial solicitando a senha do usuário. O usuário fornece credenciais que são usadas para autenticar novamente o usuário e obter uma nova asserção.
### Exemplo 3: Obter instâncias em uma região
O exemplo a seguir lista todas as instâncias do Amazon EC2 na região Ásia-Pacífico (Sydney) associadas à conta usada pelo perfil `ADFS-Production`. Este é um comando útil para retornar todas as instâncias do Amazon EC2 em uma região.
```
PS > (Get-Ec2Instance -ProfileName ADFS-Production -Region ap-southeast-2).Instances | Select InstanceType, @{Name="Servername";Expression={$_.tags | where key -eq "Name" | Select Value -Expand Value}}
InstanceType Servername
------------ ----------
t2.small DC2
t1.micro NAT1
t1.micro RDGW1
t1.micro RDGW2
t1.micro NAT2
t2.small DC1
t2.micro BUILD
```
## Leitura adicional
Para obter informações gerais sobre como implementar o acesso federado à API, consulte [Como implementar uma solução geral para API/CLI acesso federado usando o SAML](https://aws.amazon.com/blogs/security/how-to-implement-a-general-solution-for-federated-apicli-access-using-saml-2-0/) 2.0.
Para perguntas de suporte ou comentários, visite os fóruns de AWS desenvolvedores para [desenvolvimento [PowerShell de scripts](https://forums.aws.amazon.com/forum.jspa?forumID=149) ou do.NET](https://forums.aws.amazon.com/forum.jspa?forumID=61).