sso.js

Go to the documentation of this file.

/**
 * @file sso.js
 * @module routes/sso
 * @description Single Sign-On (SSO) integration endpoints. Supports per-tenant and per-user SSO
 * configuration with OAuth2 and SAML protocols. Includes Azure AD integration with MSAL.
 * @requires express
 * @requires services/db
 * @requires @azure/msal-node
 * @author RMM-PSA Development Team
 * @copyright 2026 RMM-PSA Platform
 * @license Proprietary
 */
 
/**
 * @apiDefine SSO Single Sign-On
 * SSO integration for OAuth2/SAML authentication
 */
 
// SSO Integration Route: Per-tenant and per-user SSO (OAuth2/SAML)
const express = require('express');
const router = express.Router();
const pool = require('../services/db');
const msal = require('@azure/msal-node');
 
const azureConfig = {
  auth: {
    clientId: process.env.AZURE_AD_CLIENT_ID,
    authority: 'https://login.microsoftonline.com/common',
    clientSecret: process.env.AZURE_AD_CLIENT_SECRET
  }
};
const azureRedirectUri = process.env.AZURE_AD_REDIRECT_URI || 'https://yourdomain.com/api/sso/azure/callback';
 
/**
 * @api {get} /api/sso/settings/:tenant_id Get tenant SSO config
 * @apiName GetTenantSSOSettings
 * @apiGroup SSO
 * @apiDescription Retrieve SSO configuration for a tenant. Returns config object containing
 * OAuth2 or SAML provider settings.
 * @apiParam {string} tenant_id Tenant ID
 * @apiSuccess {object} config SSO configuration object
 * @apiError {string} error="No SSO config found" (404) Tenant has no SSO configuration
 * @apiError {string} error="Server error" (500) Database query failed
 * @apiExample {curl} Example:
 *   curl -X GET http://localhost:3000/api/sso/settings/123
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "provider": "azure",
 *     "clientId": "abc123-def456",
 *     "tenantId": "xyz789"
 *   }
 */
router.get('/settings/:tenant_id', async (req, res) => {
  try {
    const result = await pool.query('SELECT config FROM integrations WHERE tenant_id = $1 AND integration_type = $2', [req.params.tenant_id, 'sso']);
    if (!result.rows.length) return res.status(404).json({ error: 'No SSO config found' });
    res.json(result.rows[0].config || {});
  } catch (err) {
    res.status(500).json({ error: 'Server error' });
  }
});
 
/**
 * @api {post} /api/sso/settings/:tenant_id Save tenant SSO config
 * @apiName SaveTenantSSOSettings
 * @apiGroup SSO
 * @apiDescription Save or update SSO configuration for a tenant. Upserts config in integrations
 * table with integration_type='sso'. Config object should contain provider-specific settings.
 * @apiParam {string} tenant_id Tenant ID
 * @apiParam {object} config SSO configuration object (varies by provider)
 * @apiSuccess {boolean} success=true Configuration saved successfully
 * @apiError {string} error="Server error" (500) Database save failed
 * @apiExample {curl} Example:
 *   curl -X POST http://localhost:3000/api/sso/settings/123 \
 *     -H "Content-Type: application/json" \
 *     -d '{"provider": "azure", "clientId": "abc123", "tenantId": "xyz789"}'
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "success": true
 *   }
 */
router.post('/settings/:tenant_id', async (req, res) => {
  try {
    const config = req.body;
    // Upsert SSO config in integrations table
    await pool.query(`INSERT INTO integrations (tenant_id, integration_type, config, is_active, created_at, updated_at)
      VALUES ($1, $2, $3, true, NOW(), NOW())
      ON CONFLICT (tenant_id, integration_type) DO UPDATE SET config = $3, updated_at = NOW()`,
      [req.params.tenant_id, 'sso', JSON.stringify(config)]);
    res.json({ success: true });
  } catch (err) {
    res.status(500).json({ error: 'Server error' });
  }
});
 
/**
 * @api {get} /api/sso/oauth/:tenant_id/start Start OAuth2 flow
 * @apiName StartOAuth2Flow
 * @apiGroup SSO
 * @apiDescription Start OAuth2 authentication flow for tenant SSO. Currently not implemented.
 * Placeholder for future OAuth2 provider support (Google, Okta, etc).
 * @apiParam {string} tenant_id Tenant ID
 * @apiSuccess {string} status="not_implemented"
 * @apiSuccess {string} message Implementation status
 * @apiExample {curl} Example:
 *   curl -X GET http://localhost:3000/api/sso/oauth/123/start
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "status": "not_implemented",
 *     "message": "OAuth2 flow not yet implemented."
 *   }
 */
router.get('/oauth/:tenant_id/start', (req, res) => {
  // TODO: Implement OAuth2 flow (e.g., Azure AD, Google, Okta)
  res.json({ status: 'not_implemented', message: 'OAuth2 flow not yet implemented.' });
});
 
/**
 * @api {post} /api/sso/saml/:tenant_id/assert Handle SAML assertion
 * @apiName HandleSAMLAssertion
 * @apiGroup SSO
 * @apiDescription Handle SAML assertion for tenant SSO. Currently not implemented.
 * Placeholder for future SAML provider support.
 * @apiParam {string} tenant_id Tenant ID
 * @apiSuccess {string} status="not_implemented"
 * @apiSuccess {string} message Implementation status
 * @apiExample {curl} Example:
 *   curl -X POST http://localhost:3000/api/sso/saml/123/assert
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "status": "not_implemented",
 *     "message": "SAML assertion not yet implemented."
 *   }
 */
router.post('/saml/:tenant_id/assert', (req, res) => {
  // TODO: Implement SAML assertion handling
  res.json({ status: 'not_implemented', message: 'SAML assertion not yet implemented.' });
});
 
/**
 * @api {get} /api/sso/user/:user_id Get user SSO info
 * @apiName GetUserSSOInfo
 * @apiGroup SSO
 * @apiDescription Get SSO provider and ID for a user. Returns sso_provider and sso_id fields
 * from users table.
 * @apiParam {number} user_id User ID
 * @apiSuccess {string} sso_provider SSO provider name (azure, google, okta, etc)
 * @apiSuccess {string} sso_id Provider-specific user identifier
 * @apiError {string} error="No SSO info found for user" (404) User not found or no SSO linked
 * @apiError {string} error="Server error" (500) Database query failed
 * @apiExample {curl} Example:
 *   curl -X GET http://localhost:3000/api/sso/user/456
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "sso_provider": "azure",
 *     "sso_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
 *   }
 */
router.get('/user/:user_id', async (req, res) => {
  try {
    const result = await pool.query('SELECT sso_provider, sso_id FROM users WHERE user_id = $1', [req.params.user_id]);
    if (!result.rows.length) return res.status(404).json({ error: 'No SSO info found for user' });
    res.json(result.rows[0]);
  } catch (err) {
    res.status(500).json({ error: 'Server error' });
  }
});
 
/**
 * @api {post} /api/sso/user/:user_id Link user to SSO provider
 * @apiName LinkUserToSSO
 * @apiGroup SSO
 * @apiDescription Link a user account to an SSO provider. Updates sso_provider and sso_id
 * fields in users table.
 * @apiParam {number} user_id User ID
 * @apiParam {string} sso_provider SSO provider name
 * @apiParam {string} sso_id Provider-specific user identifier
 * @apiSuccess {boolean} success=true User linked successfully
 * @apiError {string} error="Server error" (500) Database update failed
 * @apiExample {curl} Example:
 *   curl -X POST http://localhost:3000/api/sso/user/456 \
 *     -H "Content-Type: application/json" \
 *     -d '{"sso_provider": "azure", "sso_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "success": true
 *   }
 */
router.post('/user/:user_id', async (req, res) => {
  try {
    const { sso_provider, sso_id } = req.body;
    await pool.query('UPDATE users SET sso_provider = $1, sso_id = $2 WHERE user_id = $3', [sso_provider, sso_id, req.params.user_id]);
    res.json({ success: true });
  } catch (err) {
    res.status(500).json({ error: 'Server error' });
  }
});
 
/**
 * @api {get} /api/sso/azure/:tenant_id/start Start Azure AD OAuth2 flow
 * @apiName StartAzureADFlow
 * @apiGroup SSO
 * @apiDescription Initialize Azure AD OAuth2 authentication flow using MSAL. Returns authorization
 * URL for redirecting user to Microsoft login. Tenant ID passed via state parameter.
 * @apiParam {string} tenant_id Tenant ID (passed as state parameter)
 * @apiSuccess {string} url Azure AD authorization URL
 * @apiError {string} error="Failed to generate Azure AD auth URL" (500) MSAL error
 * @apiExample {curl} Example:
 *   curl -X GET http://localhost:3000/api/sso/azure/123/start
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=..."
 *   }
 */
router.get('/azure/:tenant_id/start', async (req, res) => {
  const msalClient = new msal.ConfidentialClientApplication(azureConfig);
  const authCodeUrlParameters = {
    scopes: ['openid', 'profile', 'email'],
    redirectUri: azureRedirectUri,
    state: req.params.tenant_id
  };
  try {
    const url = await msalClient.getAuthCodeUrl(authCodeUrlParameters);
    res.json({ url });
  } catch (err) {
    res.status(500).json({ error: 'Failed to generate Azure AD auth URL' });
  }
});
 
/**
 * @api {get} /api/sso/azure/callback Azure AD OAuth2 callback
 * @apiName AzureADCallback
 * @apiGroup SSO
 * @apiDescription Handle Azure AD OAuth2 callback. Exchanges authorization code for tokens,
 * extracts user info from ID token, and updates user SSO info in database. Also stores tokens
 * in tenant integration config.
 * @apiParam {string} code Authorization code from Azure AD (query param)
 * @apiParam {string} state Tenant ID (query param)
 * @apiSuccess {boolean} success=true Authentication successful
 * @apiSuccess {object} user User info from ID token
 * @apiSuccess {string} user.email User email
 * @apiSuccess {string} user.oid User object ID (Azure AD)
 * @apiSuccess {string} user.name User display name
 * @apiError {string} error="Missing code or tenant_id" (400) Required query params missing
 * @apiError {string} error="Azure AD callback failed" (500) Token exchange or DB update failed
 * @apiExample {curl} Example:
 *   curl -X GET "http://localhost:3000/api/sso/azure/callback?code=abc123&state=123"
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "success": true,
 *     "user": {
 *       "email": "user@example.com",
 *       "oid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 *       "name": "John Doe"
 *     }
 *   }
 */
router.get('/azure/callback', async (req, res) => {
  const code = req.query.code;
  const tenant_id = req.query.state;
  if (!code || !tenant_id) return res.status(400).json({ error: 'Missing code or tenant_id' });
  const msalClient = new msal.ConfidentialClientApplication(azureConfig);
  try {
    const tokenResponse = await msalClient.acquireTokenByCode({
      code,
      scopes: ['openid', 'profile', 'email'],
      redirectUri: azureRedirectUri
    });
    // Extract user info from ID token
    const idToken = tokenResponse.idTokenClaims;
    // Upsert user SSO info
    await pool.query(
      'UPDATE users SET sso_provider = $1, sso_id = $2 WHERE email = $3',
      ['azure', idToken.oid || idToken.sub, idToken.email]
    );
    // Optionally store tokens in tenant SSO config
    await pool.query(
      "UPDATE integrations SET config = jsonb_set(coalesce(config, '{}'), '{azure}', $1::jsonb) WHERE tenant_id = $2 AND integration_type = $3",
      [JSON.stringify(tokenResponse), tenant_id, 'sso']
    );
    res.json({ success: true, user: idToken });
  } catch (err) {
    res.status(500).json({ error: 'Azure AD callback failed', details: err.message });
  }
});
 
module.exports = router;