AWS cognito documentation change
Summary
Added comprehensive client metadata documentation with security use cases
Security assessment
Documents security applications of client metadata including geolocation checks, tenant-specific challenges, and M2M request logging - enhances security capabilities but doesn't address specific vulnerabilities.
Diff
diff --git a/cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.md b/cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.md index 07613243a..f0ddbf572 100644 --- a//cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.md +++ b//cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.md @@ -5 +5 @@ -Things to knowSet up triggersUser pool Lambda trigger eventUser pool Lambda trigger common parametersTrigger sources by operationTrigger sources by function +Things to knowSet up triggersUser pool Lambda trigger eventUser pool Lambda trigger common parametersClient metadataTrigger sources by operationTrigger sources by function @@ -43,0 +44,2 @@ User Pool Flow | Operation | Description + * Client metadata + @@ -238,0 +241,98 @@ This parameter doesn't contain any information in the original request. Your Lam +## Client metadata + +You can submit custom parameters to your Lambda trigger functions in API operations and [Token endpoint](./token-endpoint.html) requests. With client metadata, your application can collect additional information about the environment where requests originate. When you pass client metadata to your Lambda functions, they can process the additional data and make use of it in logging or customization of authentication flows. Client metadata is string pairs of your choosing and design in a JSON key-value format. + +###### Client metadata example use cases + + * Pass geolocation data at sign-up to the [pre sign-up trigger](./user-pool-lambda-pre-sign-up.html) and prevent sign-in from unwanted locations. + + * Pass tenant ID data to [custom challenge triggers](./user-pool-lambda-challenge.html) and issue different challenges to customers from different business units. + + * Pass a user's token to the [pre token generation trigger](./user-pool-lambda-pre-token-generation.html) and generate a log of the principal that an M2M request was made on behalf of. For an example request, see [Client credentials with basic authorization](./token-endpoint.html#exchanging-client-credentials-for-an-access-token-in-request-body). + + + + +Here is an example of passing client metadata to the pre sign-up trigger. + +SignUp request + + +The following is an example [SignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html#CognitoUserPools-SignUp-request-ValidationData) request with client metadata that Amazon Cognito passes to a pre sign-up trigger. + + + POST HTTP/1.1 + Host: cognito-idp.us-east-1.amazonaws.com + X-Amz-Date: 20230613T200059Z + Accept-Encoding: gzip, deflate, br + X-Amz-Target: AWSCognitoIdentityProviderService.SignUp + User-Agent: <UserAgentString> + Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=<Headers>, Signature=<Signature> + Content-Length: <PayloadSizeBytes> + + { + "ClientId": "1example23456789", + "Username": "mary_major", + "Password": "<Password>", + "SecretHash": "<Secret hash>", + "ClientMetadata": { + "IpAddress" : "192.0.2.252", + "GeoLocation" : "Netherlands (Kingdom of the) [NL]" + } + "UserAttributes": [ + { + "Name": "name", + "Value": "Mary" + }, + { + "Name": "email", + "Value": "[email protected]" + }, + { + "Name": "phone_number", + "Value": "+12065551212" + } + ], + } + +Lambda trigger input event + + +The request results in the following request body to your pre sign-up function. + + + { + "callerContext": { + "awsSdkVersion": "aws-sdk-unknown-unknown", + "clientId": "1example23456789" + }, + "region": "us-west-2", + "request": { + "clientMetadata": { + "GeoLocation": "Netherlands (Kingdom of the) [NL]", + "IpAddress": "192.0.2.252" + }, + "userAttributes": { + "email": "[email protected]", + "name": "Mary", + "phone_number": "+12065551212" + }, + "validationData": null + }, + "response": { + "autoConfirmUser": false, + "autoVerifyEmail": false, + "autoVerifyPhone": false + }, + "triggerSource": "PreSignUp_SignUp", + "userName": "mary_major2", + "userPoolId": "us-west-2_EXAMPLE", + "version": "1" + } + +###### Temporary user attributes: `validationData` + +Some authentication operations also have a `validationData` parameter. Like client metadata, this is an opportunity to pass external information that Amazon Cognito doesn't automatically gather to Lambda triggers. The validation data field is intended to provide your Lambda function witth additional user context in sign-up and sign-in operations. [SignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html#CognitoUserPools-SignUp-request-ValidationData) and [AdminCreateUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminCreateUser.html#CognitoUserPools-AdminCreateUser-request-ValidationData) pass `validationData` to the [pre sign-up trigger](./user-pool-lambda-pre-sign-up.html). [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html#CognitoUserPools-InitiateAuth-request-ClientMetadata) and [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html#CognitoUserPools-AdminInitiateAuth-request-ClientMetadata) pass `ClientMetadata` in the API request body as `validationData` in the input event to the [pre authentication](./user-pool-lambda-pre-authentication.html) and [migrate user](./user-pool-lambda-migrate-user.html) triggers. + +To map API operations to the functions that they can pass client metadata to, refer to the trigger source sections that follow. +