AWS cognito documentation change
Summary
Removed detailed setup steps for custom email sender triggers and replaced with a link to external documentation. Changed KMS key reference from alias to ID in example code.
Security assessment
The changes primarily restructure documentation by removing implementation details and consolidating setup instructions into a linked guide. While KMS encryption and Lambda permissions are security-related topics, there is no evidence this change addresses a specific vulnerability or weakness. The KEY_ALIAS to KEY_ID change clarifies parameter usage but doesn't indicate a security fix.
Diff
diff --git a/cognito/latest/developerguide/user-pool-lambda-custom-email-sender.md b/cognito/latest/developerguide/user-pool-lambda-custom-email-sender.md index bcc626cdc..2c45137d4 100644 --- a//cognito/latest/developerguide/user-pool-lambda-custom-email-sender.md +++ b//cognito/latest/developerguide/user-pool-lambda-custom-email-sender.md @@ -5 +5 @@ -Trigger sourcesParametersSet upExample: decrypt code +Trigger sourcesParametersExample: decrypt code @@ -13,29 +13 @@ This trigger serves scenarios where you might want to have greater control over -###### Note - -Currently, you can't assign custom sender triggers in the Amazon Cognito console. You can assign a trigger with the `LambdaConfig` parameter in a `CreateUserPool` or `UpdateUserPool` API request. - -To set up this trigger, perform the following steps: - - 1. Create a [symmetric encryption key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#symmetric-cmks) in AWS Key Management Service (AWS KMS). Amazon Cognito generates secrets—temporary passwords, verification codes, and confirmation codes—then uses this KMS key to encrypt the secrets. You can then use the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) API operation in your Lambda function to decrypt the secrets and send them to the user in plaintext. The [AWS Encryption SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html) is a useful tool for AWS KMS operations in your function. - - 2. Create a Lambda function that you want to assign as your custom sender trigger. Grant `kms:Decrypt` permissions for your KMS key to the Lambda function role. - - 3. Grant Amazon Cognito service principal `cognito-idp.amazonaws.com` access to invoke the Lambda function. - - 4. Write Lambda function code that directs your messages to custom delivery methods or third-party providers. To deliver your user's verification or confirmation code, Base64 decode and decrypt the value of the `code` parameter in the request. This operation produces a plaintext code or password that you must include in your message. - - 5. Update the user pool so that it uses a custom sender Lambda trigger. The IAM principal that updates or creates a user pool with a custom sender trigger must have permission to create a grant for your KMS key. The following `LambdaConfig` snippet assigns custom SMS and email sender functions. - - "LambdaConfig": { - "KMSKeyID": "arn:aws:kms:us-east-1:123456789012:key/a6c4f8e2-0c45-47db-925f-87854bc9e357", - "CustomEmailSender": { - "LambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:MyFunction", - "LambdaVersion": "V1_0" - }, - "CustomSMSSender": { - "LambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:MyFunction", - "LambdaVersion": "V1_0" - } - - - +To learn how to configure a custom email sender trigger, see [Activating custom sender Lambda triggers](./user-pool-lambda-custom-sender-triggers.html#enable-custom-sender-lambda-trigger). @@ -121,74 +92,0 @@ Amazon Cognito doesn't expect any additional return information in the custom em -## Activating the custom email sender Lambda trigger - -To set up a custom email sender trigger that uses custom logic to send email messages for your user pool, activate the trigger as follows. The procedure that follows assigns a custom email trigger, a custom SMS trigger, or both to your user pool. After you add your custom email sender trigger, Amazon Cognito always sends user attributes, including the email address, and the one-time code to your Lambda function when it would have otherwise sent an email message with Amazon Simple Email Service. - -###### Important - -Amazon Cognito HTML-escapes reserved characters like `<` (`<`) and `>` (`>`) in your user's temporary password. These characters might appear in temporary passwords that Amazon Cognito sends to your custom email sender function, but don't appear in temporary verification codes. To send temporary passwords, your Lambda function must unescape these characters after it decrypts the password, and before it sends the message to your user. - - 1. Create an encryption key in AWS KMS. This key encrypts temporary passwords and authorization codes that Amazon Cognito generates. You can then decrypt these secrets in the custom sender Lambda function and send them to your user in plaintext. - - 2. The IAM principal that creates or updates your user pool creates a one-time grant against the KMS key that Amazon Cognito uses to encrypt the code. Grant this principal `CreateGrant` permissions for your KMS key. For this example KMS key policy to be effective, the administrator who updates the user pool must be signed in with an assumed-role session for the IAM role ` arn:aws:iam::111222333444:role/my-example-role`. - -Apply the following resource-based policy to your KMS key. - - { - "Version": "2012-10-17", - "Statement": [{ - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::111222333444:role/my-example-role" - }, - "Action": "kms:CreateGrant", - "Resource": "arn:aws:kms:us-west-2:111222333444:key/1example-2222-3333-4444-999example", - "Condition": { - "StringEquals": { - "aws:SourceAccount": "111222333444" - }, - "ArnLike": { - "aws:SourceArn": "arn:aws:cognito-idp:us-west-2:111222333444:userpool/us-east-1_EXAMPLE" - } - } - }] - } - - 3. Create a Lambda function for the custom sender trigger. Amazon Cognito uses the [AWS encryption SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html) to encrypt the secrets, temporary passwords and codes that authorize your users' API requests. - - 1. Assign an IAM role to your Lambda function that has, at minimum, `kms:Decrypt` permissions for your KMS key. - - 4. Grant Amazon Cognito service principal `cognito-idp.amazonaws.com` access to invoke the Lambda function. - -The following AWS CLI command grants Amazon Cognito permission to invoke your Lambda function: - - aws lambda add-permission --function-name lambda_arn --statement-id "CognitoLambdaInvokeAccess" --action lambda:InvokeFunction --principal cognito-idp.amazonaws.com - - - 5. Compose your Lambda function code to send your messages. Amazon Cognito uses AWS Encryption SDK to encrypt secrets before Amazon Cognito sends the secrets to the custom sender Lambda function. In your function, decrypt the secret and process any relevant metadata. Then send the code, your own custom message, and destination phone number to the custom API that delivers your message. - - 6. Add the AWS Encryption SDK to your Lambda function. For more information, see [AWS Encryption SDK programming languages](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/programming-languages.html). To update the Lambda package, complete the following steps. - - 1. Export your Lambda function as a .zip file in the AWS Management Console. - - 2. Open your function and add the AWS Encryption SDK. For more information and download links, see [AWS Encryption SDK programming languages](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/programming-languages.html) in the _AWS Encryption SDK Developer Guide_. - - 3. Zip your function with your SDK dependencies, and upload the function to Lambda. For more information, see [Deploying Lambda functions as .zip file archives](https://docs.aws.amazon.com/lambda/latest/dg/configuration-function-zip.html#configuration-function-create) in the _AWS Lambda Developer Guide_. - - 7. Update your user pool to add custom sender Lambda triggers. Include a `CustomSMSSender` or `CustomEmailSender` parameter in an `UpdateUserPool` API request. The `UpdateUserPool` API operation requires all the parameters of your user pool _and_ the parameters that you want to change. If you don't provide all relevant parameters, Amazon Cognito sets the values of any missing parameters to their defaults. As demonstrated in the example that follows, include entries for all Lambda functions that you want to add to or keep in your user pool. For more information, see [Updating user pool and app client configuration](./cognito-user-pool-updating.html). - - #Send this parameter in an 'aws cognito-idp update-user-pool' CLI command, including any existing - #user pool configurations. This snippet also includes a pre sign-up trigger for syntax reference. The pre sign-up trigger - #doesn't have a role in custom sender triggers. - - --lambda-config "PreSignUp=lambda-arn, \ - CustomSMSSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \ - CustomEmailSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \ - KMSKeyID=key-id" - - - - - -To remove a custom sender Lambda trigger with an `update-user-pool` AWS CLI, omit the `CustomSMSSender` or `CustomEmailSender` parameter from `--lambda-config`, and include all other triggers that you want to use with your user pool. - -To remove a custom sender Lambda trigger with an `UpdateUserPool` API request, omit the `CustomSMSSender` or `CustomEmailSender` parameter from the request body that contains the rest of your user pool configuration. - @@ -199 +97 @@ The following Node.js example processes an email message event in your custom em -**`KEY_ALIAS`** +**`KEY_ID`** @@ -202 +100 @@ The following Node.js example processes an email message event in your custom em -The [alias](https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html) of the KMS key that you want to use to encrypt and decrypt your users' codes. +The ID of the KMS key that you want to use to encrypt and decrypt your users' codes.