Parámetros de desencadenador de Lambda para remitente de SMS personalizado Activación del desencadenador de Lambda para remitente de SMS personalizado Ejemplo de código Evaluar las capacidades de los mensajes SMS con una función de remitente de SMS personalizado Fuentes del desencadenador para remitentes personalizados de SMS

Desencadenador de Lambda para remitentes personalizados de SMS

Al asignar un desencadenador de envío de SMS personalizado al grupo de usuarios, Amazon Cognito invoca una función de Lambda en lugar de su comportamiento predeterminado cuando un evento de usuario requiere que envíe un mensaje SMS. Con un activador de remitente personalizado, tu AWS Lambda función puede enviar notificaciones por SMS a tus usuarios a través del método y el proveedor que elijas. El código personalizado de la función debe procesar y entregar todos los mensajes SMS del grupo de usuarios.

nota

Actualmente, no puede asignar desencadenadores de remitente personalizados en la consola de Amazon Cognito. Puede asignar un desencadenador con el parámetro LambdaConfig en una solicitud de API CreateUserPool o UpdateUserPool.

Para usar este desencadenador, siga estos pasos:

Crea una clave de cifrado simétrica en AWS Key Management Service (AWS KMS). Amazon Cognito genera secretos (contraseñas temporales, códigos de verificación y confirmación) y después utiliza esta clave KMS para cifrarlos. A continuación, puede usar la operación de la API Descifrar en la función de Lambda para descifrar los secretos y enviarlos al usuario como texto sin formato. AWS Encryption SDKEs una herramienta útil para AWS KMS las operaciones de su función.
Cree una función de Lambda que desee asignar como desencadenador de remitente personalizado. Conceda permisos kms:Decrypt para la clave KMS al rol de la función de Lambda.
Conceda el acceso cognito-idp.amazonaws.com a la entidad principal del servicio de Amazon Cognito para llamar a la función de Lambda.
Escriba el código de función de Lambda que dirige sus mensajes a métodos de entrega personalizados o proveedores externos. Para entregar el código de verificación o confirmación del usuario, Base64 descodifica y descifra el valor del parámetro code de la solicitud. Esta operación genera un código o contraseña en texto plano que debe incluir en el mensaje.

Actualice el grupo de usuarios para que utilice un desencadenador Lambda de remitente personalizado. La entidad principal de IAM que actualiza o crea un grupo de usuarios con un desencadenador de remitente personalizado debe tener permiso para crear una concesión para la clave de KMS. El fragmento de LambdaConfig siguiente asigna funciones personalizadas de envío de SMS y correo electrónico.


"LambdaConfig": {
   "KMSKeyID": "arn:aws:kms:us-east-1:123456789012:key/a6c4f8e2-0c45-47db-925f-87854bc9e357",
   "CustomEmailSender": {
      "LambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:MyFunction",
      "LambdaVersion": "V1_0"
   },
   "CustomSMSSender": {
      "LambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:MyFunction",
      "LambdaVersion": "V1_0"
   }

Parámetros de desencadenador de Lambda para remitente de SMS personalizado

La solicitud que Amazon Cognito envía a esta función de Lambda es una combinación de los parámetros que se indican a continuación y los parámetros comunes que Amazon Cognito agrega a todas las solicitudes.

Parámetros de solicitudes de remitente de SMS personalizado

type: La versión de la solicitud. Para un evento de remitente de SMS personalizado, el valor de esta cadena es siempre customSMSSenderRequestV1.
code: El código cifrado que su función puede descifrar y enviar al usuario.
clientMetadata: Uno o varios pares clave-valor que puede proporcionar como datos de entrada personalizados al desencadenador de la función de Lambda de remitente de SMS personalizado. Para pasar estos datos a la función Lambda, puede usar el ClientMetadata parámetro en las acciones AdminRespondToAuthChallengey de la RespondToAuthChallengeAPI. Amazon Cognito no incluye datos del ClientMetadata parámetro ni de las operaciones de InitiateAuthAPI en la solicitud que transfiere a la función de autenticación posterior. AdminInitiateAuth
userAttributes: Uno o varios pares clave-valor que representan atributos de usuario.

Parámetros de respuesta de remitente de SMS personalizado

Amazon Cognito no espera ninguna información de devolución adicional en la respuesta. La función puede utilizar operaciones de la API para consultar y modificar los recursos o registrar metadatos de eventos en un sistema externo.

Activación del desencadenador de Lambda para remitente de SMS personalizado

Puede configurar un desencadenador de remitente personalizado que utilice lógica personalizada para enviar mensajes SMS a su grupo de usuarios. En el procedimiento siguiente se asigna un desencadenador de SMS personalizado, un desencadenador de correo electrónico personalizado o ambos a su grupo de usuarios. Después de agregar su desencadenador de remitente de SMS personalizado, Amazon Cognito siempre envía los atributos de usuario, como el número de teléfono, y el código de un solo uso a su función de Lambda en lugar de enviar de forma predeterminada un mensaje SMS con Amazon Simple Notification Service.

importante

Amazon Cognito aplica códigos de escape HTML a caracteres reservados como < (<) y > (>) en la contraseña temporal de su usuario. Estos caracteres pueden aparecer en las contraseñas temporales que Amazon Cognito envía a su función de remitente de correo electrónico personalizado, pero no en los códigos de verificación temporales. Para enviar contraseñas temporales, su función de Lambda debe anular los códigos de escape de estos caracteres después de descifrar la contraseña y antes de enviar el mensaje a su usuario.

Cree una clave de cifrado en AWS KMS. Esta clave se utiliza para cifrar contraseñas temporales y códigos de autorización que genera Amazon Cognito. A continuación, puede descifrar estos secretos con la función de Lambda de remitente personalizado para enviarlos a su usuario como texto sin formato.

Conceda a la entidad principal cognito-idp.amazonaws.com del servicio Amazon Cognito acceso para cifrar códigos con la clave KMS.

Aplique la siguiente política basada en recursos a su clave KMS.


{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Principal": {
            "Service": "cognito-idp.amazonaws.com"
        },
        "Action": "kms:CreateGrant",
        "Resource": "arn:aws:kms:us-west-2:111222333444:key/1example-2222-3333-4444-999example",
        "Condition": {
            "StringEquals": {
                "aws:SourceAccount": "111222333444"
            },
            "ArnLike": {
                "aws:SourceArn": "arn:aws:cognito-idp:us-west-2:111222333444:userpool/us-east-1_EXAMPLE"
            }
        }
    }]
}

Cree una función de Lambda para el desencadenador de remitente personalizado. Amazon Cognito utiliza el SDK de cifrado de AWS para cifrar los secretos, las contraseñas temporales y los códigos que autorizan las solicitudes de API de sus usuarios.
1. Asigne un rol de IAM a su función de Lambda que tenga, como mínimo, permisos kms:Decrypt para la clave KMS.
Conceda el acceso cognito-idp.amazonaws.com a la entidad principal del servicio de Amazon Cognito para llamar a la función de Lambda.

El siguiente AWS CLI comando otorga permiso a Amazon Cognito para invocar la función Lambda:
```
        aws lambda add-permission --function-name lambda_arn --statement-id "CognitoLambdaInvokeAccess" --action lambda:InvokeFunction --principal cognito-idp.amazonaws.com
    
```
Elabore el código de su función de Lambda para enviar sus mensajes. Amazon Cognito se utiliza AWS Encryption SDK para cifrar los secretos antes de que Amazon Cognito los envíe al remitente personalizado, función Lambda. En su función, descifre el secreto y procese los metadatos pertinentes. A continuación, envíe el código, su propio mensaje personalizado y el número de teléfono de destino a la API personalizada que entrega el mensaje.
Añada el AWS Encryption SDK a su función Lambda. Para obtener más información, consulte Lenguajes de programación del SDK de cifrado de AWS. Complete los siguientes pasos para actualizar el paquete de Lambda.
1. Exporte su función de Lambda como un archivo .zip en la AWS Management Console.
2. Abra la función y añada la AWS Encryption SDK. Para obtener más información y enlaces de descarga, consulte Lenguajes de programación de AWS Encryption SDK en la Guía para desarrolladores de AWS Encryption SDK .
3. Comprima su función con sus dependencias del SDK y cargue la función en Lambda. Para obtener más información, consulte Implementación de funciones de Lambda como archivos .zip en la Guía para desarrolladores de AWS Lambda .
Actualice el grupo de usuarios para agregar desencadenadores de Lambda de remitente personalizado. Incluya un parámetro CustomSMSSender o CustomEmailSender en una solicitud de API UpdateUserPool. La operación de API UpdateUserPool requiere todos los parámetros de su grupo de usuarios y los parámetros que desea modificar. Si no proporciona todos los parámetros relevantes, Amazon Cognito establece los valores de los parámetros que faltan en sus valores predeterminados. Como se demuestra en el ejemplo siguiente, incluya entradas para todas las funciones de Lambda que desee agregar o mantener en su grupo de usuarios. Para obtener más información, consulte Actualización de la configuración del grupo de usuarios.
```
    #Send this parameter in an 'aws cognito-idp update-user-pool' CLI command, including any existing 
    #user pool configurations.
              
      --lambda-config "PreSignUp=lambda-arn, \
                       CustomSMSSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \
                       CustomEmailSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \
                       KMSKeyID=key-id"        
 
```

Para eliminar un disparador Lambda de remitente personalizado con un update-user-pool AWS CLI, omita el CustomEmailSender parámetro CustomSMSSender o e incluya todos los demás activadores que desee usar con su grupo de usuarios. --lambda-config

Para eliminar un desencadenador de Lambda de remitente personalizado con una solicitud de API UpdateUserPool, omita el parámetro CustomSMSSender o CustomEmailSender del cuerpo de la solicitud que contiene el resto de la configuración del grupo de usuarios.

Ejemplo de código

En el siguiente ejemplo de Node.js se procesa un evento de mensaje SMS en la función de Lambda de remitente de SMS personalizado. En este ejemplo se supone que la función tiene dos variables de entorno definidas.

KEY_ALIAS: El alias de la clave de KMS que desea utilizar para cifrar y descifrar los códigos de sus usuarios.
KEY_ARN: El nombre de recurso de Amazon (ARN) de la clave de KMS que desea utilizar para cifrar y descifrar los códigos de sus usuarios.


const AWS = require('aws-sdk');
const b64 = require('base64-js');
const encryptionSdk = require('@aws-crypto/client-node');
//Configure the encryption SDK client with the KMS key from the environment variables.  
const { encrypt, decrypt } = encryptionSdk.buildClient(encryptionSdk.CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT);
const generatorKeyId = process.env.KEY_ALIAS;
const keyIds = [ process.env.KEY_ARN ];
const keyring = new encryptionSdk.KmsKeyringNode({ generatorKeyId, keyIds })
exports.handler = async (event) => {
	//Decrypt the secret code using encryption SDK.
	let plainTextCode;
	if(event.request.code){
		const { plaintext, messageHeader } = await decrypt(keyring, b64.toByteArray(event.request.code));
		plainTextCode = plaintext
	}
	//PlainTextCode now contains the decrypted secret.
	if(event.triggerSource == 'CustomSMSSender_SignUp'){
		//Send an SMS message to your user via a custom provider.
		//Include the temporary password in the message.
	}
	else if(event.triggerSource == 'CustomSMSSender_ResendCode'){
	}
	else if(event.triggerSource == 'CustomSMSSender_ForgotPassword'){
	}
	else if(event.triggerSource == 'CustomSMSSender_UpdateUserAttribute'){
	}
	else if(event.triggerSource == 'CustomSMSSender_VerifyUserAttribute'){
	}
	else if(event.triggerSource == 'CustomSMSSender_AdminCreateUser'){
	}
	else if(event.triggerSource == 'CustomSMSSender_AccountTakeOverNotification'){
	}
	return;
};

Temas

Evaluar las capacidades de los mensajes SMS con una función de remitente de SMS personalizado
Fuentes del desencadenador de Lambda para remitentes personalizados de SMS

Evaluar las capacidades de los mensajes SMS con una función de remitente de SMS personalizado

La función Lambda de remitente de SMS personalizado acepta los mensajes SMS que enviaría el grupo de usuarios y la función entrega el contenido según su lógica personalizada. Amazon Cognito envía el Parámetros de desencadenador de Lambda para remitente de SMS personalizado a su función. Su función puede hacer lo que desee con esta información. Por ejemplo, puede enviar el código a un tema de Amazon Simple Notification Service (Amazon SNS). Un suscriptor de temas de Amazon SNS puede ser un mensaje SMS, un punto de conexión HTTPS o una dirección de correo electrónico.

Para crear un entorno de prueba para la mensajería SMS de Amazon Cognito con una función Lambda de remitente de SMS personalizada, consulte amazon-cognito-user-pool- development-and-testing-with - sms-redirected-to-email en la biblioteca aws-samples de. GitHub El repositorio contiene AWS CloudFormation plantillas que pueden crear un nuevo grupo de usuarios o funcionar con un grupo de usuarios del que ya disponga. Estas plantillas crean funciones de Lambda y un tema de Amazon SNS. La función de Lambda que la plantilla asigna como desencadenador de remitente SMS personalizado, redirige los mensajes SMS a los suscriptores al tema de Amazon SNS.

Cuando implementa esta solución en un grupo de usuarios, todos los mensajes que Amazon Cognito suele enviar a través de mensajería SMS, la función de Lambda los envía en su lugar a una dirección de correo electrónico central. Utilice esta solución para personalizar y obtener una vista previa de los mensajes SMS y para probar los eventos del grupo de usuarios que hacen que Amazon Cognito envíe un mensaje SMS. Tras completar las pruebas, revierta la CloudFormation pila o elimine la asignación de funciones de envío de SMS personalizada de su grupo de usuarios.

importante

No utilice las plantillas de amazon-cognito-user-pool- development-and-testing-with - sms-redirected-to-email para crear un entorno de producción. La función de Lambda del remitente de SMS personalizado en la solución simula mensajes SMS, pero la función de Lambda los envía a una sola dirección de correo electrónico central. Para poder enviar mensajes SMS en un grupo de usuarios de Amazon Cognito de producción, debe completar los requisitos que se muestran en Configuración de mensajes SMS para grupos de usuarios de Amazon Cognito.

Fuentes del desencadenador de Lambda para remitentes personalizados de SMS

En la siguiente tabla, se muestra el evento desencadenante de las fuentes del desencadenador de SMS personalizado en el código de Lambda.

`TriggerSource value`	Evento
`CustomSMSSender_SignUp`	Un usuario se registra y Amazon Cognito envía un mensaje de bienvenida.
`CustomSMSSender_ForgotPassword`	Un usuario solicita un código para restablecer su contraseña.
`CustomSMSSender_ResendCode`	Un usuario solicita un código nuevo para confirmar su registro.
`CustomSMSSender_VerifyUserAttribute`	Un usuario crea una dirección de correo electrónico nueva o un atributo de número de teléfono y Amazon Cognito envía un código para verificar el atributo.
`CustomSMSSender_UpdateUserAttribute`	Un usuario actualiza una dirección de correo electrónico o un atributo de número de teléfono y Amazon Cognito envía un código para verificar el atributo.
`CustomSMSSender_Authentication`	Un usuario configurado con autenticación multifactor (MFA) por SMS inicia sesión.
`CustomSMSSender_AdminCreateUser`	Crea un nuevo usuario en su grupo de usuarios y Amazon Cognito le envía una contraseña temporal.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Desencadenador de Lambda para remitentes de correos electrónicos personalizados

Uso del análisis de Amazon Pinpoint