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: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

should I just leave the other fields empty as well?? I'll update the comment to say "empty or missing" instead of "unset" as well

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?

I added a specific message to this one specific exception regarding a missing bearer token in a commit, but imo i think it'd be better to leave the exceptions that are thrown when validating the jwt to be general unauthorized exceptions that dont reveal internal information.

Added logging for the exception information instead ^

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?

I can add server side logging, but I think its unecessary to add client-visible logging to tell the user they are bypassing authentication? Might be misunderstanding this request

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: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

hmm, not sure what you mean by the past? jwt.verify will check for expired tokens though and return err on the guard.

checks

logging for debugging Cognito errors, added exception message for missing bearer token

dburkhart07

hopefully some last comments. c4c security is becoming so good!!!!!!

dburkhart07 · 2026-07-07T08:24:28Z

+}
+
+// Checks if the value is a non-empty string
+function isNonEmptyEnv(value: string | undefined): value is string {


wonder if we could convert this to a utils function in a separate utils folder. seems like it could be useful elsewhere too.

agreed, can do so

dburkhart07 · 2026-07-07T08:31:27Z

+}
+
+// Check if the cognito information is present in the environment variables
+export const cognitoInformationPresent =


can we just make this a function just like the backend, and call that the same way?

dburkhart07 · 2026-07-07T08:34:21Z

+    return null;
+  }
+
+  return {


im currently getting an error with these strings potentially being undefined. we should just do a regular check for all 3 variables of !isNonEmptyEnv

dburkhart07 · 2026-07-07T08:37:01Z

      isGlobal: true,
    }),
    TypeOrmModule.forRoot(AppDataSource.options),
+    CognitoModule,


not quite sure how you would do it. but we should add a specific check that, if we have some of the env variables set (e.g. pool id and region, but not client id), we should be throwing an error on startup, rather than making everything public. probably a good security practice

dburkhart07 · 2026-07-07T08:40:17Z

+}
+
+// Checks if the value is a non-empty string
+function isNonEmptyEnv(value: string | undefined): value is string {


we should make this function the exact same thing as the frontend as well, so we can reject null entries and dont have to worry at all about the frontend and backend disagreeing about whether auth is enabled or not.

dburkhart07 · 2026-07-07T08:43:53Z

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


can we move this all to the cognito guard? this isnt really a defined type, which is a bit misleading.

dburkhart07 · 2026-07-07T08:48:17Z

@@ -0,0 +1,40 @@
+// Checks if the authentication is enabled
+export function isAuthEnabled(): boolean {


the way we have this setup right now, we will run into issues with strict null checks, this file wont compile. we should make isAuthEnabled simply check that getCognitoConfig !== null

dburkhart07 · 2026-07-07T08:53:09Z


+# AWS Cognito
+# Note: Leaving any field empty or missing disables auth ENTIRELY
+COGNITO_USER_POOL_ID=


should add something here to make it clear to never put a secret in one of the VITE env variables, since these are client-facing. Setting one of these to a secret value means it gets exposed to anyone using the site. just a good cautionary measure to take.

dburkhart07 · 2026-07-07T09:00:37Z

+import { APP_GUARD } from '@nestjs/core';
+import { CognitoService } from './cognito.service';
+
+@Global()


i think, for modules that rely on env variables to function entirely (so all of our aws modules), we should be validating the env variables at compile time. can we change this to rather use something like this:

export class CognitoModule implements OnModuleInit { private readonly logger = new Logger(CognitoModule.name); onModuleInit() { const config = isAuthEnabled(); if (config === null) { this.logger.warn('Cognito auth disabled: no env vars set. All routes open.'); } else { this.logger.log(`Cognito auth enabled for pool ${config.userPoolId}`); } } }

while you are at it, would you mind making this change for the s3 and ses, where we would check the specific env variables that we need to check for ses being enabled, and s3 being enabled?

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

chnnick added 7 commits June 24, 2026 08:18

get rid of duplicate retyping and redeclaration for configuring amplify

e1de5b5

README clarification + typos, got rid of redundant/useless env variable

ffd6467

checks

correct typecheck for cognito:groups and client_id, removed email field.

b053755

logging for debugging Cognito errors, added exception message for missing bearer token

Update README.md

58d44df

Update example.env

a3c68ff

logs for debugging getUser returned nulls

0f8d751

move internal warning for checking if auth is enabled to the contructor

c3ace83

dburkhart07 requested changes Jul 7, 2026

View reviewed changes

		@@ -0,0 +1,40 @@
		// Checks if the authentication is enabled
		export function isAuthEnabled(): boolean {

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

chnnick commented May 25, 2026 •

edited

Loading

chnnick Jun 24, 2026 •

edited

Loading

chnnick Jun 24, 2026 •

edited

Loading