Trabalhar com dispositivos de usuários no grupo de usuários

Ao fazer login de usuários de grupos de usuários locais com a API de grupos de usuários do Amazon Cognito, é possível associar os logs de atividades dos usuários, provenientes da proteção contra ameaças, a cada um dos dispositivos e, opcionalmente, permitir que os usuários ignorem a autenticação multifator (MFA) se estiverem em um dispositivo confiável. O Amazon Cognito inclui uma chave de dispositivo na resposta a qualquer login que ainda não inclua informações do dispositivo. A chave do dispositivo está no formato Region_UUID. Com uma chave de dispositivo, uma biblioteca de senha remota segura (SRP) e um grupo de usuários que permita a autenticação do dispositivo, é possível solicitar que os usuários da aplicação confiem no dispositivo atual e não solicitem mais um código de MFA no login.

Como configurar dispositivos memorizados

Com os grupos de usuários do Amazon Cognito, é possível associar cada um dos dispositivos dos usuários a um identificador de dispositivo exclusivo: uma chave de dispositivo. Ao apresentar a chave do dispositivo e realizar a autenticação do dispositivo no login, é possível configurar a aplicação com um fluxo de autenticação de dispositivo confiável. Nesse fluxo, a aplicação pode apresentar aos usuários a opção de fazer login sem MFA em outro momento, conforme os requisitos de segurança da aplicação ou as preferências dos usuários. Ao final desse período, a aplicação deve alterar o status do dispositivo para não memorizado e o usuário deve fazer login com MFA até confirmar que deseja memorizar um dispositivo. Por exemplo, a aplicação pode solicitar que seus usuários confiem em um dispositivo por 30, 60 ou 90 dias. Você pode armazenar essa data em um atributo personalizado e, nessa data, alterar o status de memorização do dispositivo. Em seguida, é necessário solicitar novamente ao usuário que envie um código de MFA e configure o dispositivo para que seja novamente memorizado após a autenticação bem-sucedida.

Quando o usuário faz login com um dispositivo memorizado, é necessário realizar uma autenticação adicional do dispositivo durante o fluxo de autenticação. Para obter mais informações, consulte Fazer login com um dispositivo.

Configure o grupo de usuários para memorizar os dispositivos no menu Fazer login do grupo de usuários, em Monitoramento de dispositivos. Ao configurar a funcionalidade de dispositivos memorizados por meio do console do Amazon Cognito, você terá três opções: Always (Sempre), User Opt-In (Usuário opta por) e No (Não).

Ao selecionar Sempre memorizar ou Opção do usuário, o Amazon Cognito gera uma chave e um segredo de identificação do dispositivo toda vez que um usuário faz login em um dispositivo não identificado. A chave do dispositivo é o identificador inicial que a aplicação envia ao grupo de usuários quando o usuário realiza a autenticação do dispositivo.

Com cada dispositivo de usuário confirmado, seja lembrado automaticamente ou por opção, é possível usar a chave e o segredo do identificador do dispositivo para autenticar um dispositivo em cada login de usuário.

Também é possível definir as configurações de dispositivos memorizados para o grupo de usuários em uma solicitação de API CreateUserPool ou UpdateUserPool. Para obter mais informações, consulte a propriedade DeviceConfiguration.

A API de grupos de usuários do Amazon Cognito tem operações adicionais para dispositivos memorizados.

As operações de API com nomes que começam com Admin são para uso em aplicações do lado do servidor e devem ser autorizadas com credenciais do IAM. Para obter mais informações, consulte Noções básicas sobre a autenticação de API, OIDC e páginas de login gerenciado.

Obter uma chave do dispositivo

Sempre que o usuário faz login com a API de grupos de usuários e não inclui uma chave do dispositivo nos parâmetros de autenticação como DEVICE_KEY, o Amazon Cognito gera uma nova chave do dispositivo na resposta. Na aplicação pública do lado do cliente, coloque a chave do dispositivo no armazenamento da aplicação para que você possa incluí-la em futuras solicitações. Na aplicação confidencial do lado do servidor, defina um cookie do navegador ou outro token do lado do cliente com a chave do dispositivo do usuário.

Para que o usuário possa fazer login com o dispositivo confiável, a aplicação deve confirmar a chave do dispositivo e fornecer informações adicionais. Gere uma solicitação ConfirmDevice para o Amazon Cognito que confirme o dispositivo do usuário com a chave do dispositivo, um nome amigável, um verificador de senha e um salt. Se você configurou o grupo de usuários para autenticação opcional de dispositivos, o Amazon Cognito responderá à solicitação ConfirmDevice pedindo que o usuário escolha se deseja memorizar o dispositivo atual. Responda com a seleção do usuário em uma solicitação UpdateDeviceStatus.

Ao confirmar o dispositivo do usuário, mas não o configurar como memorizado, o Amazon Cognito armazena a associação, mas prossegue com o login que não é do dispositivo quando você fornece a respectiva chave. Os dispositivos podem gerar logs úteis para a segurança e solução de problemas do usuário. Um dispositivo confirmado, mas não memorizado, não utiliza o recurso de login, e sim o de logs de monitoramento de segurança. Ao ativar a proteção contra ameaças para o cliente da aplicação e codificar uma impressão digital do dispositivo na solicitação, o Amazon Cognito associa os eventos do usuário ao dispositivo confirmado.

Fazer login com um dispositivo

Depois que o dispositivo de um usuário é configurado para ser memorizado, o Amazon Cognito não exige mais que ele envie um código de MFA ao fazer login com a mesma chave do dispositivo. A autenticação do dispositivo substitui apenas o desafio da autenticação MFA por um desafio de autenticação do dispositivo. Não é possível conectar os usuários somente com a autenticação do dispositivo. O usuário deve primeiro concluir a autenticação com a senha ou um desafio personalizado. Veja a seguir o processo de autenticação de um usuário em um dispositivo memorizado.

Para realizar a autenticação do dispositivo em um fluxo que use acionadores do Lambda de desafio de autenticação personalizada, transmita um parâmetro DEVICE_KEY na solicitação de API InitiateAuth. Depois que o usuário passar por todos os desafios e o desafio CUSTOM_CHALLENGE gerar um valor issueTokens de true, o Amazon Cognito vai gerar um desafio DEVICE_SRP_AUTH final.

O pseudocódigo a seguir demonstra como calcular valores para a resposta DEVICE_PASSWORD_VERIFIER ao desafio. Para autenticação SRP com um dispositivo, gere um novo segredo de SRP para o usuário: uma nova senha de alta entropia DeviceSecret, um salt e o verificador de senha associado. Esses valores são distintos da senha, do salt e do verificador usados para a autenticação SRP do usuário. Eles são usados somente para autenticação do dispositivo e são armazenados somente no dispositivo. As funções para gerar os segredos de SRP para os dispositivos dos usuários estão disponíveis nas bibliotecas de SRP que estão disponíveis em vários SDKs.

PASSWORD_CLAIM_SECRET_BLOCK = SECRET_BLOCK
TIMESTAMP = "Tue May 7 00:09:40 UTC 2025"
k = SHA256(N || g) as a non-negative integer in big-endian
u = SHA256(SRP_A || SRP_B) as a non-negative integer in big-endian
x = SHA256(salt || SHA256(DeviceGroupKey || DeviceKey || ":" || DeviceSecret)) as a non-negative integer in big-endian
S_USER = (SRP_B - k * g^x)^(a + u * x) % N
K_USER = HKDF_HMAC_SHA256(salt=u, ikm=S_USER, info="Caldera Derived Key", length=16 bytes)
PASSWORD_CLAIM_SIGNATURE = Base64(HMAC_SHA256(key=K_USER, message=(DeviceGroupKey || DeviceKey || PASSWORD_CLAIM_SECRET_BLOCK || TIMESTAMP)))

Visualizar, atualizar e esquecer dispositivos

Com a API do Amazon Cognito, é possível implementar os recursos a seguir na aplicação.

Os tokens de acesso que autorizam as solicitações de API nas descrições a seguir devem incluir o escopo aws.cognito.signin.user.admin. O Amazon Cognito adiciona uma reivindicação desse escopo a todos os tokens de acesso que você gera com a API de grupos de usuários do Amazon Cognito. Os IdPs de terceiros devem gerenciar separadamente os dispositivos e a MFA para os usuários que se autenticam no Amazon Cognito. No login gerenciado, é possível solicitar o escopo aws.cognito.signin.user.admin, mas o login gerenciado adiciona automaticamente as informações do dispositivo a logs de usuário de segurança avançados e não oferece a possibilidade de memorizar os dispositivos.

Exibir informações sobre um dispositivo

É possível consultar informações sobre o dispositivo de um usuário para determinar se ele ainda está em uso. Por exemplo, convém desativar dispositivos memorizados depois que eles não tiverem feito login por 90 dias.

Exibir uma lista de todos os dispositivos do usuário.

É possível exibir uma lista de todos os dispositivos do usuário e as respectivas propriedades. Por exemplo, convém verificar se o dispositivo atual corresponde a um dispositivo memorizado.

Esquecer um dispositivo

É possível excluir a chave do dispositivo de um usuário. Convém fazer isso ao constatar que o usuário não usa mais um dispositivo ou ao detectar atividades incomuns e solicitar que um usuário conclua a MFA novamente. Para registrar novamente o dispositivo em um momento posterior, é necessário gerar e armazenar uma nova chave do dispositivo.