feat: Introduce AuthModule for handling authorization and authentication through OIDC

Author: spuxx-dev

apps/nest/src/app.controller.test.ts

@@ -1,14 +1,14 @@
 import { AppController } from './app.controller';
-import { AppService } from './app.service';
 import { TestContainer, Supertest } from '@spuxx/nest-utils';
+import { authConfig, AuthRole } from './auth/auth.config';
 
 describe('AppController', () => {
   let supertest: Supertest;
 
   beforeEach(async () => {
     const container = await TestContainer.create({
       controllers: [AppController],
-      providers: [AppService],
+      authOptions: authConfig,
       enableEndToEnd: true,
     });
     supertest = container.supertest;
@@ -18,7 +18,33 @@ describe('AppController', () => {
     it('should be successful', async () => {
       const response = await supertest.get('/');
       expect(response.statusCode).toBe(200);
-      expect(response.text).toContain('Hello!');
+      expect(response.body.message).toBe('Hello there!');
+    });
+  });
+
+  describe('protected', () => {
+    it('should be successful', async () => {
+      const response = await supertest.get('/protected', {
+        session: {
+          sub: '123',
+          realm_access: { roles: [AuthRole.user] },
+        },
+      });
+      expect(response.statusCode).toBe(200);
+    });
+
+    it('should return 401', async () => {
+      const response = await supertest.get('/protected');
+      expect(response.statusCode).toBe(401);
+    });
+
+    it('should return 403', async () => {
+      const response = await supertest.get('/protected', {
+        session: {
+          sub: '123',
+        },
+      });
+      expect(response.statusCode).toBe(403);
     });
   });
 });

apps/nest/src/app.controller.ts

@@ -1,12 +1,32 @@
-import { Controller, Get } from '@nestjs/common';
-import { AppService } from './app.service';
+import { Controller, Get, Req, UseGuards } from '@nestjs/common';
+import { EnvModule } from './env/env.module';
+import type { Request } from 'express';
+import { AuthGuard, Roles } from 'packages/nest-utils/dist/main';
+import { AuthRole } from './auth/auth.config';
 
 @Controller()
 export class AppController {
-  constructor(private readonly service: AppService) {}
-
   @Get()
-  getHello(): string {
-    return this.service.getHello();
+  getHello(@Req() request: Request): object {
+    const response = {
+      message: 'Hello there!',
+      time: new Date().toLocaleTimeString(),
+      session: request.oidc.user ? `Logged in as ${request.oidc.user.name}` : 'Not logged in',
+      routes: {
+        auth: {
+          login: `${EnvModule.get('APP_BASE_URL')}/auth/login`,
+          logout: `${EnvModule.get('APP_BASE_URL')}/auth/logout`,
+          session: `${EnvModule.get('APP_BASE_URL')}/auth/session`,
+        },
+      },
+    };
+    return response;
+  }
+
+  @Get('/protected')
+  @UseGuards(AuthGuard)
+  @Roles(AuthRole.user)
+  getProtectedHello(@Req() request: Request) {
+    return `Oh hello there, ${request.oidc.user.name}! This route is protected, but you can see it! Not bad!`;
   }
 }

apps/nest/src/app.module.test.ts

@@ -0,0 +1,12 @@
+import { TestContainer } from 'packages/nest-utils/dist/main';
+import { AppModule } from './app.module';
+
+describe('AppModule', () => {
+  it('should be ok', async () => {
+    vitest.stubEnv('AUTH_CLIENT_SECRET', 'something');
+    const container = await TestContainer.create({
+      imports: [AppModule],
+    });
+    expect(container.module).toBeDefined();
+  });
+});

apps/nest/src/app.module.ts

@@ -1,13 +1,11 @@
 import { Module } from '@nestjs/common';
 import { AppController } from './app.controller';
-import { AppService } from './app.service';
+import { AuthModule } from '@spuxx/nest-utils';
 import { EnvModule } from './env/env.module';
+import { authConfig } from './auth/auth.config';
 
 @Module({
-  imports: [
-    EnvModule,
-  ],
+  imports: [EnvModule, AuthModule.forRoot(authConfig)],
   controllers: [AppController],
-  providers: [AppService],
 })
 export class AppModule {}

apps/nest/src/app.service.ts

@@ -0,0 +1,20 @@
+import { AuthOptions } from 'packages/nest-utils/dist/main';
+import { EnvModule } from '../env/env.module';
+
+export const AuthRole = {
+  user: 'test_user',
+} as const;
+export type AuthRole = (typeof AuthRole)[keyof typeof AuthRole];
+export const authRoles = Object.values(AuthRole);
+
+export const authConfig: AuthOptions = {
+  disable: false,
+  roles: AuthRole,
+  oidc: {
+    baseURL: EnvModule.get('APP_BASE_URL'),
+    issuerBaseURL: EnvModule.get('AUTH_ISSUER_URL'),
+    clientID: EnvModule.get('AUTH_CLIENT_ID'),
+    clientSecret: EnvModule.get('AUTH_CLIENT_SECRET'),
+    secret: EnvModule.get('AUTH_CLIENT_SECRET'),
+  },
+};

apps/nest/src/auth/auth.config.ts

@@ -1,9 +1,20 @@
-import { IsDate, IsString } from 'class-validator';
+import { IsIn, IsString, IsUrl } from 'class-validator';
+import { ApplicationLogLevel } from 'packages/nest-utils/dist/main';
 
 export class Environment {
   @IsString()
-  APP_NAME: string = 'nest';
+  @IsIn(Object.values(ApplicationLogLevel))
+  APP_LOG_LEVEL: ApplicationLogLevel = ApplicationLogLevel.Default;
 
-  @IsDate()
-  START_TIME: Date;
+  @IsString()
+  APP_BASE_URL: string = 'http://localhost:3000';
+
+  @IsUrl()
+  AUTH_ISSUER_URL: string = 'https://auth.spuxx.dev/realms/spuxx/';
+
+  @IsString()
+  AUTH_CLIENT_ID: string = 'test';
+
+  @IsString()
+  AUTH_CLIENT_SECRET: string;
 }

apps/nest/src/auth/config/auth.config.ts

@@ -1,15 +1,23 @@
+import { Logger } from '@nestjs/common';
 import { NestFactory } from '@nestjs/core';
+import { CustomLogger, AuthModule } from '@spuxx/nest-utils';
 import { AppModule } from './app.module';
-import { Logger } from '@nestjs/common';
+import { authConfig } from './auth/auth.config';
+import { EnvModule } from './env/env.module';
 
 async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
+  const logger = new CustomLogger({
+    logLevel: EnvModule.get('APP_LOG_LEVEL'),
+  });
+  const app = await NestFactory.create(AppModule, {
+    logger,
+  });
+
+  AuthModule.bootstrap(app, authConfig);
+
+  await app.listen(3000);
   Logger.log(`Application is running on: http://localhost:3000`, 'Bootstrap');
-  // Required, see: https://www.npmjs.com/package/vite-plugin-node#get-started
-  if (import.meta.env.PROD) {
-    await app.listen(3000);
-  }
-  return app;
+  Logger.verbose('Verbose logging is enabled.', 'Bootstrap');
 }
 
-export const app = bootstrap();
+bootstrap();

apps/nest/src/env/env.definiton.ts

@@ -46,19 +46,21 @@
     "@nestjs/common": "^8.0.0 || ^9.0.0 || ^10.0.0",
     "@nestjs/config": "^3.0.0",
     "@nestjs/core": "^8.0.0 || ^9.0.0 || ^10.0.0",
+    "@nestjs/swagger": "^7.0.0",
     "@nestjs/testing": "^8.0.0 || ^9.0.0 || ^10.0.0",
     "class-transformer": "^0.5.0",
     "class-validator": "^0.14.0",
+    "express-openid-connect": "^2.17.1",
     "reflect-metadata": "^0.1.13 || ^0.2.0",
-    "supertest": "^7.0.0",
-    "express-openid-connect": "^2.17.1"
+    "supertest": "^7.0.0"
   },
   "peerDependenciesMeta": {
     "express-openid-connect": {
       "optional": true
     }
   },
   "dependencies": {
+    "@nanogiants/nestjs-swagger-api-exception-decorator": "^1.6.11",
     "@spuxx/js-utils": "workspace:@spuxx/js-utils@*"
   }
 }

apps/nest/src/main.ts

@@ -0,0 +1,78 @@
+import { DynamicModule, INestApplication, Logger, Module } from '@nestjs/common';
+import { defaultAuthOptions, type AuthOptions } from '../main';
+import { auth } from 'express-openid-connect';
+import { AuthController } from './controllers/auth.controller';
+import { AuthService } from './providers/auth.service';
+import { deepMerge } from 'packages/js-utils/dist/main';
+import { AuthOptionsProvider } from './providers/auth-options.provider';
+
+/**
+ * The authentication module. This module is responsible for handling authentication and
+ * authorization. It is based on the `express-openid-connect?` library and is intended
+ * for use with an OIDC provider.
+ * @example
+ * // main.ts
+ * import { AuthModule, AuthOptions } from '@nestjs-oidc/core';
+ * const authConfig: AuthOptions = {
+ *   // This is the minimum set of options you need to provide
+ *   roles: {
+ *     admin: "admin",
+ *     user: "user",
+ *     // ... more roles ...
+ *   },
+ *   oidc: {
+ *     issuerBaseURL: 'https://example.com',
+ *     baseURL: 'http://localhost:3000',
+ *     clientID: 'client-id',
+ *     clientSecret: 'client-secret',
+ *     secret: 'session-secret',
+ *   }
+ * }
+ * await AuthModule.bootstrap(app, authConfig);
+ *
+ * // app.module.ts
+ * import { AuthModule } from '@nestjs-oidc/core';
+ * ＠Module({
+ *   imports: [AuthModule.forRoot(authConfig)],
+ * })
+ * export class AppModule {}
+ */
+@Module({})
+export class AuthModule {
+  /**
+   * Bootstraps authentication. This must be called during application bootstrapping.
+   * @param app The Nest application instance.
+   * @param options The authentication options.
+   */
+  static async bootstrap(app: INestApplication, options: AuthOptions) {
+    const mergedOptions = this.mergeOptionsWithDefaultValues(options);
+    const { disable, oidc } = mergedOptions;
+    if (disable) {
+      Logger.warn('Authentication is disabled. All routes will be accessible.', AuthModule.name);
+      return;
+    }
+    app.use(auth(oidc));
+    Logger.log(`Authentication is enabled and will be handled by issuer at '${oidc.issuerBaseURL}'.`, AuthModule.name);
+  }
+
+  static forRoot(options: AuthOptions): DynamicModule {
+    return {
+      module: AuthModule,
+      controllers: [AuthController],
+      providers: [
+        AuthService,
+        {
+          provide: AuthOptionsProvider,
+          useValue: new AuthOptionsProvider(this.mergeOptionsWithDefaultValues(options)),
+        },
+      ],
+      exports: [AuthService, AuthOptionsProvider],
+    };
+  }
+
+  static mergeOptionsWithDefaultValues(options: AuthOptions) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mergedOptions = deepMerge(defaultAuthOptions as any, options as any) as unknown as AuthOptions;
+    return mergedOptions;
+  }
+}

packages/nest-utils/package.json

@@ -0,0 +1,20 @@
+import { BadRequestException, UnauthorizedException } from '@nestjs/common';
+
+export const authExceptions = {
+  login: {
+    badRequest: new BadRequestException(),
+    forbiddenReturnTo: new BadRequestException(
+      "The value of 'returnTo' is not allowed. Redirect URLs must match the allowed CORS origins or specific application endpoints. The URL must be absolute!",
+    ),
+    urlParsingError: new BadRequestException('An error occurred while parsing the redirect URL.'),
+  },
+  session: {
+    unauthorized: new UnauthorizedException(),
+  },
+  logout: {
+    badRequest: new BadRequestException(),
+    forbiddenReturnTo: new BadRequestException(
+      "The value of 'returnTo' is not allowed. Redirect URLs must match the allowed CORS origins or specific application endpoints.",
+    ),
+  },
+};

packages/nest-utils/src/auth/auth.module.ts

@@ -0,0 +1,61 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+import { ConfigParams as ExpressOidcConfig } from 'express-openid-connect';
+
+export interface AuthOptions {
+  /**
+   * Whether authentication should be disabled.
+   * @default false
+   */
+  disable?: boolean;
+  /**
+   * The list of external URLs the service is allowed to redirect to after login or logout.
+   * Local redirects are always allowed.
+   * @default []
+   */
+  allowedRedirectUrls?: string[];
+  /**
+   * The URL that should be used as the default redirect URL after login or logout.
+   * @default 'auth/session'
+   */
+  defaultRedirectUrl?: string;
+  /**
+   * The record of roles available in the application.
+   */
+  roles?: Record<string, string>;
+  /**
+   * Configuration parameters passed to `express-openid-connect`. For documentation, see:
+   * https://auth0.github.io/express-openid-connect/interfaces/ConfigParams.html
+   */
+  oidc: ExpressOidcConfig;
+}
+
+type DefaultAuthOptions = Partial<Omit<AuthOptions, 'oidc'>> & Pick<AuthOptions, 'oidc'>;
+
+/**
+ * Default values for the authentication options.
+ */
+export const defaultAuthOptions: DefaultAuthOptions = {
+  disable: false,
+  allowedRedirectUrls: [],
+  defaultRedirectUrl: '/',
+  oidc: {
+    errorOnRequiredAuth: true,
+    authRequired: false,
+    auth0Logout: false,
+    idpLogout: true,
+    enableTelemetry: false,
+    authorizationParams: {
+      response_type: 'code',
+      response_mode: 'query',
+      scope: 'openid profile email roles',
+    },
+    session: {
+      name: `${process.env.npm_package_name}-session`,
+    },
+    routes: {
+      login: false, // Is overwritten in AuthController
+      logout: false, // Is overwritten in AuthController
+      callback: '/auth/callback',
+    },
+  },
+};