Usar a API de grupos de usuários e endpoints de grupo de usuários do Amazon Cognito

Quando quiser se inscrever, fazer login e gerenciar usuários no grupo de usuários, você terá duas opções.

1. Os endpoints do grupo de usuários incluem a interface do usuário hospedada e os endpoints de federação. Eles formam um pacote de páginas da web públicas que o Amazon Cognito ativa quando você seleciona um domínio para o grupo de usuários. Para começar rapidamente com os recursos de autenticação e autorização dos grupos de usuários do Amazon Cognito, incluindo páginas de inscrição, login, gerenciamento de senhas e autenticação multifator (MFA), use a interface de usuário integrada da interface de usuário hospedada. Os outros endpoints de grupo de usuários facilitam a autenticação com provedores de identidades (IdPs) de terceiros. Os serviços que eles realizam incluem o seguinte:

   1. Endpoints de retorno de chamada do provedor de serviços para solicitações autenticadas de seus IdPs, como saml2/idpresponse e oauth2/idpresponse. Quando o Amazon Cognito é um provedor de serviços (SP) intermediário entre sua aplicação e o IdP, os endpoints de retorno de chamada representam o serviço.

   2. Endpoints que fornecem informações sobre seu ambiente, como oauth2/userInfo e jwks.json. Sua aplicação usa esses endpoints ao verificar tokens ou recupera dados do perfil do usuário com AWS SDKs e bibliotecas OAuth 2.0.

2. A API de grupos de usuários do Amazon Cognito é um conjunto de ferramentas para aplicação web ou aplicativo móvel depois são coletadas informações de login em seu próprio front-end personalizado para autenticar usuários. A autenticação da API de grupos de usuários produz os tokens web JSON a seguir.

   1. Um token de identidade com declarações de atributos verificáveis do usuário.

   2. Um token de acesso que autoriza o usuário a criar solicitações de API autorizadas por token para um endpoint de serviço da AWS.

      nota

      Por padrão, os tokens de acesso da autenticação da API de grupos de usuários contêm apenas o escopo aws.cognito.signin.user.admin. Para gerar um token de acesso com escopos adicionais, por exemplo, para autorizar uma solicitação para uma API de terceiros, solicite os escopos durante a autenticação por meio dos endpoints do grupo de usuários ou adicione escopos personalizados em um Acionador do Lambda antes da geração do token. A personalização do token de acesso adiciona custos à sua fatura da AWS.

Você pode vincular um usuário federado, que normalmente faria login por meio dos endpoints de grupos de usuários, a um usuário cujo perfil seja local para sua lista de usuários. Um usuário local existe exclusivamente em seu diretório de grupo de usuários sem federação por meio de um IdP externo. Se você vincular a identidade federada dele a um usuário local em uma solicitação de API AdminLinkProviderForUser, ele poderá fazer login com a API de grupos de usuários. Para obter mais informações, consulte Vincular usuários federados a um perfil de usuário existente.

A API de grupos de usuários do Amazon Cognito tem duplo propósito. Ela cria e configura os recursos de grupos de usuários do Amazon Cognito. Por exemplo, você pode criar grupos de usuários, adicionar acionadores do AWS Lambda e configurar o domínio de interface de usuário hospedado. A API de grupos de usuários também realiza operações de inscrição, login e outras operações para usuários locais e vinculados.

Exemplo de cenário com a API de grupos de usuários do Amazon Cognito

1. O usuário seleciona o botão “Criar uma conta” que você criou na aplicação. Ele inserem um endereço de e-mail e uma senha.

2. A aplicação envia uma solicitação da API SignUp e cria um usuário no grupo de usuários.

3. A aplicação solicita que o usuário forneça um código de confirmação enviado por e-mail. O usuário insere o código que recebeu em uma mensagem de e-mail.

4. A aplicação envia uma solicitação da API ConfirmSignUp com o código de confirmação do usuário.

5. A aplicação solicita que o usuário informe o nome de usuário e a senha, e ele insere essas informações.

6. A aplicação envia uma solicitação da API InitiateAuth e armazena um token de ID, token de acesso e token de atualização. A aplicação chama as bibliotecas do OIDC para gerenciar os tokens do usuário e manter uma sessão persistente para esse usuário.

Na API de grupos de usuários do Amazon Cognito, você não pode conectar usuários que se federam por meio de um IdP. É necessário autenticar esses usuários por meio dos endpoints de grupo de usuários. Para ter mais informações sobre os endpoints do grupo de usuários que incluem a interface do usuário hospedada, consulte Referência da interface do usuário hospedada e endpoints de federação do grupo de usuários. Os usuários federados podem começar na interface de usuário hospedada e selecionar o IdP deles ou você pode ignorar a interface de usuário hospedada e enviar os usuários diretamente ao seu IdP para fazer login. Quando a solicitação de API para Autorizar endpoint inclui um parâmetro de IdP, o Amazon Cognito redireciona silenciosamente o usuário para a página de login do IdP.

Exemplo de cenário com endpoints de grupo de usuários

1. O usuário seleciona o botão “Criar uma conta” que você criou na aplicação.

2. Você apresenta ao usuário uma lista dos provedores de identidade social nos quais você registrou as credenciais de desenvolvedor. O usuário escolhe a Apple.

3. A aplicação inicia uma solicitação para Autorizar endpoint com o nome do provedor SignInWithApple.

4. O navegador do usuário abre a página de autorização do Apple OAuth. O usuário opta por permitir que o Amazon Cognito leia as informações do perfil dele.

5. O Amazon Cognito confirma o token de acesso da Apple e consulta o perfil Apple do usuário.

6. O usuário apresenta um código de autorização do Amazon Cognito para a aplicação.

7. A aplicação troca o código de autorização pelo Endpoint de token e armazena um token de ID, token de acesso e token de atualização. A aplicação chama as bibliotecas do OIDC para gerenciar os tokens do usuário e manter uma sessão persistente para esse usuário.

A API e os endpoints de grupo de usuários são compatíveis com uma variedade de cenários descritos neste guia. As seções a seguir examinam como a API de grupos de usuários se divide ainda mais em classes que atendem aos seus requisitos de inscrição, login e gerenciamento de recursos.

Operações de API autenticadas e não autenticadas de grupos de usuários do Amazon Cognito

A API de grupos de usuários do Amazon Cognito, tanto uma interface de gerenciamento de recursos quanto uma interface de autenticação e autorização voltada para o usuário, combina os modelos de autorização a seguir nas respectivas operações. Dependendo da operação da API, talvez seja necessário fornecer autorização com credenciais do IAM, um token de acesso, um token de sessão, um segredo do cliente ou uma combinação deles. Para muitas operações de autenticação e autorização de usuários, você pode escolher entre versões autenticadas e não autenticadas da solicitação. Operações não autenticadas são a prática recomendada de segurança para aplicações que você distribui para os usuários, como aplicações móveis; não é necessário incluir nenhum segredo no código.

Você pode atribuir permissões nas políticas do IAM somente para Operações de gerenciamento autenticadas pelo IAM e Operações de usuário autenticadas pelo IAM.

Operações de gerenciamento autenticadas pelo IAM

As operações de gerenciamento autenticadas pelo IAM modificam e exibem o grupo de usuários e a configuração do cliente da aplicação, como você faria no AWS Management Console.

Por exemplo, para modificar o grupo de usuários em uma solicitação da API UpdateUserPool, você deve apresentar credenciais da AWS e permissões do IAM para atualizar o recurso.

Para autorizar essas solicitações na AWS Command Line Interface (AWS CLI) ou em um AWS SDK, configure o ambiente com variáveis de ambiente ou configuração de cliente que adicione credenciais do IAM à solicitação. Para ter mais informações, consulte Acessar a AWS usando suas credenciais da AWS na Referência geral da AWS. Você também pode enviar solicitações diretamente aos endpoints de serviço da API de grupos de usuários do Amazon Cognito. Você deve autorizar ou assinar essas solicitações com credenciais da AWS que incorpora no cabeçalho da solicitação. Para ter mais informações, consulte Assinar solicitações de API da AWS.

Operações de gerenciamento autenticadas pelo IAM
AddCustomAttributes
CreateGroup
CreateIdentityProvider
CreateResourceServer
CreateUserImportJob
CreateUserPool
CreateUserPoolClient
CreateUserPoolDomain
DeleteGroup
DeleteIdentityProvider
DeleteResourceServer
DeleteUserPool
DeleteUserPoolClient
DeleteUserPoolDomain
DescribeIdentityProvider
DescribeResourceServer
DescribeRiskConfiguration
DescribeUserImportJob
DescribeUserPool
DescribeUserPoolClient
DescribeUserPoolDomain
GetCSVHeader
GetGroup
GetIdentityProviderByIdentifier
GetSigningCertificate
GetUICustomization
GetUserPoolMfaConfig
ListGroups
ListIdentityProviders
ListResourceServers
ListTagsForResource
ListUserImportJobs
ListUserPoolClients
ListUserPools
ListUsers
ListUsersInGroup
SetRiskConfiguration
SetUICustomization
SetUserPoolMfaConfig
StartUserImportJob
StopUserImportJob
TagResource
UntagResource
UpdateGroup
UpdateIdentityProvider
UpdateResourceServer
UpdateUserPool
UpdateUserPoolClient
UpdateUserPoolDomain

Operações de usuário autenticadas pelo IAM

Operações de usuário autenticadas pelo IAM para se inscrever, fazer login, gerenciar credenciais, modificar e ver os usuários.

Por exemplo, você pode ter um nível de aplicação do lado do servidor que oferece suporte a um front-end da Web. A aplicação do lado do servidor é um cliente confidencial do OAuth no qual você confia, com acesso privilegiado aos seus recursos do Amazon Cognito. Para registrar um usuário na aplicação, o servidor pode incluir credenciais da AWS em uma solicitação da API AdminCreateUser. Para obter mais informações sobre os tipos de clientes do OAuth, consulte Client Types (Tipos de cliente) na Estrutura de autorização do OAuth 2.0.

Para autorizar essas solicitações na AWS CLI ou em um AWS SDK, configure o ambiente da aplicação do lado do servidor com variáveis de ambiente ou configuração do cliente que adiciona credenciais do IAM à solicitação. Para ter mais informações, consulte Acessar a AWS usando suas credenciais da AWS na Referência geral da AWS. Você também pode enviar solicitações diretamente aos endpoints de serviço da API de grupos de usuários do Amazon Cognito. Você deve autorizar ou assinar essas solicitações com credenciais da AWS que incorpora no cabeçalho da solicitação. Para ter mais informações, consulte Assinar solicitações de API da AWS.

Se o cliente da aplicação tiver um segredo de cliente, você deverá fornecer suas credenciais do IAM e, dependendo da operação, o parâmetro SecretHash ou o valor SECRET_HASH em AuthParameters. Para obter mais informações, consulte Computar valores de hash de segredo.

Operações de usuário autenticadas pelo IAM
AdminAddUserToGroup
AdminConfirmSignUp
AdminCreateUser
AdminDeleteUser
AdminDeleteUserAttributes
AdminDisableProviderForUser
AdminDisableUser
AdminEnableUser
AdminForgetDevice
AdminGetDevice
AdminGetUser
AdminInitiateAuth
AdminLinkProviderForUser
AdminListDevices
AdminListGroupsForUser
AdminListUserAuthEvents
AdminRemoveUserFromGroup
AdminResetUserPassword
AdminRespondToAuthChallenge
AdminSetUserMFAPreference
AdminSetUserPassword
AdminSetUserSettings
AdminUpdateAuthEventFeedback
AdminUpdateDeviceStatus
AdminUpdateUserAttributes
AdminUserGlobalSignOut

Operações de usuário não autenticadas

Operações de usuário não autenticadas para se inscrever, fazer login e iniciar redefinições de senha para os usuários. Use operações de API não autenticadas ou públicas quando quiser que qualquer pessoa na internet se inscreva e faça login na aplicação.

Por exemplo, para registrar um usuário na aplicação, você pode distribuir um cliente público do OAuth que não fornece nenhum acesso privilegiado aos segredos. É possível registrar esse usuário com a operação de API não autenticada SignUp.

Para enviar essas solicitações em um cliente público que você desenvolveu com um AWS SDK, você não precisa configurar nenhuma credencial. Você também pode enviar solicitações diretamente aos endpoints de serviço da API de grupos de usuários do Amazon Cognito sem autorização adicional.

Se o cliente da aplicação tiver um segredo de cliente, você deverá fornecer, dependendo da operação, o parâmetro SecretHash ou o valor SECRET_HASH em AuthParameters. Para obter mais informações, consulte Computar valores de hash de segredo.

Operações de usuário não autenticadas
SignUp
ConfirmSignUp
ResendConfirmationCode
ForgotPassword
ConfirmForgotPassword
InitiateAuth

Operações de usuário autorizadas por token

As operações de usuário autorizadas por token terminam a sessão, gerenciam as credenciais, modificam e visualizam os usuários após eles fazerem login ou iniciarem o processo de login. Use operações de API autorizadas por token quando não quiser distribuir segredos na aplicação e quiser autorizar solicitações com as credenciais do seu próprio usuário. Se o usuário tiver concluído o login, você deverá autorizar a solicitação de API autorizada por token com um token de acesso. Se o usuário estiver no meio de um processo de login, você deverá autorizar a solicitação de API autorizada por token com um token de sessão que o Amazon Cognito retornou em resposta à solicitação anterior.

Por exemplo, em um cliente público, talvez você queira atualizar o perfil de um usuário de uma forma que restrinja o acesso de gravação somente ao próprio perfil do usuário. Para fazer essa atualização, o cliente pode incluir o token de acesso do usuário em uma solicitação da API UpdateUserAttributes.

Para enviar essas solicitações em um cliente público que você desenvolveu com um AWS SDK, você não precisa configurar nenhuma credencial. Inclua um parâmetro AccessToken ou Session na solicitação. Você também pode enviar solicitações diretamente aos endpoints de serviço da API de grupos de usuários do Amazon Cognito. Para autorizar uma solicitação para um endpoint de serviço, inclua o token de acesso ou sessão no corpo POST da solicitação.

Para assinar uma solicitação de API para uma operação autorizada por token, inclua o token de acesso como cabeçalho Authorization na solicitação, no formato Bearer <Base64-encoded access token>.

Operações de usuário autorizadas por token	AccessToken	Sessão
RespondToAuthChallenge		✓
ChangePassword	✓
GetUser	✓
UpdateUserAttributes	✓
DeleteUserAttributes	✓
DeleteUser	✓
ConfirmDevice	✓
ForgetDevice	✓
GetDevice	✓
ListDevices	✓
UpdateDeviceStatus	✓
GetUserAttributeVerificationCode	✓
VerifyUserAttribute	✓
SetUserSettings	✓
SetUserMFAPreference	✓
GlobalSignOut	✓
AssociateSoftwareToken	✓	✓
UpdateAuthEventFeedback		✓
VerifySoftwareToken	✓	✓
RevokeToken¹

¹ RevokeToken usa um token de atualização como parâmetro. O token de atualização serve como token de autorização e como recurso de destino.