사용자 정의 메시지 Lambda 트리거

Amazon Cognito는 이메일이나 전화 확인 메시지 또는 멀티 팩터 인증(MFA) 코드를 보내기 전에 이 트리거를 호출합니다. 사용자 지정 메시지 트리거를 사용하여 메시지를 동적으로 사용자 지정할 수 있습니다. 원래 Amazon Cognito 콘솔의 메시지 사용자 지정(Message customizations) 탭에서 정적 사용자 지정 메시지를 편집할 수 있습니다.

요청에는 codeParameter가 포함됩니다. 이는 Amazon Cognito가 사용자에게 전달하는 코드의 자리 표시자 역할을 하는 문자열입니다. codeParameter 문자열을 확인 코드가 나타날 메시지 본문에 삽입합니다. Amazon Cognito에서 응답을 수신하면 Amazon Cognito에서 codeParameter 문자열을 실제 확인 코드로 바꿉니다.

참고

CustomMessage_AdminCreateUser 트리거 소스가 있는 사용자 지정 메시지 Lambda 함수는 사용자 이름 및 확인 코드를 반환합니다. 관리자가 생성한 사용자는 사용자 이름과 코드를 모두 수신해야 하므로 함수로부터의 응답에는 request.usernameParameter와 request.codeParameter가 둘 다 포함되어야 합니다.

사용자 정의 메시지 Lambda 트리거 소스

triggerSource 값	Event
CustomMessage_SignUp	사용자 지정 메시지 – 가입 후 확인 코드 전송.
CustomMessage_AdminCreateUser	사용자 지정 메시지 – 새 사용자에게 임시 암호 전송.
CustomMessage_ResendCode	사용자 지정 메시지 – 기존 사용자에게 확인 코드 재전송.
CustomMessage_ForgotPassword	사용자 지정 메시지 – 암호 분실 요청을 위한 확인 코드 전송.
CustomMessage_UpdateUserAttribute	사용자 지정 메시지 – 사용자의 이메일 또는 전화 번호가 변경되면 이 트리거가 사용자에게 자동으로 확인 코드를 전송합니다. 다른 속성에는 사용할 수 없습니다.
CustomMessage_VerifyUserAttribute	사용자 지정 메시지 – 사용자가 새 이메일 또는 전화 번호에 대해 수동으로 요청하면 이 트리거가 사용자에게 확인 코드를 전송합니다.
CustomMessage_Authentication	사용자 지정 메시지 – 인증하는 동안 MFA 코드 전송.

사용자 정의 메시지 Lambda 트리거 파라미터

Amazon Cognito가 이 Lambda 함수에 전달하는 요청은 아래 파라미터와 Amazon Cognito가 모든 요청에 추가하는 공통 파라미터의 조합입니다.

JSON

{
    "request": {
        "userAttributes": {
            "string": "string",
            . . .
        }
        "codeParameter": "####",
        "usernameParameter": "string",
        "clientMetadata": {
            "string": "string",
            . . .
        }
    },
    "response": {
        "smsMessage": "string",
        "emailMessage": "string",
        "emailSubject": "string"
    }
}

사용자 정의 메시지 요청 파라미터

userAttributes

사용자 속성을 나타내는 하나 이상의 이름-값 페어입니다.

codeParameter

사용자 지정 메시지에서 확인 코드의 자리 표시자로 사용할 문자열입니다.

usernameParameter

사용자 이름. Amazon Cognito는 관리자가 생성한 사용자의 요청에 이 파라미터를 포함합니다.

clientMetadata

사용자 지정 메시지 트리거에 지정하는 Lambda 함수에 사용자 지정 입력으로 제공할 수 있는 하나 이상의 키-값 쌍입니다. 사용자 지정 메시지 함수를 호출하는 요청에는 ClientMetadata 매개변수로 전달된 AdminInitiateAuth데이터와 InitiateAuthAPI 작업이 포함되지 않습니다. 이 데이터를 Lambda 함수로 전달하려면 다음 API 작업에서 파라미터를 사용할 ClientMetadata 수 있습니다.

• AdminResetUserPassword

• AdminRespondToAuthChallenge

• AdminUpdateUserAttributes

• ForgotPassword

• GetUserAttributeVerificationCode

• ResendConfirmationCode

• SignUp

• UpdateUserAttributes

사용자 정의 메시지 응답 파라미터

응답에서는 사용자에게 보낼 메시지에 사용할 사용자 지정 텍스트를 지정합니다. Amazon Cognito가 이러한 파라미터에 적용하는 문자열 제약 조건은 을 참조하십시오. MessageTemplateType

smsMessage

사용자에게 보낼 사용자 지정 SMS 메시지입니다. 요청에서 수신한 codeParameter 값을 포함해야 합니다.

emailMessage

사용자에게 보낼 사용자 지정 이메일 메시지입니다. emailMessage 파라미터에서 HTML 서식을 사용할 수 있습니다. 요청에서 수신한 codeParameter 값을 변수 {####}으로 포함해야 합니다. Amazon Cognito는 사용자 풀의 EmailSendingAccount 속성이 DEVELOPER인 경우에만 emailMessage 파라미터를 사용할 수 있습니다. 사용자 풀의 EmailSendingAccount 속성이 DEVELOPER가 아니고 emailMessage 파라미터가 반환된 경우 Amazon Cognito에서 400오류 코드 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException을 생성합니다. Amazon Simple Email Service(Amazon SES)를 선택하여 이메일 메시지를 보내면 사용자 풀의 EmailSendingAccount 속성이 DEVELOPER입니다. 그렇지 않으면 이 값은 COGNITO_DEFAULT입니다.

emailSubject

사용자 지정 메시지의 제목 줄입니다. 사용자 풀의 EmailSendingAccount 속성이 다음과 같은 경우에만 emailSubject 파라미터를 사용할 수 있습니다. DEVELOPER 사용자 풀의 EmailSendingAccount 속성이 DEVELOPER가 아니고 Amazon Cognito에서 emailSubject 파라미터를 반환하는 경우 Amazon Cognito에서 400 오류 코드 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException을 생성합니다. Amazon Simple Email Service(Amazon SES)를 선택하여 이메일 메시지를 보내도록 선택하면 사용자 풀의 EmailSendingAccount 속성이 DEVELOPER입니다. 그렇지 않으면 이 값은 COGNITO_DEFAULT입니다.

가입용 사용자 지정 메시지의 예

이 Lambda 함수 예는 서비스에서 앱이 사용자에게 확인 코드를 보내야 할 때 이메일 또는 SMS 메시지를 사용자 지정합니다.

Amazon Cognito는 사후 등록, 확인 코드 재전송, 잊어버린 암호 복구 또는 사용자 속성 확인과 같은 여러 이벤트에서 Lambda 트리거를 호출할 수 있습니다. SMS와 이메일 모두의 메시지가 응답에 포함됩니다. 메시지에는 코드 파라미터 "####"이 포함되어야 합니다. 이 파라미터는 사용자가 수신하는 확인 코드의 자리 표시자입니다.

이메일 메시지의 최대 길이는 UTF-8 20,000자입니다. 이 길이에는 확인 코드가 포함됩니다. 이러한 이메일 메시지에 HTML 태그를 사용할 수 있습니다.

SMS 메시지의 최대 길이는 UTF-8 140자입니다. 이 길이에는 확인 코드가 포함됩니다.

Node.js

const handler = async (event) => {
  if (event.triggerSource === "CustomMessage_SignUp") {
    const message = `Thank you for signing up. Your confirmation code is ${event.request.codeParameter}.`;
    event.response.smsMessage = message;
    event.response.emailMessage = message;
    event.response.emailSubject = "Welcome to the service.";
  }
  return event;
};

export { handler };

Amazon Cognito는 이벤트 정보를 Lambda 함수에 전달합니다. 그런 다음 함수는 응답이 변경되면 동일한 이벤트 객체를 Amazon Cognito에 반환합니다. Lambda 콘솔에서 해당 Lambda 트리거와 관련 있는 데이터로 테스트 이벤트를 설정할 수 있습니다. 다음은 이 코드 샘플의 테스트 이벤트입니다.

JSON

{
  "version": 1,
  "triggerSource": "CustomMessage_SignUp/CustomMessage_ResendCode/CustomMessage_ForgotPassword/CustomMessage_VerifyUserAttribute",
  "region": "<region>",
  "userPoolId": "<userPoolId>",
  "userName": "<userName>",
  "callerContext": {
      "awsSdk": "<calling aws sdk with version>",
      "clientId": "<apps client id>",
      ...
  },
  "request": {
      "userAttributes": {
          "phone_number_verified": false,
          "email_verified": true,
           ...
      },
      "codeParameter": "####"
  },
  "response": {
      "smsMessage": "<custom message to be sent in the message with code parameter>"
      "emailMessage": "<custom message to be sent in the message with code parameter>"
      "emailSubject": "<custom email subject>"
  }
}

관리자로 사용자 생성용 사용자 정의 메시지 예제

Amazon Cognito가 이 예제 사용자 지정 메시지 Lambda 함수에 전송한 요청에는 triggerSource 값, 사용자 이름 CustomMessage_AdminCreateUser 및 임시 비밀번호가 있습니다. 함수는 ${event.request.codeParameter} 요청의 임시 비밀번호와 요청의 사용자 이름으로 채워집니다. ${event.request.usernameParameter}

사용자 지정 메시지는 응답 개체에 codeParameter 및 usernameParameter 응답 개체에 값을 삽입해야 합니다. smsMessage emailMessage 이 예제에서 함수는 응답 필드 event.response.smsMessage 및 에 동일한 메시지를 씁니다event.response.emailMessage.

이메일 메시지의 최대 길이는 UTF-8 20,000자입니다. 이 길이에는 확인 코드가 포함됩니다. 이러한 이메일에 HTML 태그를 사용할 수 있습니다. SMS 메시지의 최대 길이는 UTF-8 140자입니다. 이 길이에는 확인 코드가 포함됩니다.

SMS와 이메일 모두의 메시지가 응답에 포함됩니다.

Node.js

const handler = async (event) => {
  if (event.triggerSource === "CustomMessage_AdminCreateUser") {
    const message = `Welcome to the service. Your user name is ${event.request.usernameParameter}. Your temporary password is ${event.request.codeParameter}`;
    event.response.smsMessage = message;
    event.response.emailMessage = message;
    event.response.emailSubject = "Welcome to the service";
  }
  return event;
};

export { handler }

Amazon Cognito는 이벤트 정보를 Lambda 함수에 전달합니다. 그런 다음 함수는 응답이 변경되면 동일한 이벤트 객체를 Amazon Cognito에 반환합니다. Lambda 콘솔에서 해당 Lambda 트리거와 관련 있는 데이터로 테스트 이벤트를 설정할 수 있습니다. 다음은 이 코드 샘플의 테스트 이벤트입니다.

JSON

{
  "version": 1,
  "triggerSource": "CustomMessage_AdminCreateUser",
  "region": "<region>",
  "userPoolId": "<userPoolId>",
  "userName": "<userName>",
  "callerContext": {
      "awsSdk": "<calling aws sdk with version>",
      "clientId": "<apps client id>",
      ...
  },
  "request": {
      "userAttributes": {
          "phone_number_verified": false,
          "email_verified": true,
           ...
      },
      "codeParameter": "####",
      "usernameParameter": "username"
  },
  "response": {
      "smsMessage": "<custom message to be sent in the message with code parameter and username parameter>"
      "emailMessage": "<custom message to be sent in the message with code parameter and username parameter>"
      "emailSubject": "<custom email subject>"
  }
}