Feat/saml auth

.github/workflows/e2e-ui-tests.yml

@@ -26,6 +26,15 @@ jobs:
         image: rroemhild/test-openldap
         ports:
           - 10389:10389
+      mocksaml:
+        image: boxyhq/mock-saml
+        ports:
+          - 4000:4000
+        env:
+          APP_URL: http://localhost:4000
+          ENTITY_ID: http://localhost:4000/heimdall-local
+          PUBLIC_KEY: ${{ secrets.MOCKSAML_PUBLIC_KEY }}
+          PRIVATE_KEY: ${{ secrets.MOCKSAML_PRIVATE_KEY }}
       splunk:
         image: splunk/splunk
         volumes:

apps/backend/README.md

@@ -1,5 +1,7 @@
 # Heimdall Backend
 
+Logos used by this project are sourced from SVG Repo and are covered by the Logo License or MIT License: https://www.svgrepo.com/page/licensing/
+
 Create the database by setting the appropriate environment variables found in `.env-example` in `.env`
 
 Run the following to create, migrate, and seed the database:

apps/backend/package.json

@@ -39,6 +39,7 @@
     "@nestjs/schematics": "^11.0.0",
     "@nestjs/sequelize": "^11.0.0",
     "@nestjs/serve-static": "^5.0.3",
+    "@node-saml/passport-saml": "^5.1.0",
     "@types/connect-pg-simple": "^7.0.0",
     "@types/express": "^5.0.0",
     "@types/express-session": "^1.17.3",

apps/backend/src/authn/authn.controller.ts

@@ -172,6 +172,27 @@ export class AuthnController {
     await this.setSessionCookies(req, session);
   }
 
+  @Get('saml')
+  @UseFilters(new AuthenticationExceptionFilter())
+  @UseGuards(AuthGuard('saml'))
+  async loginToSAML(
+    @Req() req: Request,
+  ): Promise<{ accessToken: string; userID: string }> {
+    this.logger.debug('in the saml login func');
+    this.logger.debug(JSON.stringify(req.session, null, 2));
+    return this.authnService.login(req.user as User);
+  }
+
+  @Post('saml/callback')
+  @UseFilters(new AuthenticationExceptionFilter())
+  @UseGuards(AuthGuard('saml'))
+  async getUserFromSAML(@Req() req: Request): Promise<void> {
+    this.logger.debug('in the saml login callback func');
+    this.logger.debug(JSON.stringify(req.session, null, 2));
+    const session = await this.authnService.login(req.user as User);
+    await this.setSessionCookies(req, session);
+  }
+
   async setSessionCookies(
     req: Request,
     session: {
@@ -187,4 +208,4 @@ export class AuthnController {
     });
     req.res?.redirect('/');
   }
-}
+}

apps/backend/src/authn/authn.module.ts

@@ -20,6 +20,7 @@ import {LDAPStrategy} from './ldap.strategy';
 import {LocalStrategy} from './local.strategy';
 import {OidcStrategy} from './oidc.strategy';
 import {OktaStrategy} from './okta.strategy';
+import { SAMLStrategy } from './saml.strategy';
 
 async function buildHttpsProxyAgent(proxyUrl: string): Promise<Agent> {
   const {HttpsProxyAgent} = await import('https-proxy-agent');
@@ -45,6 +46,7 @@ async function buildHttpsProxyAgent(proxyUrl: string): Promise<Agent> {
     GoogleStrategy,
     LDAPStrategy,
     ApiKeyService,
+    SAMLStrategy,
     {
       provide: OidcStrategy,
       useFactory: async (
@@ -77,4 +79,4 @@ async function buildHttpsProxyAgent(proxyUrl: string): Promise<Agent> {
   ],
   controllers: [AuthnController]
 })
-export class AuthnModule {}
+export class AuthnModule {}

apps/backend/src/authn/authn.service.ts

@@ -1,3 +1,4 @@
+import type {AuthStrategy} from '@heimdall/common/interfaces';
 import {
   ForbiddenException,
   Injectable,
@@ -100,7 +101,7 @@ export class AuthnService {
     email: string,
     firstName: string,
     lastName: string,
-    creationMethod: string
+    creationMethod: AuthStrategy
   ): Promise<User> {
     let user: User;
     try {

apps/backend/src/authn/oidc.strategy.ts

@@ -140,4 +140,4 @@ export class OidcStrategy extends PassportStrategy(Strategy as any, 'oidc') {
       )
     );
   }
-}
+}

apps/backend/src/authn/resolve_claim.ts

@@ -0,0 +1,21 @@
+import { UnauthorizedException } from '@nestjs/common';
+import _ from 'lodash';
+
+export function getRequiredClaim(
+  claims: Record<string, unknown>,
+  defaultClaimName: string,
+  configuredClaimName?: string,
+): string {
+  const resolvedClaimName = configuredClaimName || defaultClaimName;
+  const claimValue = _.get(claims, [resolvedClaimName])
+    ?? _.get(claims, resolvedClaimName);
+  const firstClaimValue = Array.isArray(claimValue)
+    ? claimValue.find(value => typeof value === 'string' && value.length > 0)
+    : claimValue;
+
+  if (typeof firstClaimValue === 'string' && firstClaimValue.length > 0) {
+    return firstClaimValue;
+  }
+
+  throw new UnauthorizedException(`Missing required claim "${resolvedClaimName}".`);
+}

apps/backend/src/authn/saml.strategy.ts

@@ -0,0 +1,134 @@
+import { Injectable } from '@nestjs/common';
+import { PassportStrategy } from '@nestjs/passport';
+import type { Profile, SamlScopingConfig } from '@node-saml/passport-saml';
+import { Strategy } from '@node-saml/passport-saml';
+import winston from 'winston';
+import { ConfigService } from '../config/config.service';
+import { User } from '../users/user.model';
+import { AuthnService } from './authn.service';
+import { getRequiredClaim } from './resolve_claim';
+
+function getSamlScoping(
+  configService: ConfigService,
+): SamlScopingConfig | undefined {
+  const idpList = configService.get('SAML_SCOPING_IDP_LIST');
+  const proxyCount = configService.get('SAML_SCOPING_PROXY_COUNT');
+  const requesterId = configService.get('SAML_SCOPING_REQUESTER_ID');
+
+  if (!proxyCount && !requesterId && !idpList) {
+    return undefined;
+  }
+
+  return {
+    idpList: idpList
+      ? JSON.parse(idpList)
+      : undefined,
+    proxyCount: proxyCount
+      ? Number(proxyCount)
+      : undefined,
+    requesterId: requesterId?.includes(',')
+      ? requesterId.split(',').map(value => value.trim())
+      : requesterId,
+  };
+}
+
+@Injectable()
+export class SAMLStrategy extends PassportStrategy(Strategy as any, 'saml') {
+  public loggingTimeFormat = 'MMM-DD-YYYY HH:mm:ss Z';
+  private readonly line = '_______________________________________________\n';
+  public logger = winston.createLogger({
+    format: winston.format.combine(
+      winston.format.timestamp({ format: this.loggingTimeFormat }),
+      winston.format.printf(
+        info =>
+          `${this.line}[${[info.timestamp]}] (Authn Service): ${info.message}`,
+      ),
+    ),
+    transports: [new winston.transports.Console()],
+  });
+
+  constructor(
+    private readonly authnService: AuthnService,
+    private readonly configService: ConfigService,
+  ) {
+    const samlAudience = configService.get('SAML_AUDIENCE');
+    super({
+      acceptedClockSkewMs: Number(configService.get('SAML_ACCEPTED_CLOCK_SKEW_MS') ?? 0),
+      additionalAuthorizeParams: configService.get('SAML_ADDITIONAL_AUTHORIZE_PARAMS') ? JSON.parse(configService.get('SAML_ADDITIONAL_AUTHORIZE_PARAMS')!) : undefined,
+      additionalLogoutParams: configService.get('SAML_ADDITIONAL_LOGOUT_PARAMS') ? JSON.parse(configService.get('SAML_ADDITIONAL_LOGOUT_PARAMS')!) : undefined,
+      additionalParams: configService.get('SAML_ADDITIONAL_PARAMS') ? JSON.parse(configService.get('SAML_ADDITIONAL_PARAMS')!) : undefined,
+      allowCreate: (configService.get('SAML_ALLOW_CREATE') ?? 'true').toLowerCase() === 'true',
+      attributeConsumingServiceIndex: configService.get('SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX'),
+      audience:
+        samlAudience?.toLowerCase() === 'false'
+          ? false
+          : samlAudience
+            || configService.get('SAML_ISSUER'),
+      authnContext: configService.get('SAML_AUTHN_CONTEXT') ? configService.get('SAML_AUTHN_CONTEXT')?.split(',').map(value => value.trim()) : undefined,
+      authnRequestBinding: configService.get('SAML_AUTHN_REQUEST_BINDING'),
+      callbackUrl:
+        configService.get('SAML_CALLBACK_URL')
+        || `${configService.getExternalUrl()}/authn/saml/callback`,
+      decryptionPvk: configService.get('SAML_DECRYPTION_PVK'),
+      digestAlgorithm: configService.get('SAML_DIGEST_ALGORITHM'),
+      disableRequestAcsUrl: (configService.get('SAML_DISABLE_REQUEST_ACS_URL') ?? '').toLowerCase() === 'true',
+      disableRequestedAuthnContext: (configService.get('SAML_DISABLE_REQUESTED_AUTHN_CONTEXT') ?? '').toLowerCase() === 'true',
+      entryPoint: configService.get('SAML_ENTRY_POINT') || 'disabled',
+      forceAuthn: (configService.get('SAML_FORCE_AUTHN') ?? '').toLowerCase() === 'true',
+      identifierFormat: configService.get('SAML_IDENTIFIER_FORMAT'),
+      idpCert: configService.get('SAML_IDP_CERT') || 'disabled',
+      idpIssuer: configService.get('SAML_IDP_ISSUER'),
+      issuer: configService.get('SAML_ISSUER') || 'disabled',
+      logoutCallbackUrl: configService.get('SAML_LOGOUT_CALLBACK_URL'),
+      logoutUrl: configService.get('SAML_LOGOUT_URL'),
+      maxAssertionAgeMs: Number(configService.get('SAML_MAX_ASSERTION_AGE_MS') ?? 0),
+      metadataContactPerson: configService.get('SAML_METADATA_CONTACT_PERSON') ? JSON.parse(configService.get('SAML_METADATA_CONTACT_PERSON')!) : undefined,
+      metadataOrganization: configService.get('SAML_METADATA_ORGANIZATION') ? JSON.parse(configService.get('SAML_METADATA_ORGANIZATION')!) : undefined,
+      passive: (configService.get('SAML_PASSIVE') ?? '').toLowerCase() === 'true',
+      privateKey: configService.get('SAML_PRIVATE_KEY'),
+      providerName: configService.get('SAML_PROVIDER_NAME'),
+      publicCert: configService.get('SAML_PUBLIC_CERT'),
+      racComparison: configService.get('SAML_RAC_COMPARISON') as
+      | 'better'
+      | 'exact'
+      | 'maximum'
+      | 'minimum'
+      | undefined,
+      requestIdExpirationPeriodMs: Number(configService.get('SAML_REQUEST_ID_EXPIRATION_PERIOD_MS') ?? 28_800_000),
+      samlAuthnRequestExtensions: configService.get('SAML_AUTHN_REQUEST_EXTENSIONS') ? JSON.parse(configService.get('SAML_AUTHN_REQUEST_EXTENSIONS')!) : undefined,
+      samlLogoutRequestExtensions: configService.get('SAML_LOGOUT_REQUEST_EXTENSIONS') ? JSON.parse(configService.get('SAML_LOGOUT_REQUEST_EXTENSIONS')!) : undefined,
+      scoping: getSamlScoping(configService),
+      signatureAlgorithm: configService.get('SAML_SIGNATURE_ALGORITHM') as 'sha1' | 'sha256' | 'sha512' | undefined,
+      signMetadata: (configService.get('SAML_SIGN_METADATA') ?? '').toLowerCase() === 'true',
+      skipRequestCompression: (configService.get('SAML_SKIP_REQUEST_COMPRESSION') ?? '').toLowerCase() === 'true',
+      spNameQualifier: configService.get('SAML_SP_NAME_QUALIFIER'),
+      validateInResponseTo: configService.get('SAML_VALIDATE_IN_RESPONSE_TO') as 'always' | 'ifPresent' | 'never' | undefined,
+      wantAssertionsSigned: (configService.get('SAML_WANT_ASSERTIONS_SIGNED') ?? 'true').toLowerCase() === 'true',
+      wantAuthnResponseSigned: (configService.get('SAML_WANT_AUTHN_RESPONSE_SIGNED') ?? 'true').toLowerCase() === 'true',
+      xmlSignatureTransforms: configService.get('SAML_XML_SIGNATURE_TRANSFORMS') ? JSON.parse(configService.get('SAML_XML_SIGNATURE_TRANSFORMS')!) : undefined,
+    });
+  }
+
+  async validate(profile: Profile): Promise<User> {
+    this.logger.debug('in saml strategy file');
+    this.logger.debug(JSON.stringify(profile, null, 2));
+    return this.authnService.validateOrCreateUser(
+      getRequiredClaim(
+        profile,
+        'email',
+        this.configService.get('SAML_EMAIL_ATTRIBUTE'),
+      ),
+      getRequiredClaim(
+        profile,
+        'firstName',
+        this.configService.get('SAML_FIRST_NAME_ATTRIBUTE'),
+      ),
+      getRequiredClaim(
+        profile,
+        'lastName',
+        this.configService.get('SAML_LAST_NAME_ATTRIBUTE'),
+      ),
+      'saml',
+    );
+  }
+}

apps/backend/src/config/config.service.ts

@@ -1,6 +1,16 @@
-import {SequelizeOptions} from 'sequelize-typescript';
+import { AUTH_STRATEGY } from '@heimdall/common/interfaces';
+import type { AuthStrategy } from '@heimdall/common/interfaces';
+import type { SequelizeOptions } from 'sequelize-typescript';
 import AppConfig from '../../config/app_config';
-import {StartupSettingsDto} from './dto/startup-settings.dto';
+import { StartupSettingsDto } from './dto/startup-settings.dto';
+
+const OAUTH_AUTH_STRATEGIES = [
+  AUTH_STRATEGY.GITHUB,
+  AUTH_STRATEGY.GITLAB,
+  AUTH_STRATEGY.GOOGLE,
+  AUTH_STRATEGY.OKTA,
+  AUTH_STRATEGY.OIDC,
+] as const;
 
 export class ConfigService {
   private readonly appConfig: AppConfig;
@@ -34,14 +44,28 @@ export class ConfigService {
     return this.get('NODE_ENV')?.toLowerCase() === 'production';
   }
 
-  enabledOauthStrategies() {
-    const enabledOauth: string[] = [];
-    supportedOauth.forEach((oauthStrategy) => {
-      if (this.get(`${oauthStrategy.toUpperCase()}_CLIENTID`)) {
-        enabledOauth.push(oauthStrategy);
-      }
-    });
-    return enabledOauth;
+  enabledAuthStrategies(): AuthStrategy[] {
+    const enabledAuthStrategies: AuthStrategy[] = [];
+    if (this.isLocalLoginAllowed()) {
+      enabledAuthStrategies.push(AUTH_STRATEGY.LOCAL);
+    }
+    if (this.get('LDAP_ENABLED')?.toLocaleLowerCase() === 'true') {
+      enabledAuthStrategies.push(AUTH_STRATEGY.LDAP);
+    }
+    enabledAuthStrategies.push(
+      ...OAUTH_AUTH_STRATEGIES.filter(authStrategy =>
+        this.get(`${authStrategy.toUpperCase()}_CLIENTID`),
+      ),
+    );
+    if (
+      ['SAML_ENTRY_POINT', 'SAML_ISSUER', 'SAML_IDP_CERT'].every(setting =>
+        this.get(setting),
+      )
+    ) {
+      enabledAuthStrategies.push(AUTH_STRATEGY.SAML);
+    }
+
+    return enabledAuthStrategies;
   }
 
   frontendStartupSettings(): StartupSettingsDto {
@@ -53,12 +77,10 @@ export class ConfigService {
       classificationBannerText: this.get('CLASSIFICATION_BANNER_TEXT') || '',
       classificationBannerTextColor:
         this.get('CLASSIFICATION_BANNER_TEXT_COLOR') || 'white',
-      enabledOAuth: this.enabledOauthStrategies(),
+      enabledAuthStrategies: this.enabledAuthStrategies(),
       externalUrl: this.getExternalUrl(),
       oidcName: this.get('OIDC_NAME') || '',
-      ldap: this.get('LDAP_ENABLED')?.toLocaleLowerCase() === 'true' || false,
       registrationEnabled: this.isRegistrationAllowed(),
-      localLoginEnabled: this.isLocalLoginAllowed(),
       tenableHostUrl: this.getTenableHostUrl(),
       forceTenableFrontend:
         this.get('FORCE_TENABLE_FRONTEND')?.toLowerCase() === 'true',
@@ -94,10 +116,3 @@ export class ConfigService {
     return this.appConfig.get(key);
   }
 }
-export const supportedOauth: string[] = [
-  'github',
-  'gitlab',
-  'google',
-  'okta',
-  'oidc'
-];

apps/backend/src/config/dto/startup-settings.dto.ts

@@ -1,33 +1,29 @@
-import {IStartupSettings} from '@heimdall/common/interfaces';
+import type {AuthStrategy, IStartupSettings} from '@heimdall/common/interfaces';
 
 export class StartupSettingsDto implements IStartupSettings {
   readonly apiKeysEnabled: boolean;
   readonly banner: string;
   readonly classificationBannerColor: string;
   readonly classificationBannerText: string;
   readonly classificationBannerTextColor: string;
-  readonly enabledOAuth: string[];
+  readonly enabledAuthStrategies: AuthStrategy[];
   readonly externalUrl: string;
+  readonly forceTenableFrontend: boolean;
   readonly oidcName: string;
-  readonly ldap: boolean;
   readonly registrationEnabled: boolean;
-  readonly localLoginEnabled: boolean;
-  readonly tenableHostUrl: string;
-  readonly forceTenableFrontend: boolean;
   readonly splunkHostUrl: string;
+  readonly tenableHostUrl: string;
 
   constructor(settings: IStartupSettings) {
     this.apiKeysEnabled = settings.apiKeysEnabled;
     this.banner = settings.banner;
     this.classificationBannerColor = settings.classificationBannerColor;
     this.classificationBannerText = settings.classificationBannerText;
     this.classificationBannerTextColor = settings.classificationBannerTextColor;
-    this.enabledOAuth = settings.enabledOAuth;
+    this.enabledAuthStrategies = settings.enabledAuthStrategies;
     this.externalUrl = settings.externalUrl;
     this.oidcName = settings.oidcName;
-    this.ldap = settings.ldap;
     this.registrationEnabled = settings.registrationEnabled;
-    this.localLoginEnabled = settings.localLoginEnabled;
     this.tenableHostUrl = settings.tenableHostUrl;
     this.forceTenableFrontend = settings.forceTenableFrontend;
     this.splunkHostUrl = settings.splunkHostUrl;

apps/backend/src/main.ts

@@ -69,7 +69,9 @@ async function bootstrap() {
   // Sessions was previously set to only be used for oauth callbacks
   // but now is used for Tenable authentication as well.
   if (
-    configService.enabledOauthStrategies().length ||
+    configService
+      .enabledAuthStrategies()
+      .some((strategy) => strategy !== 'local') ||
     configService.getTenableHostUrl().length
   ) {
     app.use(