Implement SAML SSO controller and tests

Added SAML SSO login and ACS endpoint logic to the controller, including user provisioning and session creation. Updated Jest config to use a dedicated test tsconfig. Added comprehensive tests for SAML controller behavior and created a test tsconfig.json.

Author: neSpecc

jest.config.js

@@ -24,7 +24,9 @@ module.exports = {
    * TypeScript support
    */
   transform: {
-    '^.+\\.tsx?$': 'ts-jest',
+    '^.+\\.tsx?$': ['ts-jest', {
+      tsconfig: 'test/tsconfig.json',
+    }],
   },
 
   /**

src/index.ts

@@ -30,6 +30,7 @@ import { metricsMiddleware, createMetricsServer, graphqlMetricsPlugin } from './
 import { requestLogger } from './utils/logger';
 import ReleasesFactory from './models/releasesFactory';
 import RedisHelper from './redisHelper';
+import { appendSsoRoutes } from './sso';
 
 /**
  * Option to enable playground
@@ -246,6 +247,22 @@ class HawkAPI {
 
     await redis.initialize();
 
+    /**
+     * Setup shared factories for SSO routes
+     * SSO endpoints don't require per-request DataLoaders isolation,
+     * so we can reuse the same factories instance
+     * Created here to avoid duplication with createContext
+     */
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const ssoDataLoaders = new DataLoaders(mongo.databases.hawk!);
+    const ssoFactories = HawkAPI.setupFactories(ssoDataLoaders);
+
+    /**
+     * Append SSO routes to Express app using shared factories
+     * Note: This must be called after database connections are established
+     */
+    appendSsoRoutes(this.app, ssoFactories);
+
     await this.server.start();
     this.app.use(graphqlUploadExpress());
     this.server.applyMiddleware({ app: this.app });

src/sso/saml/controller.ts

@@ -1,7 +1,11 @@
 import express from 'express';
+import { v4 as uuid } from 'uuid';
 import SamlService from './service';
 import samlStore from './store';
 import { ContextFactories } from '../../types/graphql';
+import { SamlResponseData } from '../types';
+import WorkspaceModel from '../../models/workspace';
+import UserModel from '../../models/user';
 
 /**
  * Controller for SAML SSO endpoints
@@ -37,20 +41,200 @@ export default class SamlController {
    * Initiate SSO login (GET /auth/sso/saml/:workspaceId)
    */
   public async initiateLogin(req: express.Request, res: express.Response): Promise<void> {
+    const { workspaceId } = req.params;
+    const returnUrl = (req.query.returnUrl as string) || `/workspace/${workspaceId}`;
+
+    /**
+     * 1. Check if workspace has SSO enabled
+     */
+    const workspace = await this.factories.workspacesFactory.findById(workspaceId);
+
+    if (!workspace || !workspace.sso?.enabled) {
+      res.status(400).json({ error: 'SSO is not enabled for this workspace' });
+      return;
+    }
+
+    /**
+     * 2. Compose Assertion Consumer Service URL
+     */
+    const acsUrl = this.getAcsUrl(workspaceId);
+    const relayStateId = uuid();
+
     /**
-     * TODO: Implement according to specification
+     * 3. Save RelayState to temporary storage
      */
-    throw new Error('Not implemented');
+    samlStore.saveRelayState(relayStateId, { returnUrl, workspaceId });
+
+    /**
+     * 4. Generate AuthnRequest
+     */
+    const { requestId, encodedRequest } = await this.samlService.generateAuthnRequest(
+      workspaceId,
+      acsUrl,
+      relayStateId,
+      workspace.sso.saml
+    );
+
+    /**
+     * 5. Save AuthnRequest ID for InResponseTo validation
+     */
+    samlStore.saveAuthnRequest(requestId, workspaceId);
+
+    /**
+     * 6. Redirect to IdP
+     */
+    const redirectUrl = new URL(workspace.sso.saml.ssoUrl);
+    redirectUrl.searchParams.set('SAMLRequest', encodedRequest);
+    redirectUrl.searchParams.set('RelayState', relayStateId);
+
+    res.redirect(redirectUrl.toString());
   }
 
   /**
    * Handle ACS callback (POST /auth/sso/saml/:workspaceId/acs)
    */
   public async handleAcs(req: express.Request, res: express.Response): Promise<void> {
+    const { workspaceId } = req.params;
+    const samlResponse = req.body.SAMLResponse as string;
+    const relayStateId = req.body.RelayState as string;
+
+    /**
+     * 1. Get workspace SSO configuration and check if SSO is enabled
+     */
+    const workspace = await this.factories.workspacesFactory.findById(workspaceId);
+
+    if (!workspace || !workspace.sso?.enabled) {
+      res.status(400).json({ error: 'SSO is not enabled' });
+      return;
+    }
+
+    /**
+     * 2. Validate and parse SAML Response
+     */
+    const acsUrl = this.getAcsUrl(workspaceId);
+
+    let samlData: SamlResponseData;
+
+    try {
+      /**
+       * Validate and parse SAML Response
+       * Note: InResponseTo validation is done separately after parsing
+       */
+      samlData = await this.samlService.validateAndParseResponse(
+        samlResponse,
+        workspaceId,
+        acsUrl,
+        workspace.sso.saml
+      );
+
+      /**
+       * Validate InResponseTo against stored AuthnRequest
+       */
+      if (samlData.inResponseTo) {
+        const isValidRequest = samlStore.validateAndConsumeAuthnRequest(
+          samlData.inResponseTo,
+          workspaceId
+        );
+
+        if (!isValidRequest) {
+          res.status(400).json({ error: 'Invalid SAML response: InResponseTo validation failed' });
+          return;
+        }
+      }
+    } catch (error) {
+      console.error('SAML validation error:', {
+        workspaceId,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      });
+      res.status(400).json({ error: 'Invalid SAML response' });
+      return;
+    }
+
+    /**
+     * 3. Find or create user
+     */
+    let user = await this.factories.usersFactory.findBySamlIdentity(workspaceId, samlData.nameId);
+
+    if (!user) {
+      /**
+       * JIT provisioning or invite-only policy
+       */
+      user = await this.handleUserProvisioning(workspaceId, samlData, workspace);
+    }
+
+    /**
+     * 4. Get RelayState for return URL (before consuming)
+     * Note: RelayState is consumed after first use, so we need to get it before validation
+     */
+    const relayState = samlStore.getRelayState(relayStateId);
+    const finalReturnUrl = relayState?.returnUrl || `/workspace/${workspaceId}`;
+
     /**
-     * TODO: Implement according to specification
+     * 5. Create Hawk session
      */
-    throw new Error('Not implemented');
+    const tokens = await user.generateTokensPair();
+
+    /**
+     * 6. Redirect to Garage with tokens
+     */
+    const frontendUrl = new URL(finalReturnUrl, process.env.GARAGE_URL || 'http://localhost:3000');
+    frontendUrl.searchParams.set('access_token', tokens.accessToken);
+    frontendUrl.searchParams.set('refresh_token', tokens.refreshToken);
+
+    res.redirect(frontendUrl.toString());
+  }
+
+  /**
+   * Handle user provisioning (JIT or invite-only)
+   *
+   * @param workspaceId - workspace ID
+   * @param samlData - parsed SAML response data
+   * @param workspace - workspace model
+   * @returns UserModel instance
+   */
+  private async handleUserProvisioning(
+    workspaceId: string,
+    samlData: SamlResponseData,
+    workspace: WorkspaceModel
+  ): Promise<UserModel> {
+    /**
+     * Find user by email
+     */
+    let user = await this.factories.usersFactory.findByEmail(samlData.email);
+
+    if (!user) {
+      /**
+       * Create new user (JIT provisioning)
+       * Password is not set - only SSO login is allowed
+       */
+      user = await this.factories.usersFactory.create(samlData.email, undefined, undefined);
+    }
+
+    /**
+     * Link SAML identity to user
+     */
+    await user.linkSamlIdentity(workspaceId, samlData.nameId, samlData.email);
+
+    /**
+     * Check if user is a member of the workspace
+     */
+    const member = await workspace.getMemberInfo(user._id.toString());
+
+    if (!member) {
+      /**
+       * Add user to workspace (JIT provisioning)
+       */
+      await workspace.addMember(user._id.toString());
+      await user.addWorkspace(workspaceId);
+    } else if (WorkspaceModel.isPendingMember(member)) {
+      /**
+       * Confirm pending membership
+       */
+      await workspace.confirmMembership(user);
+      await user.confirmMembership(workspaceId);
+    }
+
+    return user;
   }
 }
 

src/sso/saml/service.ts

@@ -10,6 +10,8 @@ export default class SamlService {
   /**
    * Generate SAML AuthnRequest
    *
+   * AuthnRequest - a SAML-message that Hawk sends to IdP to initiate auth process.
+   *
    * @param workspaceId - workspace ID
    * @param acsUrl - Assertion Consumer Service URL
    * @param relayState - context of user returning (url + relay state id)