翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# トークン生成前の Lambda トリガー
Amazon Cognito は、このトリガーをトークンの生成前に呼び出すため、ユーザープールトークンのクレームをカスタマイズできます。バージョン 1 または `V1_0` のトークン生成前トリガーイベントの**基本機能**を使用して、アイデンティティ (ID) トークンをカスタマイズできます。エッセンシャル機能プランまたはプラス機能プランを使用するユーザープールでは、Machine to Machine (M2M) クライアント認証情報の付与で、アクセストークンのカスタマイズを伴うバージョン 2 (`V2_0`) トリガーイベントと、アクセストークンのカスタマイズを伴うバージョン 3 (`V3_0`) トリガーイベントを生成できます。
Amazon Cognito は、ID トークンに書き込むデータが含まれているリクエストとして `V1_0` イベントを関数に送信します。`V2_0` イベントまたは `V3_0` イベントは、Amazon Cognito が ID トークンとアクセストークンの両方に書き込むデータが含まれている単一のリクエストです。両方のトークンをカスタマイズするには、トリガーバージョン 2 または 3 を使用するように関数を更新し、両方のトークンのデータを同じレスポンスで送信する必要があります。
Amazon Cognito は、バージョン 2 のイベントレスポンスを、ユーザー認証 (ユーザー自らユーザープールに提示した認証情報) からのアクセストークンに適用します。バージョン 3 のイベントレスポンスは、ユーザー認証とマシン認証からのアクセストークンに適用されます。マシン認証では、自動化されたシステムが、アプリケーションクライアントシークレットを使用してアクセストークンリクエストを承認します。結果のアクセストークンの状況を除いて、バージョン 2 と 3 のイベントは同じです。
この Lambda トリガーでは、Amazon Cognito がアプリケーションに発行する前の ID トークンとアクセストークンの一部のクレームを追加、削除、変更できます。この機能を使用するには、Amazon Cognito ユーザープールコンソールから Lambda 関数を関連付けるか、 AWS Command Line Interface (AWS CLI) でユーザープール `LambdaConfig` を更新します。
## イベントバージョン
ユーザープールは、トークン生成前トリガーイベントのさまざまなバージョンを Lambda 関数に配信できます。`V1_0` トリガーは、ID トークンを変更するためのパラメータを配信します。`V2_0` または `V3_0` トリガーは、以下のパラメータを提供します。
1. `V1_0` トリガーの関数。
1. アクセストークンをカスタマイズする機能。
1. 複雑なデータ型を ID に渡し、次のトークンクレーム値にアクセスする機能。
+ String
+ Number
+ ブール値
+ 文字列、数値、ブール値、またはこれらの組み合わせの配列
+ JSON
**注記**
ID トークンでは、`phone_number_verified`、`email_verified`、`updated_at` および `address` を除くクレームの値に複雑なオブジェクトを入力できます。
ユーザープールはデフォルトで `V1_0` イベントを配信します。`V2_0` イベントを送信するようにユーザープールを設定するには、Amazon Cognito コンソールでトリガーを設定するときに、**[トリガーイベントバージョン]** として **[基本機能 \$1 ユーザー ID のアクセストークンのカスタマイズ]** を選択します。`V3_0` イベントを生成するには、****[基本機能 \$1 ユーザー ID とマシン ID のアクセストークンのカスタマイズ]**** を選択します。[UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) API リクエストまたは [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) API リクエストの [LambdaConfig](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html#CognitoUserPools-UpdateUserPool-request-LambdaConfig) パラメータで `LambdaVersion` の値を設定することもできます。イベントバージョン 1、2、3 は、**エッセンシャル**機能プランと**プラス**機能プランで利用できます。バージョン 3 イベントの M2M オペレーションには、月間アクティブユーザー (MAU) の計算式とは別の料金体系があります。詳細については、「[Amazon Cognito の料金](https://aws.amazon.com/cognito/pricing/)」を参照してください。
**注記**
ユーザープールが 2024 年 11 月 22 日 18:00 GMT 以前に **[高度なセキュリティ機能]** オプションを使用して動作し、**ライト**機能階層に残っている場合は、トークン生成前トリガーのイベントバージョン 1 と 2 にアクセスできます。このレガシー階層のユーザープールで高度なセキュリティ機能を有効にして*いない*場合は、イベントバージョン 1 にアクセスできます。バージョン 3 は、エッセンシャルとプラスで*のみ*利用できます。
## クレームとスコープのリファレンス
Amazon Cognito は、アクセストークンと ID トークンに対して追加、変更、または抑制できるクレームとスコープを制限します。次の表は、Lambda 関数で変更できるクレームと変更できないクレーム、およびクレームの存在や値に影響するトリガーイベントパラメータを示しています。
| Claim | デフォルトのトークンタイプ | 追加可能? | 変更可能? | 抑制可能? | イベントパラメータ - 追加または変更 | イベントパラメータ - 抑制 | ID のタイプ | イベントバージョン |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| ユーザープールのトークンスキーマにないクレーム | なし | はい | はい | 該当なし | claimsToAddOrOverride | claimsToSuppress | ユーザー、マシン[1](#cognito-pretoken-machine-ids-tier-note) | すべて[2](#cognito-pretoken-id-access-versions-note) |
| scope | アクセス | はい | はい | はい | scopesToAdd | scopesToSuppress | ユーザー、マシン[1](#cognito-pretoken-machine-ids-tier-note) | v2\$10, v3\$10 |
| cognito:groups | ID、アクセス | はい | はい | はい | groupsToOverride | claimsToSuppress | ユーザー | すべて[2](#cognito-pretoken-id-access-versions-note) |
| cognito:preferred\$1role | ID | はい | はい | はい | preferredRole | claimsToSuppress[3](#cognito-pretoken-suppress-groups-note) | ユーザー | すべて |
| cognito:roles | ID | はい | はい | はい | iamRolesToOverride | claimsToSuppress[3](#cognito-pretoken-suppress-groups-note) | ユーザー | すべて |
| cognito:username | ID | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー | 該当なし |
| cognito: プレフィックスが付いたその他のクレーム | なし | いいえ | なし | いいえ | 該当なし | 該当なし | 該当なし | 該当なし |
| username | アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー | v2\$10, v3\$10 |
| sub | ID、アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー | 該当なし |
| 標準 OIDC 属性 | ID | はい | はい | はい | claimsToAddOrOverride | claimsToSuppress | ユーザー | すべて |
| custom: 属性 | ID | はい | はい | はい | claimsToAddOrOverride | claimsToSuppress | ユーザー | すべて |
| dev: 属性 | ID | いいえ | なし | はい | 該当なし | claimsToSuppress | ユーザー | すべて |
| identities | ID | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー | 該当なし |
| aud[4](#cognito-pretoken-aud-note) | ID | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| client\$1id | アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| event\$1id | アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| device\$1key | アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー | 該当なし |
| version | アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| acr | ID、アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| amr | ID、アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| at\$1hash | ID | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| auth\$1time | ID、アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| azp | ID、アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| exp | ID、アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| iat | ID、アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| iss | ID、アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| jti | ID、アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| nbf | ID、アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| nonce | ID、アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| origin\$1jti | ID、アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
| token\$1use | ID、アクセス | いいえ | なし | いいえ | 該当なし | 該当なし | ユーザー、マシン | 該当なし |
1 マシン ID のアクセストークンは、トリガー入力イベントの `v3_0` でのみ使用できます。イベントバージョン 3 は、**エッセンシャル**機能階層と**プラス**機能階層でのみ使用できます。**ライト**階層のユーザープールは `v1_0` イベントを受信できます。高度なセキュリティ機能を備えた、**ライト**階層のユーザープールは、`v1_0` イベントと `v2_0` イベントを受信できます。
2 トークン生成前トリガーを、`v1_0` イベントバージョン (ID トークンのみ)、`v2_0` イベントバージョン (ID トークンとアクセストークン)、`v3_0` イベントバージョン ( ID トークンとアクセストークン、さらにマシン ID の機能) に設定します。
3 `cognito:preferred_role` クレームと `cognito:roles` クレームを抑制するには、`cognito:groups` を `claimsToSuppress` に追加します。
4 `aud` クレームをアクセストークンに追加することはできますが、その値は現在のセッションのアプリケーションクライアント ID と一致する必要があります。リクエストイベントのクライアント ID は、`event.callerContext.clientId` から取得できます。
## ID トークンのカスタマイズ
トークン生成前 Lambda トリガーのすべてのイベントバージョンでは、ユーザープールのアイデンティティ (ID) トークンの内容をカスタマイズできます。ID トークンは、ウェブまたはモバイルアプリにサインインするためのユーザー属性を、信頼できる ID ソースから提供します。ID トークンの詳細については、「[ID トークンの理解](amazon-cognito-user-pools-using-the-id-token.md)」を参照してください。
トークン生成前の Lambda トリガーでは、ID トークンを使用して以下のような操作を行います。
+ ユーザーがアイデンティティプールにリクエストした IAM ロールをランタイムに変更します。
+ 外部ソースからユーザー属性を追加します。
+ 既存のユーザー属性値を追加または置換します。
+ アプリに渡されるはずのユーザー属性が、ユーザーの許可されたスコープや、アプリクライアントに付与した属性の読み取りアクセス権により開示されることを抑制します。
## アクセストークンのカスタマイズ
トークン生成前 Lambda トリガーのイベントバージョン 2 および 3 を使用すると、ユーザープールのアクセストークンの内容をカスタマイズできます。アクセストークンは、Amazon Cognito トークン認可 API オペレーションやサードパーティ API などのアクセス保護されたリソースから情報を取得することをユーザーに許可します。クライアント認証情報の付与による Machine to Machine (M2M) 認証の場合、Amazon Cognito は、ユーザープールがバージョン 3 (`V3_0`) イベント用に設定されている場合にのみ、トークン生成前トリガーを呼び出します。アクセストークンの詳細については、「[アクセストークンの理解](amazon-cognito-user-pools-using-the-access-token.md)」を参照してください。
トークン生成前の Lambda トリガーでは、アクセストークンを使用して以下のような操作を行います。
+ `scope` クレーム内のスコープを追加または抑制します。例えば、スコープ `aws.cognito.signin.user.admin` のみを割り当てる Amazon Cognito ユーザープール API 認証で生成されたアクセストークンにスコープを追加できます。
+ ユーザープールグループのユーザーのメンバーシップを変更します。
+ Amazon Cognito アクセストークンにまだ存在していないクレームを追加します。
+ アプリに渡されるはずのクレームの開示を抑制します。
ユーザープールでのアクセスのカスタマイズをサポートするには、トリガーリクエストの更新バージョンを生成するようにユーザープールを設定する必要があります。ユーザープールを更新するには、次の手順に従います。
------
#### [ AWS マネジメントコンソール ]
**トークン生成前の Lambda トリガーでアクセストークンのカスタマイズをサポートするには**
1. [Amazon Cognito コンソール](https://console.aws.amazon.com/cognito/home)に移動し、**[ユーザープール]** を選択します。
1. リストから既存のユーザープールを選択するか、[ユーザープールを作成](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html)します。
1. **[拡張機能]** メニューを選択し、**[Lambda トリガー]** を見つけます。
1. **トークン生成前トリガー**を追加または編集します。
1. **[Lambda 関数を割り当てる]** で Lambda 関数を選択します。
1. **[トリガーイベントバージョン]** として、**[基本機能 \$1 ユーザー ID のアクセストークンのカスタマイズ]** または **[機能機能 \$1 ユーザー ID とマシン ID のアクセストークンのカスタマイズ]** を選択します。この設定により、Amazon Cognito が関数に送信するリクエストパラメータが更新され、アクセストークンをカスタマイズするためのフィールドが含まれるようになります。
------
#### [ User pools API ]
**トークン生成前の Lambda トリガーでアクセストークンのカスタマイズをサポートするには**
[CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) または [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) API リクエストを生成します。デフォルト値に設定しないすべてのパラメータには、値を指定する必要があります。詳細については、「[ユーザープールとアプリケーションクライアントの設定更新](cognito-user-pool-updating.md)」を参照してください。
リクエストの `LambdaVersion` パラメータに以下の内容を含めます。`LambdaVersion` の値が `V2_0` である場合、ユーザープールはアクセストークンのパラメータを追加し、アクセストークンに変更を適用します。`LambdaVersion` の値が `V3_0` である場合、`V2_0` と同じイベントが生成されますが、ユーザープールは M2M アクセストークンに*対しても*変更を適用します。特定の関数バージョンを呼び出すには、関数バージョンを `LambdaArn` の値とする Lambda 関数 ARN を使用します。
```
"PreTokenGenerationConfig": {
"LambdaArn": "arn:aws:lambda:us-west-2:123456789012:function:MyFunction",
"LambdaVersion": "V3_0"
},
```
------
**Machine to Machine (M2M) クライアント認証情報のクライアントメタデータ**
[クライアントメタデータ](cognito-user-pools-working-with-lambda-triggers.md#working-with-lambda-trigger-client-metadata)は M2M リクエストで渡すことができます。クライアントメタデータは、[トークン生成前の Lambda トリガー](#user-pool-lambda-pre-token-generation) の結果に役立つユーザーまたはアプリケーション環境からの追加情報です。ユーザープリンシパルによる認証オペレーションでは、[AdminRespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminRespondToAuthChallenge.html) API リクエストおよび [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html) API リクエストの本文で、クライアントメタデータをトークン生成前トリガーに渡すことができます。アプリケーションは、[トークンエンドポイント](token-endpoint.md)への直接リクエストを使用して M2M のアクセストークン生成フローを実行するため、異なるモデルとなります。クライアント認証情報のトークンリクエストの POST 本文で、クライアントメタデータオブジェクトを URL エンコード (`x-www-form-urlencoded`) した `aws_client_metadata` パラメータを文字列に渡します。リクエスト例については、「[基本認可によるクライアント認証情報POST 本文認可によるクライアント認証情報](token-endpoint.md#exchanging-client-credentials-for-an-access-token-in-request-body)」を参照してください。次に示すのは、キーと値のペア `{"environment": "dev", "language": "en-US"}` を渡すパラメータの例です。
```
aws_client_metadata=%7B%22environment%22%3A%20%22dev%22,%20%22language%22%3A%20%22en-US%22%7D
```
**その他のリソース**
+ [Amazon Cognito ユーザープールでアクセストークンをカスタマイズする方法](https://aws.amazon.com/blogs/security/how-to-customize-access-tokens-in-amazon-cognito-user-pools/)
**Topics**
+ [イベントバージョン](#user-pool-lambda-pre-token-generation-event-versions)
+ [クレームとスコープのリファレンス](#user-pool-lambda-pre-token-generation-excluded-claims)
+ [ID トークンのカスタマイズ](#user-pool-lambda-pre-token-generation-idtoken)
+ [アクセストークンのカスタマイズ](#user-pool-lambda-pre-token-generation-accesstoken)
+ [トークン生成前の Lambda トリガーのソース](#user-pool-lambda-pre-token-generation-trigger-source)
+ [トークン生成前の Lambda トリガーのパラメータ](#cognito-user-pools-lambda-trigger-syntax-pre-token-generation)
+ [トークン生成前トリガーイベントバージョン 2 の例:クレーム、スコープ、グループの追加と非表示](#aws-lambda-triggers-pre-token-generation-example-version-2-overview)
+ [トークン生成前イベントバージョン 2 の例: 複雑なオブジェクトでクレームを追加する](#aws-lambda-triggers-pre-token-generation-example-version-2-complex-objects)
+ [トークン生成前イベントバージョン 1 の例: 新しいクレームの追加と既存のクレームの非表示](#aws-lambda-triggers-pre-token-generation-version-1-add-claim)
+ [トークン生成前イベントバージョン 1 の例: ユーザーグループのメンバーシップの変更](#aws-lambda-triggers-pre-token-generation-version-1-change-group)
## トークン生成前の Lambda トリガーのソース
| triggerSource 値 | イベント |
| --- | --- |
| TokenGeneration\$1HostedAuth | Amazon Cognito マネージドログインのサインインページからの認証時に呼び出されます。 |
| TokenGeneration\$1Authentication | ユーザー認証フローが完了した後に呼び出されます。 |
| TokenGeneration\$1NewPasswordChallenge | 管理者によってユーザーが作成された後に呼び出されます。このフローは、ユーザーが一時パスワードを変更する必要があるときに呼び出されます。 |
| TokenGeneration\$1ClientCredentials | M2M クライアント認証情報の付与の後に呼び出されます。ユーザープールがこのイベントを送信するのは、イベントバージョンが V3\$10 の場合のみです。 |
| TokenGeneration\$1AuthenticateDevice | ユーザーデバイスの認証の終了時に呼び出されます。 |
| TokenGeneration\$1RefreshTokens | ユーザーが ID およびアクセスのトークンを更新しようとしたときに呼び出されます。 |
## トークン生成前の Lambda トリガーのパラメータ
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)を組み合わせたものです。トークン生成前の Lambda トリガーをユーザープールに追加するときに、トリガーバージョンを選択できます。このバージョンにより、Amazon Cognito がアクセストークンをカスタマイズするための追加パラメータを含むリクエストを Lambda 関数に渡すかどうかが決まります。
------
#### [ Version one ]
バージョン 1 のトークンは、ID トークン内のグループメンバーシップ、IAM ロール、新しいクレームを設定できます。グループメンバーシップのオーバーライドは、アクセストークンの `cognito:groups` クレームにも適用されます。
```
{
"request": {
"userAttributes": {"string": "string"},
"groupConfiguration": {
"groupsToOverride": [
"string",
"string"
],
"iamRolesToOverride": [
"string",
"string"
],
"preferredRole": "string"
},
"clientMetadata": {"string": "string"}
},
"response": {
"claimsOverrideDetails": {
"claimsToAddOrOverride": {"string": "string"},
"claimsToSuppress": [
"string",
"string"
],
"groupOverrideDetails": {
"groupsToOverride": [
"string",
"string"
],
"iamRolesToOverride": [
"string",
"string"
],
"preferredRole": "string"
}
}
}
}
```
------
#### [ Versions two and three ]
バージョン 2 および 3 のリクエストイベントは、アクセストークンをカスタマイズするフィールドを追加します。ユーザープールは、バージョン 3 のイベントの変更をマシン ID のアクセストークンに適用します。また、これらのバージョンは、レスポンスオブジェクトの複雑な `claimsToOverride` データ型のサポートも追加します。Lambda 関数は、次のタイプのデータを `claimsToOverride` の値で返すことができます。
+ String
+ Number
+ ブール値
+ 文字列、数値、ブール値、またはこれらの組み合わせの配列
+ JSON
```
{
"request": {
"userAttributes": {
"string": "string"
},
"scopes": ["string", "string"],
"groupConfiguration": {
"groupsToOverride": ["string", "string"],
"iamRolesToOverride": ["string", "string"],
"preferredRole": "string"
},
"clientMetadata": {
"string": "string"
}
},
"response": {
"claimsAndScopeOverrideDetails": {
"idTokenGeneration": {
"claimsToAddOrOverride": {
"string": [accepted datatype]
},
"claimsToSuppress": ["string", "string"]
},
"accessTokenGeneration": {
"claimsToAddOrOverride": {
"string": [accepted datatype]
},
"claimsToSuppress": ["string", "string"],
"scopesToAdd": ["string", "string"],
"scopesToSuppress": ["string", "string"]
},
"groupOverrideDetails": {
"groupsToOverride": ["string", "string"],
"iamRolesToOverride": ["string", "string"],
"preferredRole": "string"
}
}
}
}
```
------
### トークン生成前のリクエストパラメータ
| 名前 | 説明 | トリガーイベントの最小バージョン |
| --- |--- |--- |
| userAttributes | ユーザープール内のユーザープロファイルの属性。 | 1 |
| groupConfiguration | 現在のグループ設定を含む入力オブジェクト。このオブジェクトには、`groupsToOverride`、`iamRolesToOverride`、および `preferredRole` が含まれています。 | 1 |
| groupsToOverride | ユーザーがメンバーになっている[ユーザープールグループ](cognito-user-pools-user-groups.md#cognito-user-pools-user-groups.title)。 | 1 |
| iamRolesToOverride | ユーザープールグループを AWS Identity and Access Management (IAM) ロールに関連付けることができます。この要素は、ユーザーがメンバーになっているグループのすべての IAM ロールのリストです。 | 1 |
| preferredRole | ユーザープールグループには、[優先順位](cognito-user-pools-user-groups.md#assigning-precedence-values-to-groups.title)を設定できます。この要素には、`groupsToOverride` 要素内で優先順位が最も高いグループの IAM ロールの名前が含まれます。 | 1 |
| clientMetadata | トークン生成前のトリガーに指定する Lambda 関数へのカスタム入力として提供できる 1 つ、または複数のキー/値ペア。 このデータを Lambda 関数に渡すには、[AdminRespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminRespondToAuthChallenge.html) および [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html) API オペレーションで ClientMetadata パラメータを使用します。Amazon Cognito は、トークン生成前の関数に渡すリクエストの [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) および [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API オペレーションに `ClientMetadata` パラメータのデータを含めません。 | 1 |
| scopes | アクセストークンのスコープ。アクセストークンに含まれるスコープは、ユーザーがリクエストし、アプリクライアントに発行を許可したユーザープールの標準スコープとカスタムスコープです。 | 2 |
### トークン生成前のレスポンスパラメータ
| 名前 | 説明 | トリガーイベントの最小バージョン |
| --- |--- |--- |
| claimsOverrideDetails | A container for all elements in a V1\$10 trigger event. | 1 |
| claimsAndScopeOverrideDetails | `V2_0` または `V3_0` トリガーイベント内のすべての要素を格納するコンテナ。 | 2 |
| idTokenGeneration | ユーザーの ID トークンで上書き、追加、または抑制するクレーム。この ID トークンのカスタマイズ値の親は、バージョン 2 以降でのみ表示されますが、子要素はバージョン 1 のイベントでも表示されます。 | 2 |
| accessTokenGeneration | ユーザーのアクセストークンで上書き、追加、または抑制するクレームとスコープ。このアクセストークンのカスタマイズ値の親は、バージョン 2 以降のイベントでのみ表示されます。 | 2 |
| claimsToAddOrOverride | 追加または変更する 1 つ以上のクレームとその値のマップ。グループ関連のクレームには、代わりに `groupOverrideDetails` を使用します。 イベントバージョン 2 以降の場合、この要素は `accessTokenGeneration` と `idTokenGeneration` の両方の下に表示されます。 | 1[*](#cognito-pretoken-complex-objects-note) |
| claimsToSuppress | Amazon Cognito で抑制するクレームのリスト。関数がクレーム値の非表示と置換の両方を行う場合、Amazon Cognito はクレームを非表示にします。 イベントバージョン 2 以降の場合、この要素は `accessTokenGeneration` と `idTokenGeneration` の両方の下に表示されます。 | 1 |
| groupOverrideDetails | 現在のグループ設定を含む出力オブジェクト。このオブジェクトには、`groupsToOverride`、`iamRolesToOverride`、および `preferredRole` が含まれています。 この関数は、`groupOverrideDetails` オブジェクトを、指定したオブジェクトに置き換えます。レスポンスで空または Null オブジェクトを返すと、Amazon Cognito はグループを非表示にします。既存のグループ設定を同じままにするには、リクエストの `groupConfiguration` オブジェクトの値をレスポンスの `groupOverrideDetails` オブジェクトにコピーします。その後、サービスに渡します。 Amazon Cognito ID とアクセストークンには、両方とも `cognito:groups` クレームが含まれています。`groupOverrideDetails` オブジェクトは、アクセストークンおよび ID トークンの `cognito:groups` クレームを置き換えます。バージョン 1 のイベントがアクセストークンを変更できるのは、グループのオーバーライドのみです。 | 1 |
| scopesToAdd | ユーザーのアクセストークンの `scope` クレームに追加するスコープのリスト。1 つ以上の空白文字を含むスコープ値を追加することはできません。 | 2 |
| scopesToSuppress | ユーザーのアクセストークンの `scope` クレームから削除するスコープのリスト。 | 2 |
\$1 バージョン 1 のイベントへのレスポンスオブジェクトは、文字列を返すことができます。バージョン 2 および 3 のイベントへのレスポンスオブジェクトは、[複雑なオブジェクト](#user-pool-lambda-pre-token-generation-event-versions)を返すことができます。
## トークン生成前トリガーイベントバージョン 2 の例:クレーム、スコープ、グループの追加と非表示
この例では、ユーザーのトークンに以下の変更を行います。
1. ID トークンに `family_name` として `Doe` を設定します。
1. ID トークンに `email` クレームと `phone_number` クレームが表示されないようにします。
1. ID トークンの `cognito:roles` クレームを `"arn:aws:iam::123456789012:role\/sns_callerA","arn:aws:iam::123456789012:role\/sns_callerC","arn:aws:iam::123456789012:role\/sns_callerB"` に設定します。
1. ID トークンの `cognito:preferred_role` クレームを `arn:aws:iam::123456789012:role/sns_caller` に設定します。
1. スコープとして `openid`、`email`、`solar-system-data/asteroids.add` をアクセストークンに追加します。
1. アクセストークンの `phone_number` スコープと `aws.cognito.signin.user.admin` スコープを非表示にします。`phone_number` を削除すると、`userInfo` からユーザーの電話番号が取得されなくなります。`aws.cognito.signin.user.admin` を削除すると、ユーザーが Amazon Cognito ユーザープール API を使用して自分のプロファイルを読み取ったり変更したりするための API リクエストが禁止されます。
**注記**
`phone_number` をスコープから削除した場合、アクセストークンの残りのスコープに `openid` と少なくとも 1 つの標準スコープが含まれていれば、ユーザーの電話番号のみが取得できなくなります。詳細については、「[スコープについて](cognito-user-pools-define-resource-servers.md#cognito-user-pools-define-resource-servers-about-scopes)」を参照してください。
1. ID トークンとアクセストークンの `cognito:groups` クレームを `"new-group-A","new-group-B","new-group-C"` に設定します。
------
#### [ JavaScript ]
```
export const handler = function(event, context) {
event.response = {
"claimsAndScopeOverrideDetails": {
"idTokenGeneration": {
"claimsToAddOrOverride": {
"family_name": "Doe"
},
"claimsToSuppress": [
"email",
"phone_number"
]
},
"accessTokenGeneration": {
"scopesToAdd": [
"openid",
"email",
"solar-system-data/asteroids.add"
],
"scopesToSuppress": [
"phone_number",
"aws.cognito.signin.user.admin"
]
},
"groupOverrideDetails": {
"groupsToOverride": [
"new-group-A",
"new-group-B",
"new-group-C"
],
"iamRolesToOverride": [
"arn:aws:iam::123456789012:role/new_roleA",
"arn:aws:iam::123456789012:role/new_roleB",
"arn:aws:iam::123456789012:role/new_roleC"
],
"preferredRole": "arn:aws:iam::123456789012:role/new_role",
}
}
};
// Return to Amazon Cognito
context.done(null, event);
};
```
------
Amazon Cognito は Lambda 関数にイベント情報を渡します。関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。Lambda コンソールで、Lambda トリガーに関連するデータを使用したテストイベントをセットアップできます。以下は、このコードサンプルのテストイベントです。
------
#### [ JSON ]
```
{
"version": "2",
"triggerSource": "TokenGeneration_Authentication",
"region": "us-east-1",
"userPoolId": "us-east-1_EXAMPLE",
"userName": "JaneDoe",
"callerContext": {
"awsSdkVersion": "aws-sdk-unknown-unknown",
"clientId": "1example23456789"
},
"request": {
"userAttributes": {
"sub": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"cognito:user_status": "CONFIRMED",
"email_verified": "true",
"phone_number_verified": "true",
"phone_number": "+12065551212",
"family_name": "Zoe",
"email": "Jane.Doe@example.com"
},
"groupConfiguration": {
"groupsToOverride": ["group-1", "group-2", "group-3"],
"iamRolesToOverride": ["arn:aws:iam::123456789012:role/sns_caller1", "arn:aws:iam::123456789012:role/sns_caller2", "arn:aws:iam::123456789012:role/sns_caller3"],
"preferredRole": ["arn:aws:iam::123456789012:role/sns_caller"]
},
"scopes": [
"aws.cognito.signin.user.admin", "openid", "email", "phone"
]
},
"response": {
"claimsAndScopeOverrideDetails": []
}
}
```
------
## トークン生成前イベントバージョン 2 の例: 複雑なオブジェクトでクレームを追加する
この例では、ユーザーのトークンに以下の変更を行います。
1. ID トークンに数値、文字列、ブール値、JSON タイプのクレームを追加します。これは、ID トークンでバージョン 2 のトリガーイベントが利用できる唯一の変更です。
1. アクセストークンに数値、文字列、ブール値、JSON タイプのクレームを追加します。
1. アクセストークンに 3 つのスコープを追加します。
1. ID トークンとアクセストークンの `email` クレームを抑制します。
1. アクセストークンの `aws.cognito.signin.user.admin` スコープを抑制します。
------
#### [ JavaScript ]
```
export const handler = function(event, context) {
var scopes = ["MyAPI.read", "MyAPI.write", "MyAPI.admin"]
var claims = {}
claims["aud"]= event.callerContext.clientId;
claims["booleanTest"] = false;
claims["longTest"] = 9223372036854775807;
claims["exponentTest"] = 1.7976931348623157E308;
claims["ArrayTest"] = ["test", 9223372036854775807, 1.7976931348623157E308, true];
claims["longStringTest"] = "\{\
\"first_json_block\": \{\
\"key_A\": \"value_A\",\
\"key_B\": \"value_B\"\
\},\
\"second_json_block\": \{\
\"key_C\": \{\
\"subkey_D\": [\
\"value_D\",\
\"value_E\"\
],\
\"subkey_F\": \"value_F\"\
\},\
\"key_G\": \"value_G\"\
\}\
\}";
claims["jsonTest"] = {
"first_json_block": {
"key_A": "value_A",
"key_B": "value_B"
},
"second_json_block": {
"key_C": {
"subkey_D": [
"value_D",
"value_E"
],
"subkey_F": "value_F"
},
"key_G": "value_G"
}
};
event.response = {
"claimsAndScopeOverrideDetails": {
"idTokenGeneration": {
"claimsToAddOrOverride": claims,
"claimsToSuppress": ["email"]
},
"accessTokenGeneration": {
"claimsToAddOrOverride": claims,
"claimsToSuppress": ["email"],
"scopesToAdd": scopes,
"scopesToSuppress": ["aws.cognito.signin.user.admin"]
}
}
};
console.info("EVENT response\n" + JSON.stringify(event, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2))
console.info("EVENT response size\n" + JSON.stringify(event, (_, v) => typeof v === 'bigint' ? v.toString() : v).length)
// Return to Amazon Cognito
context.done(null, event);
};
```
------
Amazon Cognito は Lambda 関数にイベント情報を渡します。関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。Lambda コンソールで、Lambda トリガーに関連するデータを使用したテストイベントをセットアップできます。以下は、このコードサンプルのテストイベントです。
------
#### [ JSON ]
```
{
"version": "2",
"triggerSource": "TokenGeneration_HostedAuth",
"region": "us-west-2",
"userPoolId": "us-west-2_EXAMPLE",
"userName": "JaneDoe",
"callerContext": {
"awsSdkVersion": "aws-sdk-unknown-unknown",
"clientId": "1example23456789"
},
"request": {
"userAttributes": {
"sub": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"cognito:user_status": "CONFIRMED"
"email_verified": "true",
"phone_number_verified": "true",
"phone_number": "+12065551212",
"email": "Jane.Doe@example.com"
},
"groupConfiguration": {
"groupsToOverride": ["group-1", "group-2", "group-3"],
"iamRolesToOverride": ["arn:aws:iam::123456789012:role/sns_caller1"],
"preferredRole": ["arn:aws:iam::123456789012:role/sns_caller1"]
},
"scopes": [
"aws.cognito.signin.user.admin",
"phone",
"openid",
"profile",
"email"
]
},
"response": {
"claimsAndScopeOverrideDetails": []
}
}
```
------
## トークン生成前イベントバージョン 1 の例: 新しいクレームの追加と既存のクレームの非表示
この例では、トークン生成前の Lambda 関数でバージョン 1 のトリガーイベントを使用して、新しいクレームを追加し、既存のクレームを抑制します。
------
#### [ Node.js ]
```
const handler = async (event) => {
event.response = {
claimsOverrideDetails: {
claimsToAddOrOverride: {
my_first_attribute: "first_value",
my_second_attribute: "second_value",
},
claimsToSuppress: ["email"],
},
};
return event;
};
export { handler };
```
------
Amazon Cognito は Lambda 関数にイベント情報を渡します。関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。Lambda コンソールで、Lambda トリガーに関連するデータを使用したテストイベントをセットアップできます。以下は、このコードサンプルのテストイベントです。コード例 ではリクエストパラメータを処理しないため、空のリクエストでテストイベントを使用できます。共通のリクエストパラメータの詳細については、「[ユーザープールの Lambda トリガーイベント](cognito-user-pools-working-with-lambda-triggers.md#cognito-user-pools-lambda-trigger-event-parameter-shared)」を参照してください。
------
#### [ JSON ]
```
{
"request": {},
"response": {}
}
```
------
## トークン生成前イベントバージョン 1 の例: ユーザーグループのメンバーシップの変更
この例では、トークン生成前の Lambda 関数でバージョン 1 のトリガーイベントを使用し、ユーザーのグループメンバーシップを変更します。
------
#### [ Node.js ]
```
const handler = async (event) => {
event.response = {
claimsOverrideDetails: {
groupOverrideDetails: {
groupsToOverride: ["group-A", "group-B", "group-C"],
iamRolesToOverride: [
"arn:aws:iam::XXXXXXXXXXXX:role/sns_callerA",
"arn:aws:iam::XXXXXXXXX:role/sns_callerB",
"arn:aws:iam::XXXXXXXXXX:role/sns_callerC",
],
preferredRole: "arn:aws:iam::XXXXXXXXXXX:role/sns_caller",
},
},
};
return event;
};
export { handler };
```
------
Amazon Cognito は Lambda 関数にイベント情報を渡します。関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。Lambda コンソールで、Lambda トリガーに関連するデータを使用したテストイベントをセットアップできます。以下は、このコードサンプルのテストイベントです。
------
#### [ JSON ]
```
{
"request": {},
"response": {}
}
```
------