Cognito Users

Amazon Cognito Amazon Cognito
Amazon Cognito — a user authentication service providing user pools, JWT tokens, and group-based authorization. handles user authentication for this project. The user pool uses email as the username, issues JWT tokens, and integrates with API Gateway API Gateway
Amazon API Gateway — a managed HTTP API service with JWT authorization, CORS, and throttling. Routes requests to the Query Lambda. to authorize requests. This page covers the auto-created admin user, manual user management, and how group membership controls API access.

Authentication flow

When a user signs in, the flow works like this:

1. User authenticates against the Cognito user pool from the web UI
2. Cognito returns a JWT (ID token and access token)
3. The web UI includes the token in API requests
4. API Gateway API Gateway
   Amazon API Gateway — a managed HTTP API service with JWT authorization, CORS, and throttling. Routes requests to the Query Lambda. validates the JWT using the Cognito authorizer
5. If valid, the request is forwarded to the appropriate Lambda Lambda
   AWS Lambda — serverless compute. This project uses two functions: ingest (RSS → embed → store) and query (search → answer). function
6. Group claims in the token determine endpoint access (admin vs regular user)

Auto-created admin

When you set cognito_admin_email in your Terraform Terraform
HashiCorp Terraform — infrastructure-as-code tool used to provision all AWS resources in this demo. variables, an admin user is automatically created during terraform apply.

terraform.tfvars

cognito_admin_email = "admin@example.com"

During deployment, Terraform:

1. Creates the user in the Cognito user pool with email verified
2. Adds the user to the admin group
3. Sends a temporary password to the email address

Note

The admin user must change their temporary password on first sign-in. Cognito enforces this with a FORCE_CHANGE_PASSWORD status until the user completes the challenge.

Groups and access control

The project creates a single Cognito group called admin. Group membership determines which API endpoints a user can call.

Group	Endpoint access	Description
admin	POST /ingest and POST /query	Can trigger ingestion and query the system
(no group)	POST /query only	Can query but cannot trigger ingestion

Tip

The admin group claim is included in the JWT token as cognito:groups. API Gateway checks this claim to authorize the POST /ingest route.

Password requirements

The Cognito user pool enforces the following password policy:

• Minimum 8 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one number
• At least one special character

Manual user creation

First, retrieve the user pool ID from Terraform outputs:

POOL_ID="$(terraform output -raw cognito_user_pool_id)"

Create a user

aws cognito-idp admin-create-user \
  --user-pool-id "${POOL_ID}" \
  --username "user@example.com" \
  --user-attributes Name=email,Value=user@example.com Name=email_verified,Value=true \
  --message-action SUPPRESS

The --message-action SUPPRESS flag prevents Cognito from sending a welcome email. Remove it if you want the user to receive their temporary password by email.

Set a permanent password

aws cognito-idp admin-set-user-password \
  --user-pool-id "${POOL_ID}" \
  --username "user@example.com" \
  --password "YourSecurePass12!" \
  --permanent

Caution

The —permanent flag skips the forced password change on first login. Without it, the user must complete the NEW_PASSWORD_REQUIRED challenge before they can use the account.

Add a user to the admin group

aws cognito-idp admin-add-user-to-group \
  --user-pool-id "${POOL_ID}" \
  --username "user@example.com" \
  --group-name "admin"

After adding a user to the admin group, they gain access to POST /ingest on their next sign-in (when a fresh token is issued).

Remove a user from the admin group

aws cognito-idp admin-remove-user-from-group \
  --user-pool-id "${POOL_ID}" \
  --username "user@example.com" \
  --group-name "admin"

Listing users

List all users in the pool

aws cognito-idp list-users \
  --user-pool-id "${POOL_ID}" \
  --output table

List users in the admin group

aws cognito-idp list-users-in-group \
  --user-pool-id "${POOL_ID}" \
  --group-name "admin" \
  --output table

Deleting a user

aws cognito-idp admin-delete-user \
  --user-pool-id "${POOL_ID}" \
  --username "user@example.com"

Caution

User deletion is permanent and immediate. The user loses access to all API endpoints and their tokens are invalidated.

Quick reference

Action	CLI command
Create user	aws cognito-idp admin-create-user
Set password	aws cognito-idp admin-set-user-password
Add to group	aws cognito-idp admin-add-user-to-group
Remove from group	aws cognito-idp admin-remove-user-from-group
List users	aws cognito-idp list-users
List group members	aws cognito-idp list-users-in-group
Delete user	aws cognito-idp admin-delete-user