🔐Secure API Gateway with Cognito Authorizer

Introduction

AWS Cognito

AWS Cognito là một dịch vụ được quản lý bởi Amazon Web Services (AWS), chuyên dùng để xác thực (authentication) và phân quyền truy cập (authorization) cho người dùng. Thay vì bạn phải tự xây dựng toàn bộ hệ thống đăng nhập, quản lý tài khoản, và bảo vệ API, thì Cognito giúp bạn làm điều đó một cách nhanh chóng, bảo mật và chuẩn hóa. Cognito gồm 2 thành phần chính:

• Cognito User Pool – Quản lý người dùng và xác thực

  • Dùng để đăng ký, đăng nhập, xác thực người dùng và cấp JWT tokens (ID, Access, Refresh).
  • Ngoài ra, User Pool hỗ trợ các tính năng mở rộng như:
    • Xác thực đa yếu tố (MFA)
    • Đăng nhập không cần mật khẩu (passwordless)
    • Đăng nhập bằng email, số điện thoại, mạng xã hội (Google, Apple, v.v.)
    • SSO qua SAML/OIDC
    • Tích hợp tốt với API Gateway, Lambda, IAM và các dịch vụ AWS khác

• Cognito Identity Pool – Phân quyền truy cập tài nguyên AWS

  • Cho phép người dùng đã xác thực (từ User Pool, SAML, Google, Facebook, v.v.) được gán IAM roles để truy cập tài nguyên AWS như: Amazon S3, Amazon DynamoDB.

Cơ chế hoạt động cuả Cognito Authorizer

Một trong những tính năng mạnh mẽ của Cognito là có thể hoạt động như một authorizer cho API Gateway.

• Khi người dùng đăng nhập thành công vào Cognito (qua giao diện frontend hoặc Postman), họ sẽ nhận được một cặp token – Access Token và ID Token.
• Những token này đại diện cho danh tính của người dùng và sẽ được đính kèm vào phần “Authorization” của HTTP request khi gọi API.
• API Gateway sẽ dùng Cognito Authorizer để kiểm tra token đó. Nếu token hợp lệ, request sẽ được chuyển tiếp đến backend (ví dụ như Lambda, S3, v.v). Nếu token không hợp lệ hoặc thiếu, request sẽ bị từ chối ngay tại API Gateway và trả lỗi 401 Unauthorized.

Lab Introduction

• AWS experience: Intermediate
• Time to complete:  30 minutes
• AWS Region: US East (N. Virginia) us-east-1
• Services used: Cognito, API Gateway, Lambda

Architecture

Trong bài lab này, chúng ta sẽ từng bước xây dựng một hệ thống API được bảo vệ bằng Cognito Authorizer, từ việc tạo một Lambda function đơn giản để xử lý logic backend – đây sẽ là đích đến của các request thông qua API Gateway. Tiếp theo, bạn sẽ tạo một Cognito User Pool để quản lý người dùng và xác thực với Passwordless. Sau đó, sẽ triển khai một REST API Gateway, tích hợp với Lambda vừa tạo. Tiếp theo, sẽ cấu hình Cognito Authorizer trên API Gateway để xác thực các request dựa trên JWT token do Cognito phát hành. Khi cấu hình xong, sẽ tạo một user trong Cognito User Pool, và dùng Postman để mô phỏng quá trình đăng nhập, lấy token, và gọi API – xác minh rằng hệ thống hoạt động đúng như mong đợi: chỉ những request có token hợp lệ mới được phép truy cập API.

Task Details

1. Create Lambda function
2. Create Cognito User Pool
   • Create User Pool
   • Configure Passwordless Authentication
3. Create REST API Gateway
4. Configure Cognito Authorizer
   • Create Cognito Authorizer
   • Configure Cognito authorizer for method request
   • Deploy API Gateway
5. Create a user in user pool
6. Test API with Postman
   • Test Api without access token
   • Test Api with access token
7. Clean up

1. Create Lambda function

• Author from scratch
• Basic information
  • Function name: d-lambda-nonvpc-cmp-demo-function
  • Runtime: Python 3.13
  • Architecture: x86_64
  • Execution role: Create a new role with basic Lambda permissions
• Create function

2. Create Cognito User Pool

2.1 Create User Pool

Tại Amazon Cognito Console -> Menu User pools -> Click Create user pool

• Define your application
  • Application type: Single-page application (SPA)
  • Name your application: d-cognito-spa-app
• Configure options
  • Options for sign-in identifiers: Email
• Create user directory

• Sau khi tạo user pool xong, vào user pool vừa tạo -> Menu Overview -> Click Rename
• Đổi tên User pool name: d-user-pool-demo

2.2 Configure Passwordless Authentication

Tại Menu Sign-in -> Options for choice-based sign-in -> Click Edit

• Additional choices: Email message one-time password

Đã config xong tính năng đăng nhập Passwordless dùng Email OTP để xác thực.

3. Create REST API Gateway

Vào API Gateway Console -> APIs -> Create API -> REST API -> Build

API details:

• New API
• API name: d-apigw-cmp-demo
• API endpoint type: Regional

Tạo resource: demo

Create Resource

Method details

• Method type: GET
• Intergration Type: Lambda Funciton
• Lambda proxy integration: Enable
• Lambda :
  • Region: us-east-1
  • Function: d-lambda-nonvpc-cmp-demo-function

Test API Gateway

Tại Resources /demo-> Method GET-> Chọn tab Test -> Click Test

Kết quả test thành công: Status 200 và Response body trả về "Hello from Lambda!"

4. Configure Cognito Authorizer

4.1 Create Cognito Authorizer

Vào Authorizers -> Create an authorizer

Authorizer details

• Authorizer name: d-authorizer-user-pool-demo
• Authorizer type: Cognito
• Cognito user pool: Enable
  • Region: us-east-1
  • user pool: d-user-pool-demo
• Token source: Authorization
• Create authorizer

4.2 Configure Cognito authorizer for method request

Tại Resources /demo-> Method GET-> Chọn tab Method request -> Click Edit

• Authorization: d-authorizer-user-pool-demo
• Authorization scopes: aws.cognito.signin.user.admin

Kết quả sau khi đã hoàn tất việc config Cognito authorizer cho method GET

4.3 Deploy API Gateway

Tại Resources /demo-> Click Deploy API

• Stage name: dev

5. Create a user in user pool

Vào d-user-pool-demo đã tạo ở bước 2.1 -> Users -> Click Create user

User information

• Invitation message:Don't send an invitation
• Email address:Nhập địa chỉ email và chọn Mark email address as verified
• Temporary password: Don't set a password

Đã tạo user thành công!

6. Test API with Postman

Bạn có thể sử dụng 1 tool test API online như reqbin.com. Ở bài demo này mình dùng Postman.

6.1 Test Api without access token

Chúng ta sẽ gọi API mà không kèm theo AccessToken để xem kết quả

• URL: API Gateway Invoke URL + /demo
• Content: JSON
• Method: GET

Kết quả trả về là 401 (Unauthorized) "message": "Unauthorized" - không có quyền call API.

6.2 Test Api with access token

Chúng ta sẽ đăng nhập để lấy AccessToken sau đó sẽ gọi lại API kèm theo AccessToken

• Log in
  • URL: https://cognito-idp.us-east-1.amazonaws.com/
  • X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth
  • Content-Type: application/x-amz-json-1.1
  • Method: POST
  • Body:
    • Copy nội dung bên dưới và thay thế các giá trị sau:
      • Thay ClientId bằng Cognito App Client ID của bạn tạo trước đó
      • Thay USERNAME bằng email đã tạo user trước đó

{
    "ClientId": "fpe9go9vfi94f0efq9vnuljnh",
    "AuthFlow": "USER_AUTH",
    "AuthParameters": {
        "USERNAME": "abcxyz@gmail.com",
        "PREFERRED_CHALLENGE": "EMAIL_OTP"
    }
}

Sau khi gửi Request log in sẽ nhận được response chứa Session và mail chứa authentication code, và 2 giá trị này dùng để gửi Request Confirm Log in ở bước tiếp theo.

• Confirm Log in
  • URL: https://cognito-idp.us-east-1.amazonaws.com/
  • X-Amz-Target: AWSCognitoIdentityProviderService.RespondToAuthChallenge
  • Content-Type: application/x-amz-json-1.1
  • Method: POST
    • Copy nội dung bên dưới và thay thế các giá trị sau:
      • Thay ClientId bằng Cognito App Client ID của bạn tạo trước đó
      • Thay USERNAME bằng email đã tạo user trước đó
      • Thay EMAIL_OTP_CODE bằng authentication code nhận từ email bạn vừa nhận được
      • Thay Session bằng session từ response của log in trước đó

{
    "ClientId": "fpe9go9vfi94f0efq9vnuljnh",
    "ChallengeName": "EMAIL_OTP",
    "ChallengeResponses": {
        "USERNAME": "abcxyz@gmail.com",
        "EMAIL_OTP_CODE": "05578005"
    },
    "Session": "AYABeP5T0ATHVJ3yoKb6dISNZ_kAHQABAAdTZXJ2a..."
}

Sau khi gửi Request confirm log in sẽ nhận được response có chứa Access Token và ID Token, v.v

• Test api with access token
  • URL: API Gateway Invoke URL + /demo
  • Authorization: AccessToken từ response trả về của confirm log in
  • Content: JSON
  • Method: GET

Kết quả test thành công: Status 200 OK và Response body trả về "Hello from Lambda!"

7. Clean up

• Delete Lambda Function
• Delete API Gateway
• Delete Cognito User pool

Challenge

Bây giờ bạn đã hiểu cách bảo vệ API bằng Cognito Authorizer rồi, hãy thử nâng tầm bảo mật với những thử thách thực chiến sau:

• Ẩn API Gateway, ngăn người dùng truy cập trực tiếp API Gateway thông qua default URL, chỉ cho phép gọi API thông qua CloudFront – từ đó dễ dàng kết hợp geo restriction, WAF, và custom domain để bảo mật và tối ưu hiệu năng.
• Tự động refresh token trên frontend: tránh tình trạng user bị logout khi JWT token hết hạn bằng cách sử dụng Cognito RefreshToken flow để tự động gọi lại InitiateAuth, đảm bảo trải nghiệm mượt mà cho các SPA như Netflix hoặc Spotify.
• Khám phá các phương án Authorizer khác ngoài Cognito
  • Lambda Authorizer (trước đây là Custom Authorizer): cho phép viết logic tùy chỉnh
  • IAM-based authorization: phù hợp cho nội bộ, sử dụng Signature v4 để cấp quyền truy cập API Gateway dựa trên IAM role hoặc user

Tổng Kết

Qua bài lab này, chúng ta đã từng bước xây dựng một hệ thống API được bảo vệ toàn diện bằng Cognito Authorizer:

• Xây dựng backend Lambda function để xử lý logic – là nơi tiếp nhận các request hợp lệ.
• Tạo Cognito User Pool để quản lý danh tính người dùng và thực hiện xác thực.
• Triển khai REST API Gateway kết nối với Lambda, làm cầu nối giữa client và backend.
• Cấu hình Cognito Authorizer để API Gateway kiểm tra JWT token và chỉ cho phép truy cập khi token hợp lệ.
• Tạo người dùng, đăng nhập và test bằng Postman để mô phỏng quy trình thực tế từ authentication đến authorization.

Kết luận: Cognito Authorizer chính là "người gác cổng thông minh" cho API Gateway, biến những dòng JWT khô khan thành lớp bảo vệ API mạnh mẽ và chuẩn best practice AWS – tất cả đều gói gọn trong vài bước config.

Tài liệu Tham khảo:

• https://repost.aws/knowledge-center/api-gateway-cognito-user-pool-authorizer
• https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-accessing-resources-api-gateway-and-lambda.html
• https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html
• https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html
• https://dev.classmethod.jp/articles/tried-using-cognito-as-api-gateway-authorizer/
• https://qiita.com/zumax/items/2d7eb1ffa49441eb988a