Como configurar o Amazon Cognito para autenticação federada usando o Azure AD

Conforme mostrado na figura 1, a arquitetura de uma aplicação de alto nível usando tecnologia serverless com autenticação federada normalmente envolve as seguintes etapas:

1. O usuário seleciona seu IdP preferido para autenticar.
2. O usuário é redirecionado para o IdP federado para fazer login. Na autenticação bem-sucedida, o IdP envia de volta um token ou SAML assertion contendo detalhes de identidade do usuário em um Amazon Cognito User Pool.
3. O Amazon Cognito User Pool emite um conjunto de tokens para a aplicação
4. A aplicação pode usar o token emitido pelo Amazon Cognito User Pool para acesso autorizado às APIs protegidas pelo Amazon API Gateway.

Para saber mais sobre o fluxo de autenticação com a federação SAML, consulte a publicação no blog Building ADFS Federation for your Web App using Amazon Cognito User Pools (Criação de uma federação ADFS para sua aplicação web usando Amazon Cognito User Pools).

Instruções passo-a-passo para habilitar o Azure AD como provedor de identidades federado em um Amazon Cognito User Pool

Esta publicação o guiará pelas seguintes etapas:

1. Criar um Amazon Cognito User Pool
2. Adicionar o Amazon Cognito como uma aplicação corporativa no Azure AD
3. Adicionar o Azure AD como provedor de identidades (IdP) SAML no Amazon Cognito
4. Criar um cliente de aplicação e usar o IdP SAML recém-criado para o Azure AD

Pré-requisitos

Você precisará ter acesso administrativo ao Azure AD, uma conta da AWS e a AWS Command Line Interface (AWS CLI) instalada em sua máquina. Siga as instruções para instalar, atualizar e desinstalar a AWS CLI versão 2. Para configurar sua instalação, siga as instruções para configurar a AWS CLI. Se você não quiser instalar a AWS CLI, também poderá executar esses comandos no AWS CloudShell, que fornece um shell baseado em navegador para gerenciar, explorar e interagir com segurança aos seus recursos na AWS.

Etapa 1: criar um Amazon Cognito User Pool

Os procedimentos nesta publicação usam a AWS CLI, mas você também pode seguir as instruções para usar o Console de Gerenciamento da AWS para criar um novo User Pool.

Como criar um User Pool na AWS CLI

1. Use o comando a seguir para criar um User Pool com configurações padrão. Substitua <yourUserPoolName> pelo nome que deseja usar para o User Pool.
2. aws cognito-idp create-user-pool \
3. --pool-name <yourUserPoolName>

Você deve ver uma saída contendo vários detalhes sobre o User Pool recém-criado.

4. Copie o valor do ID do User Pool, que neste exemplo é ap-southeast-2_xx0xXxXXX. Você precisará desse valor para as próximas etapas.

"UserPool": {
        "Id": "ap-southeast-2_xx0xXxXXX",
        "Name": "example-corp-prd-userpool"
       "Policies": { …

Adicionar um nome de domínio ao User Pool

Um dos muitos recursos úteis do Amazon Cognito é a interface de usuário hospedada, que fornece uma interface da web configurável para o login do usuário. A interface do usuário hospedada pode ser acessada a partir de um nome de domínio que precisa ser adicionado ao User Pool. Há duas opções para adicionar um nome de domínio a um User Pool. Você pode usar um domínio do Amazon Cognito ou um nome de domínio que seja seu. Essa solução usa um domínio do Amazon Cognito, que terá o seguinte formato:

https://<yourDomainPrefix>.auth.<aws-region>.amazoncognito.com

Como adicionar um nome de domínio ao User Pool

1. Use o seguinte comando da CLI para adicionar um domínio do Amazon Cognito ao User Pool. Substitua <yourDomainPrefix> por um prefixo de nome de domínio exclusivo (por exemplo example-corp-prd). Observe que você não pode usar as palavras-chave aws, amazon ou cognito para o prefixo do domínio.

   aws cognito-idp create-user-pool-domain \
   --domain <yourDomainPrefix> \
   --user-pool-id <yourUserPoolID>

Preparar informações para a configuração do Azure AD

Então, é hora de preparar o Identifier (Entity ID) e a Reply URL, que são necessários para adicionar o Amazon Cognito como aplicação corporativa no Azure AD (feito na etapa 2 abaixo). O Azure AD espera esses valores em um formato muito específico. Em um editor de texto, anote seus valores para Identifier (Entity ID) e a Reply URL de acordo com os seguintes formatos:

• Para Identifier (Entity ID), o formato é:

  urn:amazon:cognito:sp:<yourUserPoolID>

  Por exemplo:

  urn:amazon:cognito:sp:ap-southeast-2_nYYYyyYyYy
  

• Para Reply URL, o formato é:

  https://<yourDomainPrefix>.auth.<aws-region>.amazoncognito.com/saml2/idpresponse
  

  Por exemplo:

  https://example-corp-prd.auth.ap-southeast-2.amazoncognito.com/saml2/idpresponse
  

  Observação: a Reply URL é o endpoint em que o Azure AD enviará a declaração SAML para o Amazon Cognito durante o processo de autenticação do usuário.

Atualize os espaços reservados acima com seus valores (sem < >) e anote os valores de Identifier (Entity ID) e a Reply URL em um editor de texto para referência futura.

Para obter mais informações, consulte Adicionar provedores de identidade SAML a um User Pool no guia do desenvolvedor do Amazon Cognito.

Etapa 2: adicionar o Amazon Cognito como aplicação corporativa no Azure AD

Nesta etapa, você adicionará um Amazon Cognito User Pool como uma aplicação no Azure AD, para estabelecer uma relação de confiança entre eles.

Como adicionar uma nova aplicação no Azure AD

1. Faça login no Portal do Azure.
2. Na seção Azure Services (Serviços do Azure), escolha Azure Active Directory.
3. Na barra lateral esquerda, escolha Enterprise applications (Aplicações corporativas).
4. Escolha New application (Nova aplicação).
5. Na página Browse Azure AD Gallery (Pesquisar na galeria do Azure AD), escolha Create your own application (Crie sua própria aplicação).

Em What’s the name of your app? (Qual é o nome da sua aplicação?), insira um nome para ela e selecione Integrate any other application you don’t find in the gallery (Non-gallery) [Integrar qualquer outra aplicação que não encontrar na galeria (fora da galeria], conforme mostrado na figura 2. Escolha Create (Criar).

Levará alguns segundos para que a aplicação seja criada no Azure AD. Depois, você deverá ser redirecionado para a página Overview (Visão geral) da aplicação recém-adicionada.

Observação: ocasionalmente, essa etapa pode resultar em um erro Not Found (Não encontrado), mesmo que o Azure AD tenha criado uma nova aplicação. Se isso acontecer, no Azure AD, volte para Enterprise applications (Aplicações corporativas) e pesquise sua aplicação pelo nome.

Como configurar o Single Sign-on usando SAML

1. Na página Getting started (Introdução), no quadro Set up single sign on (Configurar single sign on), escolha Get started (Começar), conforme mostrado na figura 3.

Isso adiciona grupo claims para que o Amazon Cognito possa receber os detalhes da associação ao grupo do usuário autenticado como parte da declaração SAML.

8. Em um editor de texto, anote os Claim names (Nomes das Claims) em Additional claims (Claims adicionais), conforme mostrado na figura 5. Você precisará deles ao criar o mapeamento de atributos no Amazon Cognito.

9. Feche a tela User Attributes & Claims (Atributos e claims de usuário) selecionando o X no canto superior direito. Você será redirecionado para a página Set up Single Sign-on with SAML (Configurar o Single Sign-on com o SAML).

10. Role para baixo até a seção SAML Signing Certificate (Certificado de assinatura SAML) e copie o URL de metadados da federação da aplicação escolhendo o ícone copiar para a área de transferência (destacado com seta vermelha na figura 6). Mantenha esse URL em um editor de texto, pois você precisará dele na próxima etapa.

Etapa 3: adicionar o Azure AD como SAML IdP no Amazon Cognito

Em seguida, você precisará de um atributo no Amazon Cognito User Pool em que os detalhes da associação do grupo no Azure AD possam ser recebidos, e adicionará o Azure AD como um provedor de identidades.

Como adicionar um atributo personalizado ao User Pool e adicionar o Azure AD como um provedor de identidades

1. Use o seguinte comando da CLI para adicionar um atributo personalizado ao User Pool. Substitua <yourUserPoolID> e <customAttributeName> por seus próprios valores.

   aws cognito-idp add-custom-attributes \
   --user-pool-id <yourUserPoolID> \
   --custom-attributes Name=<customAttributeName>,AttributeDataType="String"
   

   Se o comando for bem-sucedido, você não verá nenhuma saída.

2. Use o seguinte comando da CLI para adicionar o Azure AD como um provedor de identidades. Substitua o seguinte por seus próprios valores:
   • Replace <yourUserPoolID> with Amazon Cognito user pool ID copied previously.
   • Replace <IDProviderName> with a name for your identity provider (for example, Example-Corp-IDP).
   • Replace <MetadataURLCopiedFromAzureAD> with the Metadata URL copied from Azure AD.
   • Replace <customAttributeName> with custom attribute name created previously.

   aws cognito-idp create-identity-provider \
   --user-pool-id <yourUserPoolID> \
   --provider-name=<IDProviderName> \
   --provider-type SAML \
   --provider-details MetadataURL=<MetadataURLCopiedFromAzureAD> \
   --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress,<customAttributeName>=http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
   

   A execução bem-sucedida desse comando adiciona o Azure AD como um IdP SAML ao seu Amazon Cognito User Pool.

Etapa 4: criar um cliente de aplicação e usar o IdP SAML recém-criado para o Azure AD

Antes de usar o Amazon Cognito em sua aplicação web, você precisa registrar essa aplicação no Amazon Cognito como um app client. Um cliente de aplicação (app client) é uma entidade dentro de um Amazon Cognito User Pool que tem permissão para chamar operações de API não autenticadas (operações que não exigem um usuário autenticado), por exemplo, para registrar, fazer login e lidar com senhas esquecidas.

Como criar um cliente de aplicação

1. Use o comando a seguir para criar um app client. Substitua o seguinte por seus próprios valores:
   • • Substitua <yourUserPoolID> pelo ID do Amazon Cognito User Pool criado anteriormente.
     • Substitua <yourAppClientName> pelo nome de seu app client.
     • Substitua <callbackURL> pelo URL de sua aplicação web que receberá o código de autorização. Ele deve ser um endpoint HTTPS, exceto em um ambiente de desenvolvimento local onde você pode usar http://localhost:PORT_NUMBER.
     • Use o parâmetro –allowed-o-auth-flows para fluxos OAuth permitidos que você deseja habilitar. Neste exemplo, usamos código para concessão de código de autorização.
     • Use o parâmetro –allowed-o-auth-scopes para especificar quais escopos de OAuth (como telefone, e-mail, openID) o Amazon Cognito incluirá nos tokens. Neste exemplo, usamos openID.
     • Substitua <IDProviderName> pelo mesmo nome usado para o provedor de ID anteriormente.
   • <IDProviderName> with the same name you used for ID provider previously.

   aws cognito-idp create-user-pool-client \
   --user-pool-id <yourUserPoolID> \
   --client-name <yourAppClientName> \
   --no-generate-secret \
   --callback-urls <callbackURL> \
   --allowed-o-auth-flows code \
   --allowed-o-auth-scopes openid email\
   --supported-identity-providers <IDProviderName> \
   --allowed-o-auth-flows-user-pool-client
   

A execução bem-sucedida desse comando fornecerá uma saída no seguinte formato. Em um editor de texto, anote o ClientId para referência na aplicação web. No exemplo a seguir, o ClientId é 7xyxyxyxyxyxyxyxyxyxy.

{
    "UserPoolClient": {
        "UserPoolId": "ap-southeast-2_xYYYYYYY",
        "ClientName": "my-client-name",
        "ClientId": "7xyxyxyxyxyxyxyxyxyxy",
        "LastModifiedDate": "2021-05-04T17:33:32.936000+12:00",
        "CreationDate": "2021-05-04T17:33:32.936000+12:00",
        "RefreshTokenValidity": 30,
        "SupportedIdentityProviders": [
            "Azure-AD"
        ],
        "CallbackURLs": [
            "http://localhost:3030"
        ],
        "AllowedOAuthFlows": [
            "code"
        ],
        "AllowedOAuthScopes": [
            "openid", "email"
        ],
        "AllowedOAuthFlowsUserPoolClient": true
    }
}

TestTeste a configuração

Em seguida, faça um teste rápido para verificar se tudo está configurado corretamente.

1. Abra o console do Amazon Cognito.
2. Escolha Manage User Pools (Gerenciar grupos de usuários) e selecione o User Pool que você criou na Etapa 1: criar um Amazon Cognito User Pool.
3. Na barra lateral esquerda, escolha App client settings (Configurações do cliente da aplicação) e procure o cliente de aplicação que você criou na Etapa 4: criar um cliente de aplicação e usar o IdP SAML recém-criado para o Azure AD. Role até a seção Hosted UI (Interface do usuário hospedada) e escolha Launch Hosted UI (Iniciar interface do usuário hospedada), conforme mostrado na figura 7.

1. Na página de login, conforme mostrado na figura 8, você deve ver todos os IdPs habilitados no App client. Escolha o botão Azure-AD, que redireciona você para a página de login hospedada em https://login.microsoftonline.com/.

5. Faça login usando sua ID corporativa. Se tudo estiver funcionando corretamente, você deve ser redirecionado de volta para o URL de retorno de chamada após a autenticação bem-sucedida.

(Opcional) Adicionar autenticação à uma aplicação de página única

Uma maneira de adicionar autenticação segura usando o Amazon Cognito em uma aplicação de página única (SPA) é usar o método Auth.federatedSignIn() da classe Auth do AWS Amplify. O AWS Amplify fornece SDKs para integrar sua aplicação web ou para dispositivos móveis a uma lista crescente de serviços da AWS, incluindo integração com o Amazon Cognito User Pool. O método federatedSign() renderizará a interface do usuário hospedada que oferece aos usuários a opção de fazer login com os provedores de identidade habilitados no app client  (na etapa 4), conforme mostrado na figura 8. Uma vantagem da interface do usuário hospedada é que você não precisa escrever nenhum código para renderizá-la. Além disso, ela implementará de forma transparente a concessão do código de autorização com o PKCE e fornecerá com segurança à sua aplicação do lado do cliente os tokens (ID, Acesso e Refresh) necessários para acessar as APIs de backend.

Para obter um exemplo de aplicação web e instruções para conectá-la à autenticação do Amazon Cognito, consulte o repositório aws-amplify-oidc-federation do GitHub.

Conclusão

Nesta publicação, você aprendeu como integrar um Amazon Cognito User Pool com o Azure AD como um provedor de identidades SAML externo, para permitir que seus usuários usem a ID corporativa para fazer login em aplicações web ou em dispositivos móveis.

Para obter mais informações sobre essa solução, assista ao nosso vídeo Integrating Amazon Cognito with Azure Active Directory (Integração do Amazon Cognito com o Azure Active Directory) (a partir do minuto 25:26) no canal oficial da AWS na Twitch. No vídeo, você encontrará uma demonstração completa de como integrar o Amazon Cognito ao Azure AD e como usar o SDK do AWS Amplify para adicionar autenticação a uma aplicação React simples (usando o exemplo de uma loja de animais de estimação). O vídeo também mostra como você pode acessar detalhes de associação de grupo do Azure AD para autorização e controle de acesso refinado.

Se você tiver algum feedback sobre esta publicação, envie os comentários na seção Comentários abaixo. Se você tiver dúvidas sobre esta publicação, inicie um novo tópico no fórum do Amazon Cognito ou em Entre em contato com o AWS Support.