140 cognito by chnnick · Pull Request #168 · Code-4-Community/scaffolding

chnnick · 2026-05-25T00:37:06Z

ℹ️ Issue

Closes #140

📝 Description

Created an easily-importable NestJS guard that can be used by future projects to implement Cognito Authentication into their application. Amplify on the frontend authenticates users, providing registered users with a JWT access token that can be used to access authorized routes.

Briefly list the changes made to the code:

NestJS guard that checks and verifies the Bearer token in the authorization header via AWS Cognito to determine access onto specific routes, puts the verified token payload under a user field of the request that can be read by other methods.
CognitoService getUser() method that exposes the verified JWT payload attached to the request by the guard
Cognito module that imported into App Module for authentication across entire application
@public decorator that allows one to bypass authentication by putting metadata read by the guard
Interface for an expected JWT payload used by the guard and service
Cognito config that allows for a centralized place to extract env variables for Cognito
Tests for the cognito service and cognito guard
Implemented Amplify on the frontend to show an auth screen and configure auth for the application if frontend cognito env variables are set, if anyfrontend cognito env values are not set, there is no auth screen
Cognito .env variables in example.env that is used by both the backend (Cognito) and frontend (Amplify)
README.md in backend/aws/cognito for new devs/TLs that provides documentation for how the authentication flow works: Authentication in frontend -> Authorization in the backend, as well as how to expand in the future.

✔️ Verification

Backend TESTS:

Frontend TESTS:
No Auth:

With Auth:

🏕️ (Optional) Future Work / Notes

No styling on auth page, can import the @aws-amplify/ui-react/styles.css library on main.tsx to use their premade styling?

NEW: I think that a workshop on Authentication / Authorization would be helpful for future devs, would 100% be up to helping with that! I spent wayyy too much time figuring out the difference between the two and their uses in larger apps like which scaffolding will fork off of.

…added required env keys to example.env, configured amplify in separate auth file only if both environment variables exist/are set.

…igure runs correctly with cognito values as strings.

…array of strings or a single string.

…e (COGNITO_USER_POOL_ID is set), but missing env variables for client_id and cognito_region both should not allow requests to go through

…into 140-Cognito

…into 140-Cognito Note: added necessary packages for aws-amplify. Did not push merged changes that existed inside .nx

…into 140-Cognito

…ffolding into 140-Cognito.

dburkhart07

Amazing! Very educational for me to read through as well!

…or greater accessiblity

… of never type for mock requests

…verifyToken

… default

… any env variables)

…ffolding into 140-Cognito

…autogenerated in vite.config, also set the project root to allow frontend access to root /.env file.

…into 140-Cognito

chnnick · 2026-06-10T20:09:05Z

Fell down an authentication/authorization rabbit hole atm will update with new changes soon for a better approach for an authentication-only module that still allows authorization (RBAC) later down the line

documentation

CognitoJWTPayload to just AccessTokenPayload for accuracy, javadoc comments

…into 140-Cognito

dburkhart07

few small things

dburkhart07 · 2026-06-17T09:29:28Z

+    return;
+  }
+
+  const poolId: string = userPoolId;


nit: we defined these constants at the top of the file, i dont really think we need to define them again here

dburkhart07 · 2026-06-17T09:38:15Z

+
+### Auth model
+
+- **Verification** — `CognitoJWTGuard` is the only component that validates JWTs (signature, issuer, audience). 


CognitoJwtGuard does not validate the audience the way we have it implemented here

dburkhart07 · 2026-06-17T09:39:04Z

+4. **Frontend calls the backend with the access token.** The client attaches it on every request as a header: `Authorization: Bearer <access_token>`.
+
+5. **The Guard checks the token.** `CognitoJWTGuard` runs on every route (it's registered as a global `APP_GUARD`). For each request it:
+   - lets the request through immediately if auth is disabled (Cognito env vars unset or the route is marked `@Public()`)


this makes it seem like Public disables auth. I think you should specify here that specifying a route as public does not disable anything, but rather just makes an easy bypass

dburkhart07 · 2026-06-17T09:41:27Z

+# Note: Leaving any field unset disables auth ENTIRELY
+COGNITO_USER_POOL_ID=us-east-2_AbCdEf123
+COGNITO_CLIENT_ID=4h57k9lmno1pqrstuv2wxyz3ab
+COGNITO_REGION=us-east-2


we really shouldnt specify a specific COGNITO_REGION. This should just be one single AWS_REGION variable the project uses all AWS things for

dburkhart07 · 2026-06-17T09:45:28Z

+  }
+  const normalized = value.trim().toLowerCase();
+  return (
+    normalized !== '' && normalized !== 'null' && normalized !== 'undefined'


normalized will never be null or undefined here.

dburkhart07 · 2026-06-19T07:38:21Z

+    const request = context.switchToHttp().getRequest<Request>();
+    const token = extractBearerToken(request);
+    if (!token) {
+      throw new UnauthorizedException();


Can we give this exception (and the ones below) specific exception messages as well?

dburkhart07 · 2026-06-19T07:41:44Z

+   */
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    // If authentication is not enabled, allow the request to proceed
+    if (!isAuthEnabled()) {


Can we add some form of log here so that the user knows they are bypassing it perhaps?

dburkhart07 · 2026-06-19T07:44:34Z

+  private verifyToken(token: string): Promise<AccessTokenPayload> {
+    // If the region, user pool ID, or client ID is not set, throw an unauthorized exception by default
+    const config = getCognitoConfig();
+    if (!config) {


this will never be hit (if we got to verifyToken we already know auth is enabled)

dburkhart07 · 2026-06-19T07:50:34Z

+  getUser(request: Request): AccessTokenPayload | null {
+    // If authentication is not enabled, return null
+    if (!isAuthEnabled()) {
+      return null;


can we maybe add some logs into these return nulls (and if there is anywhere else this is happening in the module)? that way the user knows whether the issue is cognito being down, or their user actually being unreachable.

dburkhart07 · 2026-06-19T07:53:34Z

+  return (
+    typeof payload.sub === 'string' &&
+    typeof payload.iss === 'string' &&
+    typeof payload.token_use === 'string' &&


should we not check that this is access?

dburkhart07 · 2026-06-19T07:54:08Z

+    typeof payload.iss === 'string' &&
+    typeof payload.token_use === 'string' &&
+    typeof payload.exp === 'number' &&
+    typeof payload.iat === 'number'


should check that this is in the past

dburkhart07 · 2026-06-19T07:54:59Z

+ * @param value - The value to check, typically a decoded JWT payload.
+ * @returns `true` if `value` matches the {@link AccessTokenPayload} shape.
+ */
+export function isAccessTokenPayload(


do we have special checks for the client_id? what about cognito_groups

dburkhart07 · 2026-06-19T07:58:36Z

+  client_id?: string; // Client ID used during authentication (ex: <your client ID>)
+  exp: number; // Expiration time (Unix timestamp)
+  iat: number; // Issued at time (Unix timestamp)
+  email?: string; // Email (ex: test@example.com)


what do we need this field for? i dont think access tokens normally send email addresses through that. i think the verify in jwt.strategy doesnt even need the email.

chnnick added 11 commits May 15, 2026 15:15

wrap app in authenticator if cognito information is set in env file, …

918f560

…added required env keys to example.env, configured amplify in separate auth file only if both environment variables exist/are set.

correctly importing env variables, type guards for each value so conf…

94a3b9e

…igure runs correctly with cognito values as strings.

new cognito env variables, JWTPayload type

dd53297

cognito config + updated types to allow for both id and access tokens

c222613

cognito guard, module, and decorators, added to appmodule

e61d789

tests for guard and service

765e65c

documentation

118ed9b

move auth into the correct folder

b3d9471

warnings for dual usage of Cognito

557f6f9

widen aud type to allow for serialization of the aud claim as either …

1e94607

…array of strings or a single string.

updated documentation

f2b0716

chnnick requested a review from maxn990 as a code owner May 25, 2026 00:37

chnnick added 5 commits May 24, 2026 17:44

tests clarification for denying partial configurations: Auth is activ…

81729d4

…e (COGNITO_USER_POOL_ID is set), but missing env variables for client_id and cognito_region both should not allow requests to go through

Merge branch 'main' of https://github.com/Code-4-Community/scaffolding …

fd9f237

…into 140-Cognito

Merge branch 'main' of https://github.com/Code-4-Community/scaffolding …

e4e878a

…into 140-Cognito Note: added necessary packages for aws-amplify. Did not push merged changes that existed inside .nx

Merge branch 'main' of https://github.com/Code-4-Community/scaffolding …

57c2553

…into 140-Cognito

Merge branch '140-Cognito' of https://github.com/Code-4-Community/sca…

f78c0e7

…ffolding into 140-Cognito.

dburkhart07 requested changes May 28, 2026

View reviewed changes

chnnick added 12 commits May 29, 2026 16:58

Cognito Module as a global import, export CognitoJWTGuard in module f…

65d940c

…or greater accessiblity

require all three Cognito env variables to enable authentication

fc6d8ec

wrapped getUser tests into describe(), use Request type alias instead…

4f3d4f1

… of never type for mock requests

use cached jswk client for jwks, typed the payload that returns from …

ad13e14

…verifyToken

updated documentation after importing CognitoModule into AppModule by…

167141a

… default

updated documentation to match new auth disable requirements (missing…

378435b

… any env variables)

updated tests for missing env variables -> auth disabled

35a5127

try to just use cognitoinformationpresent

2b96133

type vite cognito env vars before passing into amplify.configure

cd44f7a

Merge branch '140-Cognito' of https://github.com/Code-4-Community/sca…

0253089

…ffolding into 140-Cognito

get rid of VITE specific cognito variables in .env instead have them …

146b271

…autogenerated in vite.config, also set the project root to allow frontend access to root /.env file.

Merge branch 'main' of https://github.com/Code-4-Community/scaffolding …

b579463

…into 140-Cognito

chnnick added 4 commits June 2, 2026 16:10

check for cognito region when turning on auth in the frontend

960951e

Merge branch 'main' of https://github.com/Code-4-Community/scaffolding …

65b5ba8

…into 140-Cognito

specify frontend root for vite

9dbd28c

type guard + make token_use a required field -> strict token checking

cba88c4

chnnick added 7 commits June 11, 2026 14:29

README with new auth flow for newbies, updated access token only

614ae40

documentation

tokens clarification

a3c374c

get rid of id token in jwtpayload checks for the backend, rename

ac27824

CognitoJWTPayload to just AccessTokenPayload for accuracy, javadoc comments

updated tests with new groupings

e13d23c

Merge branch 'main' of https://github.com/Code-4-Community/scaffolding …

e0d28e9

…into 140-Cognito

rename new payload type in readme

57834c9

typo

836bb28

maxn990 requested a review from dburkhart07 June 16, 2026 13:36

dburkhart07 requested changes Jun 17, 2026

View reviewed changes

dburkhart07 requested changes Jun 19, 2026

View reviewed changes


		### Auth model

		- Verification — `CognitoJWTGuard` is the only component that validates JWTs (signature, issuer, audience).

Conversation

chnnick commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ℹ️ Issue

📝 Description

✔️ Verification

🏕️ (Optional) Future Work / Notes

Uh oh!

dburkhart07 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chnnick commented Jun 10, 2026

Uh oh!

dburkhart07 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

chnnick commented May 25, 2026 •

edited

Loading