Package: cdk-lambda-recaptcha-authorizer
ReCaptcha Authorizer for AWS CDKThis is an AWS CDK construct that provides an easy way to add ReCaptcha-based authorization
to your API Gateway endpoints. It uses Google's ReCaptcha API to verify user responses and
secure your API resources.InstallationTo use this construct in your AWS CDK projects, you can install it from npm:npminstallcdk-lambda-recaptcha-authorizerExample UsageHere's an example of how to use theReCaptchaAuthorizerconstruct in your AWS CDK stack:import*ascdkfrom'aws-cdk-lib';import{Construct}from'constructs';import*asapigwfrom'aws-cdk-lib/aws-apigateway';import*aslambdafrom'aws-cdk-lib/aws-lambda';import{ReCaptchaAuthorizer}from'cdk-lambda-recaptcha-authorizer';exportclassLraExampleStackextendscdk.Stack{constructor(scope:Construct,id:string,props?:cdk.StackProps){super(scope,id,props);constchallangeResponseHeaderName='X-My-Header'constapi=newapigw.RestApi(this,'Api',{restApiName:'API',description:'API with reCAPTCHA authorizer',defaultCorsPreflightOptions:{allowHeaders:['Content-Type','X-Amz-Date',challangeResponseHeaderName],allowCredentials:true,allowOrigins:['*'],allowMethods:['OPTIONS','GET','POST','PUT','PATCH','DELETE'],}});constreCaptchaAuthorizer=newReCaptchaAuthorizer(this,'ReCaptchaAuthorizer',{reCaptchaSecretKey:'YOUR-RECAPTCHA-SECRET-KEY',reCaptchaVersion:'v2',challangeResponseHeaderName:challangeResponseHeaderName})constresource=api.root.addResource('submitForm');resource.addMethod('POST',newapigw.LambdaIntegration(newlambda.Function(this,'Lambda',{runtime:lambda.Runtime.NODEJS_14_X,handler:'index.handler',code:lambda.Code.fromInline('exports.handler = async () => { return { statusCode: 200, body: "Hello World!" }; };'),})),{authorizer:reCaptchaAuthorizer,authorizationType:apigw.AuthorizationType.CUSTOM,});}}Here's an example form in html that sends recaptcha challange response in header:<!DOCTYPE html><html><head><title>reCAPTCHA v2 Demo</title><scriptsrc="https://www.google.com/recaptcha/api.js"asyncdefer></script></head><body><h1>reCAPTCHA v2 Demo Form</h1><formid="demoForm"method="POST"><labelfor="name">Name:</label><inputtype="text"id="name"name="name"required/><br/><divclass="g-recaptcha"data-sitekey="YOUR-RECAPTCHA-SITE-KEY"></div><buttontype="submit">Submit</button></form><script>constform=document.getElementById("demoForm")form.addEventListener("submit",async(event)=>{event.preventDefault()constrecaptchaResponse=grecaptcha.getResponse()if(recaptchaResponse===""){alert("Please complete the reCAPTCHA verification.")return}constheaders=newHeaders()headers.append("X-My-Header",recaptchaResponse)constresponse=awaitfetch("YOUR-API-GATEWAY-URL",{method:"POST",headers:headers,body:newFormData(form),})if(response.ok){alert("Form submitted successfully!")}else{alert("Form submission failed. Please try again later.")}})</script></body></html>ConfigurationTheReCaptchaAuthorizeraccepts the following configuration options:reCaptchaSecretKey: Your ReCaptcha secret key. It is required.reCaptchaVersion: The ReCaptcha version to use. It can be either 'v2' or 'v3'.v3MinScoreRequired: (Optional) The minimum score required for ReCaptcha v3 authorization. Default is 0.5.v3Action: (Optional) Specify a custom action name for ReCaptcha v3 authorization.challangeResponseHeaderName: (Optional) The name of the header containing the
ReCaptcha response token. Default is 'X-Recaptcha-Response'.ThereCaptchaSecretKeyandreCaptchaVersionare mandatory parameters, as they are essential
for the ReCaptcha verification process. If you don't provide these values, an error will be thrown.For ReCaptcha v3, you can optionally set thev3MinScoreRequiredparameter to specify the minimum
score required for authorization. The default value is 0.5, but you can adjust it as needed.If you are using ReCaptcha v3 and have defined specific actions in your ReCaptcha settings,
you can use thev3Actionparameter to specify the expected action name for the request.
If the action name doesn't match the one provided, the verification will fail.Additionally, you can customize the header name used to send the ReCaptcha token
with thechallangeResponseHeaderNameparameter. The default header name is 'X-Recaptcha-Response',
but you can use a custom name if needed.Keep in mind that these configuration options should be provided when creating theReCaptchaAuthorizerinstance to ensure proper functioning and security of your API endpoints.How It WorksTheReCaptchaAuthorizerconstruct creates an AWS Lambda function that handles the ReCaptcha verification.
It sends the ReCaptcha token to Google's ReCaptcha API using an HTTPS POST request and verifies
the user's response. If the verification is successful, the authorizer allows the request to proceed
and grants access to the associated API Gateway resource.Here's a high-level overview of the process:When a client makes a request to an API Gateway endpoint protected by theReCaptchaAuthorizer,
it includes a ReCaptcha token in the request headers.TheReCaptchaAuthorizerLambda function receives the request and extracts the ReCaptcha
token from the headers.The Lambda function then sends an HTTPS POST request to Google's ReCaptcha API with the
ReCaptcha token and your ReCaptcha secret key.Google's ReCaptcha API verifies the token and sends back a response indicating whether
the token is valid or not.If the ReCaptcha token is valid, the Lambda function allows the request to proceed
and grants access to the API Gateway resource.If the ReCaptcha token is invalid or the verification fails, the Lambda function
denies access to the API Gateway resource and returns an unauthorized response.