Acionador do Lambda para definir desafio de autenticação

O gatilho de desafio define auth é uma função do Lambda que mantém a sequência de desafios em um fluxo de autenticação personalizado. Ele declara o sucesso ou o fracasso da sequência de desafios e define o próximo desafio se a sequência ainda não estiver completa.

Definir o desafio de autenticação

O Amazon Cognito invoca esse acionador para iniciar o fluxo de autenticação personalizado.

A solicitação desse acionador do Lambda contém session. O parâmetro session é uma matriz que contém todos os desafios apresentados ao usuário no processo de autenticação atual. A solicitação também inclui o resultado correspondente. A matriz session armazena detalhes do desafio (ChallengeResult) em ordem cronológica. O desafio session[0] representa o primeiro que o usuário recebe.

Você pode fazer com que o Amazon Cognito verifique senhas de usuário antes que ele emita seus desafios personalizados. Todos os gatilhos do Lambda associados à categoria Autenticação das cotas de taxa de solicitação serão executados quando você realizar a autenticação SRP em um fluxo de desafio personalizado. Veja uma visão geral do processo:

1. Sua aplicação inicia o login chamando InitiateAuth ou AdminInitiateAuth com o mapa AuthParameters. Os parâmetros devem incluir CHALLENGE_NAME: SRP_A, e os valores de SRP_A e USERNAME.

2. O Amazon Cognito invoca o acionador do Lambda de desafio de autenticação com uma sessão inicial que contém challengeName: SRP_A e challengeResult: true.

3. Depois de receber essas entradas, a função do Lambda responde com challengeName: PASSWORD_VERIFIER, issueTokens: false, failAuthentication: false.

4. Se a verificação de senha for bem-sucedida, o Amazon Cognito invocará sua função do Lambda novamente com uma nova sessão contendo challengeName: PASSWORD_VERIFIER e challengeResult: true.

5. Para iniciar seus desafios personalizados, sua função do Lambda responde com challengeName: CUSTOM_CHALLENGE, issueTokens: false e failAuthentication: false. Se você não quiser iniciar seu fluxo de autenticação personalizado com a verificação de senha, poderá iniciar o login com o mapa AuthParameters incluindo CHALLENGE_NAME: CUSTOM_CHALLENGE.

6. O loop de desafios se repetirá até que todos os desafios sejam respondidos.

O exemplo a seguir mostra uma solicitação InitiateAuth inicial que precede a autenticação personalizada com um fluxo SRP.

{
    "AuthFlow": "CUSTOM_AUTH",
    "ClientId": "1example23456789",
    "AuthParameters": {
        "CHALLENGE_NAME": "SRP_A",
        "USERNAME": "testuser",
        "SRP_A": "[SRP_A]",
        "SECRET_HASH": "[secret hash]"
    }
}

Parâmetros do acionador do Lambda para definir o desafio de autenticação

A solicitação que o Amazon Cognito transmite para essa função do Lambda é uma combinação dos parâmetros abaixo e dos parâmetros comuns que o Amazon Cognito adiciona a todas as solicitações.

JSON

{
    "request": {
        "userAttributes": {
            "string": "string",
                . . .
        },
        "session": [
            ChallengeResult,
            . . .
        ],
        "clientMetadata": {
            "string": "string",
            . . .
        },
        "userNotFound": boolean
    },
    "response": {
        "challengeName": "string",
        "issueTokens": boolean,
        "failAuthentication": boolean
    }
}

Parâmetros de solicitação para definir o desafio de autenticação

Quando o Amazon Cognito invoca sua função do Lambda, ele fornece os seguintes parâmetros:

userAttributes

Um ou mais pares de nome-valor que representam atributos de usuário.

userNotFound

Um booleano que é preenchido pelo Amazon Cognito quando PreventUserExistenceErrors é definido como ENABLED para o cliente de grupo de usuários. Um valor de true significa que o ID do usuário (nome de usuário, endereço de e-mail e outros detalhes) não correspondeu a nenhum usuário existente. Quando PreventUserExistenceErrors é definido como ENABLED, o serviço não informa a aplicação dos usuários inexistentes. Recomendamos que suas funções do Lambda mantenham a mesma experiência do usuário e contabilizem a latência. Dessa forma, o autor da chamada não consegue detectar comportamentos diferentes quando o usuário existe ou não existe.

sessão

Uma matriz de elementos ChallengeResult. Cada regra contém os seguintes elementos:

challengeName

Um dos seguintes tipos de desafio: CUSTOM_CHALLENGE, SRP_A, PASSWORD_VERIFIER, SMS_MFA, EMAIL_OTP, SOFTWARE_TOKEN_MFA, DEVICE_SRP_AUTH, DEVICE_PASSWORD_VERIFIER ou ADMIN_NO_SRP_AUTH.

Quando sua função define auth challenge emite um desafio PASSWORD_VERIFIER para um usuário que configurou a autenticação multifator, o Amazon Cognito prossegue com um desafio SMS_MFA, EMAIL_OTP ou SOFTWARE_TOKEN_MFA. Essas são as instruções para um código de autenticação multifator. Em sua função, inclua o tratamento de eventos de entrada de desafios SMS_MFA, EMAIL_OTP e SOFTWARE_TOKEN_MFA. Você não precisa invocar os desafios de MFA usando sua função de desafio define auth.

Importante

Quando sua função estiver determinando se um usuário fez a autenticação com êxito e você precisar emitir tokens para ele, sempre confira challengeName em sua função “define auth challenge” e garantir que corresponda ao valor esperado.

challengeResult

Defina como true se o usuário tiver concluído o desafio com êxito; do contrário, defina-o como false.

challengeMetadata

Seu nome para o desafio personalizado. Usado somente se challengeName for CUSTOM_CHALLENGE.

clientMetadata

Um ou mais pares de chave/valor que você pode fornecer como entrada personalizada para a função do Lambda especificada para o acionador definir desafio de autenticação. Para transmitir esses dados para sua função do Lambda, você pode usar o parâmetro ClientMetadata nas operações de API AdminRespondToAuthChallenge e RespondToAuthChallenge. A solicitação que invoca a função de definição de desafio de autenticação não inclui dados transmitidos no parâmetro ClientMetadata nas operações AdminInitiateAuth e InitiateAuth da API.

Parâmetros de resposta para definir o desafio de autenticação

Na resposta, você pode retornar o próximo estágio do processo de autenticação.

challengeName

Uma string que contém o nome do próximo desafio. Se você deseja apresentar um novo desafio ao seu usuário, especifique o nome do desafio aqui.

issueTokens

Se você determinar que o usuário concluiu os desafios de autenticação de forma adequada; defina-o como true. Se o usuário não cumprir os desafios devidamente, defina como false.

failAuthentication

Se quiser encerrar o processo de autenticação atual, defina-o como true. Para continuar o processo de autenticação atual, defina-o como false.

Exemplo de definição do desafio de autenticação

Este exemplo definirá uma série de desafios de autenticação e emitirá tokens somente se o usuário concluir todos os desafios com êxito.

Node.js

const handler = async (event) => {
  if (
    event.request.session.length === 1 &&
    event.request.session[0].challengeName === "SRP_A"
  ) {
    event.response.issueTokens = false;
    event.response.failAuthentication = false;
    event.response.challengeName = "PASSWORD_VERIFIER";
  } else if (
    event.request.session.length === 2 &&
    event.request.session[1].challengeName === "PASSWORD_VERIFIER" &&
    event.request.session[1].challengeResult === true
  ) {
    event.response.issueTokens = false;
    event.response.failAuthentication = false;
    event.response.challengeName = "CUSTOM_CHALLENGE";
  } else if (
    event.request.session.length === 3 &&
    event.request.session[2].challengeName === "CUSTOM_CHALLENGE" &&
    event.request.session[2].challengeResult === true
  ) {
    event.response.issueTokens = false;
    event.response.failAuthentication = false;
    event.response.challengeName = "CUSTOM_CHALLENGE";
  } else if (
    event.request.session.length === 4 &&
    event.request.session[3].challengeName === "CUSTOM_CHALLENGE" &&
    event.request.session[3].challengeResult === true
  ) {
    event.response.issueTokens = true;
    event.response.failAuthentication = false;
  } else {
    event.response.issueTokens = false;
    event.response.failAuthentication = true;
  }

  return event;
};

export { handler };