本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 身分驗證前 Lambda 觸發程序
<a name="user-pool-lambda-pre-authentication"></a>

Amazon Cognito 會在使用者嘗試登入時叫用此觸發程序，因此您可以建立自訂驗證來執行預先準備的動作。例如，您可以拒絕身分驗證請求，或將工作階段資料記錄到外部系統。

**注意**  
除非使用者集區應用程式用戶端`PreventUserExistenceErrors`的設定設為 ，否則當使用者不存在時，此 Lambda 觸發不會啟用`ENABLED`。現有身分驗證工作階段的續約也不會啟用此觸發。

**Topics**
+ [流程概觀](#user-pool-lambda-pre-authentication-1)
+ [身分驗證前 Lambda 觸發程序參數](#cognito-user-pools-lambda-trigger-syntax-pre-auth)
+ [身分驗證前範例](#aws-lambda-triggers-pre-authentication-example)

## 流程概觀
<a name="user-pool-lambda-pre-authentication-1"></a>

![\[註冊前身分驗證 Lambda 觸發程序 – 用戶端流程\]](http://docs.aws.amazon.com/zh_tw/cognito/latest/developerguide/images/lambda-pre-authentication-1.png)


此請求包括來自應用程式傳遞至使用者集區 `InitiateAuth` 和 `AdminInitiateAuth` API 操作的 `ClientMetadata` 值的用戶端驗證資料。

如需詳細資訊，請參閱[範例身分驗證工作階段](authentication.md#amazon-cognito-user-pools-authentication-flow)。

## 身分驗證前 Lambda 觸發程序參數
<a name="cognito-user-pools-lambda-trigger-syntax-pre-auth"></a>

Amazon Cognito 傳遞至此 Lambda 函數的請求，是以下參數和 Amazon Cognito 新增至所有請求的[常用參數](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.html#cognito-user-pools-lambda-trigger-syntax-shared)之組合。

------
#### [ JSON ]

```
{
    "request": {
        "userAttributes": {
            "string": "string",
            . . .
        },
        "validationData": {
            "string": "string",
            . . .
        },
        "userNotFound": boolean
    },
    "response": {}
}
```

------

### 身分驗證前請求參數
<a name="cognito-user-pools-lambda-trigger-syntax-pre-auth-request"></a>

**userAttributes**  
代表使用者屬性的一或多組名稱/值。

**userNotFound**  
當您將使用者集區的 `PreventUserExistenceErrors` 設定為 `ENABLED` 時，Amazon Cognito 會填入此布林值。

**validationData**  
一或多個鍵值組，包含使用者登入請求中的驗證資料。若要將此資料傳遞至您的 Lambda 函數，您可以使用 [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) 和 [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) API 動作中的 ClientMetadata 參數。

### 身分驗證前回應參數
<a name="cognito-user-pools-lambda-trigger-syntax-pre-auth-response"></a>

Amazon Cognito 不會處理函數在回應中傳回的任何新增資訊。您的函數可傳回錯誤以拒絕登入嘗試，或者使用 API 操作以查詢和修改您的資源。

## 身分驗證前範例
<a name="aws-lambda-triggers-pre-authentication-example"></a>

此範例函數可防止使用者使用特定的應用程式用戶端登入您的使用者集區。由於預先驗證 Lambda 函數在使用者具有現有工作階段時不會叫用，因此該函數只會防止您要封鎖的應用程式用戶端 ID 展開新的工作階段。

------
#### [ Node.js ]

```
const handler = async (event) => {
  if (
    event.callerContext.clientId === "user-pool-app-client-id-to-be-blocked"
  ) {
    throw new Error("Cannot authenticate users from this user pool app client");
  }

  return event;
};

export { handler };
```

------
#### [ Python ]

```
def lambda_handler(event, context):
    if event['callerContext']['clientId'] == "<user pool app client id to be blocked>":
        raise Exception("Cannot authenticate users from this user pool app client")

    # Return to Amazon Cognito
    return event
```

------

Amazon Cognito 會將事件資訊傳遞至您的 Lambda 函數。此函數會將相同事件物件傳回 Amazon Cognito，並在回應中附上任何變更。在 Lambda 主控台中，您可使用與 Lambda 觸發程序相關聯的資料來設定測試事件。下列是此程式碼範例的測試事件：

------
#### [ JSON ]

```
{
    "callerContext": {
        "clientId": "<user pool app client id to be blocked>"
    },
    "response": {}
}
```

------