기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 사전 토큰 생성 Lambda 트리거
토큰 생성 전에 Amazon Cognito가 이 트리거를 간접 호출하기 때문에 사용자 풀 토큰 신청을 사용자 지정할 수 있습니다. 버전 1 또는 `V1_0` 사전 토큰 생성 트리거 이벤트의 **기본 기능**을 사용하여 ID 토큰을 사용자 지정할 수 있습니다. Essentials 또는 Plus 기능 플랜이 있는 사용자 풀에서는 액세스 토큰 사용자 지정을 통해 버전 2 또는 `V2_0` 트리거 이벤트를 생성하고 M2M(머신 간) 클라이언트 자격 증명 부여를 위한 액세스 토큰 사용자 지정을 통해 버전 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 및 액세스 토큰 클레임 값에 전달하는 기능:
+ 문자열
+ 숫자
+ 부울
+ 문자열, 숫자, 부울 또는 이러한 문자열의 조합 배열
+ JSON
**참고**
ID 토큰에서 `phone_number_verified`, `email_verified`, `updated_at` 및 `address`를 제외한 복잡한 개체를 클레임 값에 채울 수 있습니다.
사용자 풀은 기본적으로 `V1_0` 이벤트를 전달합니다. `V2_0` 이벤트를 보내도록 사용자 풀을 구성하려면 Amazon Cognito 콘솔에서 트리거를 구성할 때 사용자 ID에 대한 **기본 기능 \$1 액세스 토큰 사용자 지정**의 **이벤트 트리거 버전**을 선택합니다. `V3_0` 이벤트를 생성하려면 ****사용자 및 머신 ID에 대한 기본 기능 \$1 액세스 토큰 사용자 지정****을 선택합니다. [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) 또는 [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은 **Essentials** 및 **Plus** 기능 플랜에서 사용할 수 있습니다. 버전 3 이벤트에 대한 M2M 작업에는 월간 활성 사용자(MAU) 공식과 별도의 요금 구조가 있습니다. 자세한 내용은 [Amazon Cognito 요금](https://aws.amazon.com/cognito/pricing/)을 참조하세요.
**참고**
2024년 11월 22일 18:00 GMT 이전에 **고급 보안 기능** 옵션으로 작동하고 **Lite** 기능 계층에 남아 있는 사용자 풀은 사전 토큰 생성 트리거의 이벤트 버전 1 및 2에 액세스할 수 있습니다. 고급 보안 기능이 *없는* 이 레거시 계층의 사용자 풀은 이벤트 버전 1에 액세스할 수 있습니다. 버전 3은 Essentials 및 Plus*에서만* 사용할 수 있습니다.
## 클레임 및 범위 참조
Amazon Cognito는 액세스 및 자격 증명 토큰에서 추가, 수정 또는 억제할 수 있는 클레임 및 범위를 제한합니다. 다음 표에서는 Lambda 함수가 수정할 수 있는 클레임과 수정할 수 없는 클레임 및 클레임의 존재 또는 값에 영향을 미치는 트리거 이벤트 파라미터를 설명합니다.
| Claim | 기본 토큰 유형 | 추가할 수 있나요? | 수정할 수 있나요? | 억제할 수 있나요? | 이벤트 파라미터 - 추가 또는 수정 | 이벤트 파라미터 - 억제 | 자격 증명 유형 | 이벤트 버전 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 사용자 풀 토큰 스키마에 없는 클레임 | 없음 | 예 | 예 | 해당 사항 없음 | 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 | User | 모두[2](#cognito-pretoken-id-access-versions-note) |
| cognito:preferred\$1role | ID | 예 | 예 | 예 | preferredRole | claimsToSuppress[3](#cognito-pretoken-suppress-groups-note) | User | 모두 |
| cognito:roles | ID | 예 | 예 | 예 | iamRolesToOverride | claimsToSuppress[3](#cognito-pretoken-suppress-groups-note) | User | 모두 |
| cognito:username | ID | 아니요 | 아니요 | 아니요 | 해당 사항 없음 | 해당 사항 없음 | User | 해당 사항 없음 |
| cognito: 접두사가 있는 기타 모든 클레임 | 없음 | 아니요 | 아니요 | 아니요 | 해당 사항 없음 | 해당 사항 없음 | 해당 사항 없음 | 해당 사항 없음 |
| username | 액세스 | 아니요 | 아니요 | 아니요 | 해당 사항 없음 | 해당 사항 없음 | User | v2\$10, v3\$10 |
| sub | ID, 액세스 | 아니요 | 아니요 | 아니요 | 해당 사항 없음 | 해당 사항 없음 | User | 해당 사항 없음 |
| 표준 OIDC 속성 | ID | 예 | 예 | 예 | claimsToAddOrOverride | claimsToSuppress | User | 모두 |
| custom: 속성 | ID | 예 | 예 | 예 | claimsToAddOrOverride | claimsToSuppress | User | 모두 |
| dev: 속성 | ID | 아니요 | 아니요 | 예 | 해당 사항 없음 | claimsToSuppress | User | 모두 |
| identities | ID | 아니요 | 아니요 | 아니요 | 해당 사항 없음 | 해당 사항 없음 | User | 해당 사항 없음 |
| aud[4](#cognito-pretoken-aud-note) | ID | 아니요 | 아니요 | 아니요 | 해당 사항 없음 | 해당 사항 없음 | 사용자, 머신 | 해당 사항 없음 |
| client\$1id | 액세스 | 아니요 | 아니요 | 아니요 | 해당 사항 없음 | 해당 사항 없음 | 사용자, 머신 | 해당 사항 없음 |
| event\$1id | 액세스 | 아니요 | 아니요 | 아니요 | 해당 사항 없음 | 해당 사항 없음 | 사용자, 머신 | 해당 사항 없음 |
| device\$1key | 액세스 | 아니요 | 아니요 | 아니요 | 해당 사항 없음 | 해당 사항 없음 | User | 해당 사항 없음 |
| 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은 **Essentials** 및 **Plus** 기능 계층에서만 사용할 수 있습니다. **Lite** 계층의 사용자 풀은 `v1_0` 이벤트를 수신할 수 있습니다. 고급 보안 기능이 있는 **Lite** 계층의 사용자 풀은 `v1_0` 및 `v2_0` 이벤트를 수신할 수 있습니다.
2 ID 토큰만을 위한 이벤트 버전 `v1_0`, ID 및 액세스 토큰을 위한 이벤트 버전 `v2_0`, 머신 ID에 대한 기능이 있는 ID 및 액세스 토큰을 위한 이벤트 버전 `v3_0`으로 사전 토큰 생성 트리거를 구성합니다.
3 `cognito:preferred_role` 및 `cognito:roles` 클레임을 억제하려면 `claimsToSuppress`에 `cognito:groups`를 추가합니다.
4 액세스 토큰에 `aud` 클레임을 추가할 수 있지만 해당 값은 현재 세션의 앱 클라이언트 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와 같은 액세스 보호 리소스에서 정보를 검색할 수 있는 권한을 사용자에게 부여합니다. 클라이언트 자격 증명 부여를 사용한 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 Management Console ]
**사전 토큰 생성 Lambda 트리거에서 액세스 토큰 사용자 지정의 지원**
1. [Amazon Cognito 콘솔](https://console.aws.amazon.com/cognito/home)로 이동한 다음 **사용자 풀(User Pools)**을 선택합니다.
1. 목록에서 기존 사용자 풀을 선택하거나 [사용자 풀을 생성합니다](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).
1. **확장** 메뉴를 선택하고 **Lambda 트리거**를 찾습니다.
1. **사전 토큰 생성 트리거**를 추가 또는 편집합니다.
1. **Lambda 함수 할당**에서 Lambda 함수를 선택합니다.
1. **사용자 ID에 대한 기본 기능 \$1 액세스 토큰 사용자 지정** 또는 **사용자 및 머신 ID에 대한 기본 기능 \$1 액세스 토큰 사용자 지정**의 **트리거 이벤트 버전**을 선택합니다. 이 설정은 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` 파라미터에 다음 콘텐츠를 포함합니다. `V2_0`의 `LambdaVersion` 값은 사용자 풀이 액세스 토큰에 대한 파라미터를 추가하고 변경 사항을 적용하도록 합니다. `V3_0`의 `LambdaVersion` 값은 `V2_0`과 동일한 이벤트를 생성하지만 *또한* 사용자 풀이 M2M 액세스 토큰에 변경 사항을 적용하도록 합니다. 특정 함수 버전을 간접 호출하려면 함수 버전을 `LambdaArn`의 값으로 포함하는 Lambda 함수 ARN을 사용하세요.
```
"PreTokenGenerationConfig": {
"LambdaArn": "arn:aws:lambda:us-west-2:123456789012:function:MyFunction",
"LambdaVersion": "V3_0"
},
```
------
**M2M(머신 간) 클라이언트 자격 증명을 위한 클라이언트 메타데이터**
M2M 요청에서 [클라이언트 메타데이터](cognito-user-pools-working-with-lambda-triggers.md#working-with-lambda-trigger-client-metadata)를 전달할 수 있습니다. 클라이언트 메타데이터는 [사전 토큰 생성 Lambda 트리거](#user-pool-lambda-pre-token-generation)의 결과에 기여할 수 있는 사용자 또는 애플리케이션 환경의 추가 정보입니다. 사용자 보안 주체를 사용한 인증 작업에서 [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 요청 본문의 사전 토큰 생성 트리거에 클라이언트 메타데이터를 전달할 수 있습니다. 애플리케이션은 [Token 엔드포인트](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)
+ [자격 증명 토큰 사용자 지정](#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 값 | Event |
| --- | --- |
| TokenGeneration\$1HostedAuth | Amazon Cognito 관리 로그인 페이지에서 인증 중에 호출됩니다. |
| TokenGeneration\$1Authentication | 사용자 인증 흐름이 완료된 이후 호출됩니다. |
| TokenGeneration\$1NewPasswordChallenge | 사용자가 관리자에 의해 생성된 후 호출됩니다. 이 흐름은 사용자가 임시 비밀번호를 변경해야 할 때 호출됩니다. |
| TokenGeneration\$1ClientCredentials | M2M 클라이언트 자격 증명 부여 후 호출됩니다. 사용자 풀은 이벤트 버전이 V3\$10인 경우에만 이 이벤트를 전송합니다. |
| TokenGeneration\$1AuthenticateDevice | 사용자 디바이스 인증 마지막에 호출됩니다. |
| TokenGeneration\$1RefreshTokens | 사용자가 자격 증명 및 액세스 토큰을 새로 고치려 할 때 호출됩니다. |
## 사전 토큰 생성 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`에서 다음 형식의 데이터를 반환할 수 있습니다.
+ 문자열
+ 숫자
+ 부울
+ 문자열, 숫자, 부울 또는 이러한 문자열의 조합 배열
+ 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 함수에 대한 사용자 지정 입력으로 제공할 수 있는 하나 이상의 키-값 페어입니다. 이 데이터를 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 | 추가 또는 수정하려는 하나 이상의 클레임 및 해당 값이 표시된 맵입니다. 그룹 관련 클레임의 경우 대신 `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` 클레임에 추가하려는 범위 목록입니다. 하나 이상의 공백 문자가 포함된 범위 값은 추가할 수 없습니다. | 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 요청이 방지됩니다.
**참고**
액세스 토큰의 나머지 범위에 `openid` 및 하나 이상의 표준 범위가 포함된 경우에만 범위에서 `phone_number`를 제거하면 사용자 전화 번호를 검색할 수 없습니다. 자세한 내용은 [범위에 대한 정보](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 유형의 클레임을 추가합니다. 이는 버전 2 트리거 이벤트가 ID 토큰에 사용할 수 있도록 하는 유일한 변경 사항입니다.
1. 번호, 문자열, 부울 및 JSON 유형의 클레임을 액세스 토큰에 추가합니다.
1. 액세스 토큰에 세 가지 범위를 추가합니다.
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": {}
}
```
------