自訂 SMS 寄件者 Lambda 觸發程序

若您將自訂簡訊寄件者觸發程序指派至使用者集區，Amazon Cognito 會在使用者事件要求傳送簡訊時，調用 Lambda 函數而非其預設行為。透過自訂寄件者觸發，您的 AWS Lambda 函數可以透過您選擇的方法和提供者傳送簡訊通知給使用者。您函數的自訂程式碼必須從您的使用者集區處理並傳遞所有簡訊。

此觸發程序適用於您可能想要更妥善控制使用者集區傳送簡訊方式的情況。您的 Lambda 函數可以自訂對 Amazon SNS API 操作的呼叫，例如當您想要管理多個起始 IDs 或跨 時 AWS 區域。您的函數也可能將訊息重新導向至另一個交付媒體或第三方服務。

若要了解如何設定自訂電子郵件寄件者觸發條件，請參閱 啟用自訂寄件者 Lambda 觸發條件。

自訂簡訊寄件者 Lambda 觸發程序來源

下表說明 Lambda 程式碼中自訂簡訊觸發程序來源的觸發事件。

TriggerSource value	事件
CustomSMSSender_SignUp	使用者註冊後，Amazon Cognito 會傳送歡迎訊息。
CustomSMSSender_ForgotPassword	使用者請求代碼以重置其密碼。
CustomSMSSender_ResendCode	使用者請求新的程式碼以確認其註冊。
CustomSMSSender_VerifyUserAttribute	使用者建立新的電子郵件地址或電話號碼屬性，Amazon Cognito 會傳送代碼來驗證屬性。
CustomSMSSender_UpdateUserAttribute	使用者更新電子郵件地址或電話號碼屬性，Amazon Cognito 會傳送代碼來驗證屬性。
CustomSMSSender_Authentication	使用 SMS 多重要素驗證 (MFA) 設定的使用者登入。
CustomSMSSender_AdminCreateUser	您可以在使用者集區中建立新使用者，Amazon Cognito 會將臨時密碼傳送給使用者。

自訂 SMS 寄件者 Lambda 觸發程序參數

Amazon Cognito 傳遞至此 Lambda 函數的請求，是以下參數和 Amazon Cognito 新增至所有請求的常用參數之組合。

JSON

{
    "request": {
        "type": "customSMSSenderRequestV1",
        "code": "string",
        "clientMetadata": {
            "string": "string",
             . . .
            },
        "userAttributes": {
            "string": "string",
            . . .
         }
}

自訂 SMS 寄件者請求參數

type

請求版本。對於自訂 SMS 寄件者事件，此字串的值一律為 customSMSSenderRequestV1。

code

您的函數可以解密並傳送給您使用者的加密代碼。

clientMetadata

您可以做為自訂 SMS 寄件者 Lambda 函數觸發程序的自訂輸入提供的一個或多個鍵值組。若要將此資料傳遞至您的 Lambda 函數，您可以使用 AdminRespondToAuthChallenge 和 RespondToAuthChallenge API 動作中的 ClientMetadata 參數。Amazon Cognito 不包含其傳遞至身分驗證後函數的請求中的 AdminInitiateAuth 和 InitiateAuth API 操作的 ClientMetadata 參數中的資料。

userAttributes

代表使用者屬性的一個或多個鍵值組。

自訂 SMS 寄件者回應參數

Amazon Cognito 不預期會在回應中收到任何其他傳回的資訊。您的函數可使用 API 操作來查詢和修改您的資源，或將事件中繼資料記錄到外部系統。

程式碼範例

下列 Node.js 範例處理您的自訂 SMS 寄件者 Lambda 函數中的 SMS 訊息事件。此範例假設您的函數定義了兩個環境變數。

KEY_ID

您要用來加密和解密使用者程式碼的 KMS 金鑰 ID。

KEY_ARN

您想要用來加密和解密使用者程式碼的 KMS 金鑰的 Amazon Resource Name (ARN)。

部署此函數

1. 在開發人員工作區中安裝最新版本的 NodeJS。

2. 在工作區中建立新的 NodeJS 專案。

3. 使用 初始化您的專案npm init -y。

4. 建立 Lambda 函數的指令碼：touch index.mjs。

5. 將下列範例的內容貼到 index.mjs。

6. 下載專案相依性 AWS Encryption SDK：npm install @aws-crypto/client-node。

7. 將專案目錄壓縮為檔案：zip -r my_deployment_package.zip .。

8. 將 ZIP 檔案部署到您的 函數。

import { KmsKeyringNode, buildClient, CommitmentPolicy } from '@aws-crypto/client-node';

// Configure the encryption SDK client with the KMS key from the environment variables
const { encrypt, decrypt } = buildClient(
    CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT
);

const generatorKeyId = process.env.KEY_ID;
const keyIds = [process.env.KEY_ARN];
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds });

// Example function to simulate sending SMS.
// This example logs message details to CloudWatch Logs from your Lambda function.
// Update this function with custom logic that sends an SMS message to 'phoneNumber' with body 'message'.
const sendSMS = async (phoneNumber, message) => {
    // Log the destination with the phone number masked.
    console.log(`Simulating SMS send to ${phoneNumber.replace(/[^+]/g, '*')}`);
    // Log the message with the code masked.
    console.log(`Message content: ${message.replace(/\b\d{6,8}\b/g, '********')}`);    
    // Simulate API delay
    await new Promise(resolve => setTimeout(resolve, 100));
    console.log('SMS sent successfully');
    return true;
};

export const handler = async (event) => {
    try {
        // Decrypt the secret code using encryption SDK
        let plainTextCode;
        if (event.request.code) {
            const { plaintext, messageHeader } = await decrypt(keyring, Buffer.from(event.request.code, 'base64'));
            plainTextCode = Buffer.from(plaintext).toString('utf-8');
        }

        // Handle different trigger sources
        if (event.triggerSource == 'CustomSMSSender_SignUp') {
            const phoneNumber = event.request.userAttributes.phone_number;
            const message = `Welcome! Your verification code is: ${plainTextCode}`;
            await sendSMS(phoneNumber, message);
        }
        else if (event.triggerSource == 'CustomSMSSender_ResendCode') {
            // Handle resend code
        }
        else if (event.triggerSource == 'CustomSMSSender_ForgotPassword') {
            // Handle forgot password
        }
        else if (event.triggerSource == 'CustomSMSSender_UpdateUserAttribute') {
            // Handle update attribute
        }
        else if (event.triggerSource == 'CustomSMSSender_VerifyUserAttribute') {
            // Handle verify attribute
        }
        else if (event.triggerSource == 'CustomSMSSender_AdminCreateUser') {
            // Handle admin create user
        }
        return;
    } catch (error) {
        console.error('Error in custom SMS sender:', error);
        throw error;
    }
};

使用自訂 SMS 寄件者函數評估 SMS 訊息功能

自訂 SMS 寄件者 Lambda 函數會接受您的使用者集區將傳送的 SMS 訊息，且該函數會根據您的自訂邏輯傳遞內容。Amazon Cognito 將 自訂 SMS 寄件者 Lambda 觸發程序參數 傳送到您的函數中。您的函數可以進行您想要使用此資訊做的事。例如，您可以將代碼傳送至 Amazon Simple Notification Service (Amazon SNS) 主題。Amazon SNS 主題訂閱者可以是 SMS 訊息、HTTPS 端點或電子郵件地址。

若要使用自訂 SMS 寄件者 Lambda 函數來測試 Amazon Cognito SMS 簡訊的測試環境，請參閱 GitHub 上的 aws-samples 程式庫中的 amazon-cognito-user-pool-development-and-testing-with-sms-redirected-to-email。儲存庫包含可建立新的使用者集區的 AWS CloudFormation 範本，或使用您已擁有的使用者集區。這些範本會建立 Lambda 函數和 Amazon SNS 主題。由範本指派為自訂 SMS 寄件者觸發程序的 Lambda 函數，會將您的 SMS 訊息重新導向至 Amazon SNS 主題的訂閱者。

當您將此解決方案部署到使用者集區時，對於 Amazon Cognito 通常透過 SMS 簡訊傳送的所有訊息，Lambda 函數會改為傳送到一個中央電子郵件地址。使用此解決方案可以自訂和預覽 SMS 訊息，並測試導致 Amazon Cognito 傳送 SMS 訊息的使用者集區事件。完成測試後，請復原 CloudFormation 堆疊，或從使用者集區中移除自訂 SMS 寄件者函數分配。

重要

請勿使用 amazon-cognito-user-pool-development-and-testing-with-sms-redirected-to-email 中的範本建置生產環境。解決方案中的自訂 SMS 寄件者 Lambda 函數會模擬 SMS 訊息，但 Lambda 函數會將它們全部傳送到一個中央電子郵件地址。您必須先完成在 Amazon Cognito 使用者集區的簡訊設定 顯示的需求，才能在實際產品的 Amazon Cognito 使用者集區中傳送 SMS 訊息。