
subaud is authored by Court Schuett (he/him). While Court is an 8090 Inc employee, opinions and statements on this blog are his own.


Court Schuett


# AWS CDK Cognito Protected API Demo

This project demonstrates how to create a protected API using AWS CDK with Cognito authentication. It sets up a complete serverless infrastructure including API Gateway, Lambda, and Cognito User Pool. To test the API, we'll configure and use Postman with OAuth 2.0 to sign in and get an access token. This can be an easy way to test your API without setting up a frontend while still using JWTs for authentication.

## Architecture

The infrastructure consists of three main components:

**Cognito User Pool**: Handles user authentication

- Email-based sign-up and sign-in
- Password policies and email verification
- OAuth 2.0 flows support
- Hosted UI for sign-up/sign-in

**API Gateway**: Protected REST API

- Cognito authorizer integration
- Single GET endpoint `/hello`
- JWT token validation

**Lambda Function**: Backend logic

- Returns protected data
- Includes user information from Cognito claims

![Overview](/images/blog/cdk-cognito-api-postman/CogntioAPIPostman.drawio.png)

## Infrastructure Code Overview

### Cognito Setup (CognitoConstruct)

```typescript
this.userPool = new UserPool(this, "UserPool", {
  userPoolName: "postman-demo-user-pool",
  selfSignUpEnabled: true,
  signInAliases: { email: true },
  standardAttributes: {
    email: { required: true, mutable: true },
    givenName: { required: true, mutable: true },
  },
  passwordPolicy: {
    minLength: 8,
    requireLowercase: true,
    requireUppercase: true,
    requireDigits: true,
    requireSymbols: true,
  },
  signInCaseSensitive: false,
  userVerification: {
    emailStyle: VerificationEmailStyle.LINK,
    emailSubject: "Verify your email for our demo app!",
  },
});

this.userPoolClient = new UserPoolClient(this, "UserPoolClient", {
  userPool: this.userPool,
  oAuth: {
    flows: {
      authorizationCodeGrant: true,
      implicitCodeGrant: true,
    },
    scopes: [OAuthScope.EMAIL, OAuthScope.OPENID, OAuthScope.PROFILE],
    callbackUrls: [
      "http://localhost:3000/callback",
      "https://oauth.pstmn.io/v1/callback",
    ],
  },
  preventUserExistenceErrors: true,
  accessTokenValidity: Duration.minutes(60),
  idTokenValidity: Duration.minutes(60),
  refreshTokenValidity: Duration.days(30),
});
```

### API Gateway Setup (ApiGatewayConstruct)

```typescript
const api = new RestApi(this, "ProtectedApi", {
  restApiName: "Protected API Demo",
  description: "API Gateway with Cognito authorization",
});

const authorizer = new CognitoUserPoolsAuthorizer(this, "ApiAuthorizer", {
  cognitoUserPools: [props.userPool],
  authorizerName: "CognitoAuthorizer",
  identitySource: "method.request.header.Authorization",
  resultsCacheTtl: Duration.minutes(5),
});

const resource = api.root.addResource("hello");
resource.addMethod("GET", new LambdaIntegration(props.lambdaFunction), {
  authorizer: authorizer,
  authorizationType: AuthorizationType.COGNITO,
  authorizationScopes: ["email", "openid", "profile"],
});
```

## Understanding Cognito Tokens & API Security

### Token Flow

When a user authenticates through Cognito, three different tokens are issued:

1. **ID Token**: A JWT containing user identity claims (profile info, email, etc.)
2. **Access Token**: A JWT specifically for authorizing API requests
3. **Refresh Token**: Used to obtain new ID and Access tokens when they expire

### How API Gateway Authorization Works

1. Client obtains tokens through Cognito authentication
2. Client includes Access Token in API request (`Authorization: Bearer <token>`)
3. API Gateway:
   - Validates token signature using Cognito's public keys
   - Checks token expiration
   - Verifies audience (client_id) and issuer (Cognito User Pool)
   - Passes user claims to Lambda in `event.requestContext.authorizer`

### JWT Token Structure

Each token is a JSON Web Token (JWT) with three parts:

```bash
header.payload.signature
```

#### ID Token Example

https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.html

```json
{
  "sub": "user-uuid",
  "email_verified": true,
  "iss": "https://cognito-idp.{region}.amazonaws.com/{userPoolId}",
  "cognito:username": "john.doe",
  "given_name": "John",
  "aud": "{clientId}",
  "token_use": "id",
  "exp": 1234567890,
  "iat": 1234567890
}
```

#### Access Token Example

https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.html

```json
{
  "sub": "user-uuid",
  "device_key": "device-id",
  "scope": "email openid profile",
  "iss": "https://cognito-idp.{region}.amazonaws.com/{userPoolId}",
  "token_use": "access",
  "exp": 1234567890,
  "iat": 1234567890
}
```

### Token Validation Process

https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-verifying-a-jwt.html

1. **Structure Verification**

   - Check if token is well-formed JWT
   - Verify token hasn't expired (`exp` claim)
   - Validate token use (`token_use` claim)

2. **Signature Validation**

   - Download JWKs from Cognito
   - Verify token signature using public key
   - Ensure issuer (`iss`) matches User Pool

3. **Claims Validation**
   - Verify audience (`aud`) matches client ID
   - Check required scopes are present
   - Validate any custom claims

### Security Best Practices

#### Token Configuration

- Access tokens expire in 60 minutes (configured in Cognito client)
- ID tokens expire in 60 minutes (configured in Cognito client)
- Refresh tokens expire in 30 days
- Authorization cache TTL set to 5 minutes in API Gateway
- Tokens must be sent in Authorization header

#### Cognito Security Settings

- Case-insensitive email sign-in enabled
- User existence errors prevented (security feature)
- Password requirements enforced:
  - Minimum length: 8 characters
  - Requires lowercase letters
  - Requires uppercase letters
  - Requires numbers
  - Requires special characters
- Email verification required
- OAuth flows:
  - Authorization Code Grant (for web apps)
  - Implicit Grant (for mobile apps)
- Strict callback URL validation

#### API Gateway Security

- Cognito authorizer validates tokens automatically
- Required scopes: email, openid, profile
- Authorization caching for performance (5-minute TTL)
- Token claims available to Lambda function

### Security Benefits

- **Token-based Authentication**: Stateless, scalable authentication
- **Short-lived Tokens**: Access tokens expire in 1 hour (configurable)
- **Signature Verification**: Prevents token tampering
- **Scope-based Access**: Can restrict API access based on token scopes
- **User Context**: Lambda receives verified user information
- **Standard OAuth2/OIDC**: Industry-standard security protocols

## Testing with Postman

### **Get the Hosted UI URL**

- After deploying, find the `HostedUISignUpUrl` in CloudFormation outputs
- Create an account through the Hosted UI
- Verify your email address

![SignUp](/images/blog/cdk-cognito-api-postman/SignUp.png)
_Sign up page_

![VerificationLink](/images/blog/cdk-cognito-api-postman/VerificationLink.png)
_Verification link_

![VerificationEmail](/images/blog/cdk-cognito-api-postman/VerificationEmail.png)
_Verification email_

###**Configure Postman**

- Create a new request
- Under Authorization tab:
  - Type: OAuth 2.0
  - Grant Type: Authorization Code
  - Callback URL: https://oauth.pstmn.io/v1/callback
  - Auth URL: [CognitoDomainUrl]/oauth2/authorize
  - Access Token URL: [CognitoDomainUrl]/oauth2/token
  - Client ID: [UserPoolClientId]
  - Scope: email openid profile

![UnauthorizedGET](/images/blog/cdk-cognito-api-postman/UnauthorizedGET.png)
_Example of unauthorized GET request_

![AuthorizationSetup1](/images/blog/cdk-cognito-api-postman/AuthorizationSetup1.png)
_Authorization tab with Auth Type set to OAuth 2.0_

![AuthorizationSetup2](/images/blog/cdk-cognito-api-postman/AuthorizationSetup2.png)
_Authorization tab Configuring new token_

### **Get Access Token**

- Click "Get New Access Token"
- Log in with your Cognito credentials
- Use the token for API requests

![AuthorizationSetup3](/images/blog/cdk-cognito-api-postman/AuthorizationSetup3.png)
_Click "Get New Access Token"_

![LoginPopup](/images/blog/cdk-cognito-api-postman/LoginPopup.png)
_Login popup_

![AuthenticationComplete](/images/blog/cdk-cognito-api-postman/AuthenticationComplete.png)
_Authentication complete_

![UseToken](/images/blog/cdk-cognito-api-postman/UseToken.png)
_Click "Use Token"_

### **Make API Requests**

- GET [ApiUrl]/hello

![AuthorizedGET](/images/blog/cdk-cognito-api-postman/AuthorizedGET.png)
_Example of authorized GET request_

## Deployment

```bash
yarn
yarn cdk deploy
```

The deployment will output:

- Cognito Domain URL
- User Pool ID
- Client ID
- API Gateway URL
- Hosted UI URL for sign-up
- Auth URL
- Token URL

## Cleanup

```bash
yarn cdk destroy
```


In this demo we will see how to deploy a Cognito protected API and test it with Postman using OAuth 2.0 for authentication and login

CDK Cognito Protected API Demo with Postman

# Building a Private Fargate Task and Lambda

In order to build an AWS Fargate task in a [private subnet](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html) that can still be invoked by a Lambda function, the Lambda function must also be built in the same VPC with access to the private subnet.

![Overview](/images/blog/PrivateLambdaFargate.png)

## GitHub Repo

Full code is available here: https://github.com/schuettc/cdk-private-fargate-with-lambda

## Building the VPC and ALB

```typescript
this.vpc = new Vpc(this, 'VPC', {
  subnetConfiguration: [
    {
      cidrMask: 24,
      name: 'PrivateSubnet',
      subnetType: SubnetType.PRIVATE_WITH_EGRESS,
    },
    {
      cidrMask: 24,
      name: 'PublicSubnet',
      subnetType: SubnetType.PUBLIC,
    },
  ],
  maxAzs: 2,
});
```

Here we are creating a VPC with two types of Subnets - `PRIVATE_WITH_EGRESS` and `PUBLIC`.

```typescript
this.applicationLoadBalancer = new ApplicationLoadBalancer(this, 'alb', {
  vpc: this.vpc,
  vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
  internetFacing: false,
  securityGroup: this.fargateSecurityGroup,
});
```

Next we will create an Application Load Balancer in the `PRIVATE_WITH_EGRESS` subnet.

## Fargate

```typescript
this.fargateService = new ApplicationLoadBalancedFargateService(
  this,
  'fargateService',
  {
    taskImageOptions: {
      image: ContainerImage.fromRegistry('amazon/amazon-ecs-sample'),
      taskRole: fargateTaskRole,
    },
    publicLoadBalancer: false,
    vpc: props.vpc,
    assignPublicIp: false,
    openListener: false,
    loadBalancer: props.applicationLoadBalancer,
    listenerPort: 80,
    taskSubnets: {
      subnetType: SubnetType.PRIVATE_WITH_EGRESS,
    },
    securityGroups: [props.fargateSecurityGroup],
    runtimePlatform: {
      operatingSystemFamily: OperatingSystemFamily.LINUX,
      cpuArchitecture: CpuArchitecture.X86_64,
    },
  },
);
```

Next we will create the Fargate Service and Task, once again assigning it to the `PRIVATE_WITH_EGRESS` subnet using the previously created Application Load Balancer.

## Lambda

```typescript
const fargateLambdaInPrivateVPCwithSG = new NodejsFunction(
  this,
  'fargateLambdaInPrivateVPCwithSG',
  {
    entry: 'src/resources/fargateLambda/index.ts',
    runtime: Runtime.NODEJS_LATEST,
    architecture: Architecture.ARM_64,
    role: lambdaRole,
    timeout: Duration.seconds(60),
    vpc: props.vpc,
    vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
    securityGroups: [lambdaSecurityGroup],
    environment: {
      FARGATE_ALB_URL: props.fargateService.loadBalancer.loadBalancerDnsName,
    },
  },
);
```

Finally, we will create the Lambda function and assign to the `PRIVATE_WITH_EGRESS` subnet.

## Security Groups

In addition to containing the Lambda, Application Load Balancer, and Fargate within the same VPC and private subnet, Security Groups can also be used to restrict access.

```typescript
this.fargateSecurityGroup = new SecurityGroup(this, 'fargateSecurityGroup', {
  vpc: this.vpc,
  description: 'Security Group for Fargate ALB',
});
```

First we will create a Security Group for the Application Load Balancer.

```typescript
const lambdaSecurityGroup = new SecurityGroup(this, 'LambdaSecurityGroup', {
  vpc: props.vpc,
});
```

Next we will create a Security Group for the Lambda function.

```typescript
props.fargateSecurityGroup.connections.allowFrom(
  new Connections({
    securityGroups: [lambdaSecurityGroup],
  }),
  Port.tcp(80),
  'allow traffic on port 80 from the Lambda security group',
);
```

Finally, we will allow a connection from the Lambda Security Group to the Application Load Balancer Security Group. This will allow the Lambda function to make requests to the Fargate Task through the Application Load Balancer. The other two Lambda functions show how this is required as they do not work. The first does not include the correct Security Group and the second does not include the correct VPC subnet.

## Result

Once deployed, the Lambda function in the correct VPC with the correct Security Group will be able to make a request to the Fargate task and get a response:

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <title>Simple PHP App</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link href="assets/css/bootstrap.min.css" rel="stylesheet" />
    <style>
      body {
        margin-top: 40px;
        background-color: #333;
      }
    </style>
    <link href="assets/css/bootstrap-responsive.min.css" rel="stylesheet" />
    
  </head>

  <body>
    <div class="container">
      <div class="hero-unit">
        <h1>Simple PHP App</h1>
        <h2>Congratulations</h2>
        <p>Your PHP application is now running on a container in Amazon ECS.</p>
        <p>The container is running PHP version 5.4.16.</p>
      </div>
    </div>
  </body>
</html>
```

The other Lambda functions will timeout and fail

```text
Task timed out after 60.07 seconds
```

Additionally, the Application Load Balancer URL will only return an RFC 1918 private address:

```bash
$ nslookup internal-Privat-vpcRe-8uesdCpJs6j6-1716194524.us-east-1.elb.amazonaws.com

Non-authoritative answer:
Name:	internal-privat-vpcre-8uesdcpjs6j6-1716194524.us-east-1.elb.amazonaws.com
Address: 10.0.1.253
Name:	internal-privat-vpcre-8uesdcpjs6j6-1716194524.us-east-1.elb.amazonaws.com
Address: 10.0.0.230
```

How to build a private Fargate task and connect to it with an AWS Lambda function using AWS CDK.  

Using CDK to build a Fargate task with AWS Lambda integration


In order to deploy a Python Lambda function with additional dependencies, we must use something that will [install those dependencies](https://packaging.python.org/en/latest/tutorials/managing-dependencies/). With NodeJS, we can use something like [`esbuild`](https://esbuild.github.io/) to do this. In a Typescript CDK, we can use npm or yarn to install this as a [development dependency](https://classic.yarnpkg.com/en/docs/dependency-types#toc-devdependencies). However, we do not have this option with a Python Lambda. To have this built during deployment, we can use the [bundlingOptions interface](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.BundlingOptions.html).

```typescript
this.queryLambda = new Function(this, "QueryLambda", {
  code: Code.fromAsset(path.join(__dirname, "resources/query_lambda"), {
    bundling: {
      image: Runtime.PYTHON_3_9.bundlingImage,
      command: [
        "bash",
        "-c",
        "pip install -r requirements.txt -t /asset-output && cp -au . /asset-output",
      ],
    },
  }),
  runtime: Runtime.PYTHON_3_9,
  vpc: props.vpc,
  vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
  architecture: Architecture.ARM_64,
  handler: "index.handler",
  timeout: Duration.minutes(5),
  role: props.role,
  layers: [props.powerToolsLayer],
  environment: {
    RDS_SECRET_NAME: props.dataBase.secret?.secretName!,
  },
});
```

In [this](https://github.com/schuettc/cdk-private-rds-with-lambda/blob/main/src/lambda.ts) example from the [cdk-private-rds-with-lambda](https://github.com/schuettc/cdk-private-rds-with-lambda) repository, we can see the `QueryLambda` function is being created using `Code` from the `/resources/query_lambda` directory and bundled using a Docker image. This does require Docker desktop to be run locally or from the pipeline that is deploying this function.

When this Lambda function is deployed, `pip install` will be used with the `requirements.txt` file in the `/query_lambda` directory to create the zip file that will be uploaded as the Lambda function.

```bash
resources/
├── initialize_lambda/
│   ├── index.py
│   └── requirements.txt
└── query_lambda/
    ├── index.py
    └── requirements.txt
```


This article will show you how to deploy a Python Lambda function with additional dependencies using CDK

Lambda

CDK Cognito Protected API Demo with Postman

Using CDK to build a Fargate task with AWS Lambda integration

Deploying a Python Lambda with Requirements using CDK