npm.io
1.3.2 • Published 5h ago

@carisls/sso-standard

Licence
MIT
Version
1.3.2
Deps
4
Size
45 kB
Vulns
0
Weekly
0

@carisls/sso-standard

A middleware implementing standard OIDC/OAuth2 authorization code flow SSO for Express.js applications. This package provides a complete, ready-to-use authentication solution with automatic token management, session handling, and user mapping.

Features

  • Complete OIDC/OAuth2 authorization code flow implementation
  • Automatic cookie-based session management with encryption
  • Automatic token refresh handling
  • User token mapping and request injection
  • Built-in authorization middleware
  • Multi-provider support (Keycloak, Okta, and other OIDC providers)
  • JWKS-based public key validation with caching
  • Supports both ESM and CommonJS
  • Customizable endpoints and paths
  • Secure cookie handling with encryption

Installation

npm install @carisls/sso-standard

Quick Start

ESM (ECMAScript Modules)
import express from 'express';
import { router } from '@carisls/sso-standard';

const app = express();

app.use(router({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  // Simple format: comma-separated string
  providers: 'https://auth.example.com',
  // Or array format: providers: [{ ssoUrl: 'https://auth.example.com' }],
  encPassword: 'your-encryption-password'
}));

app.listen(3000);
CommonJS
const express = require('express');
const { router } = require('@carisls/sso-standard');

const app = express();

app.use(router({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  // Simple format: comma-separated string
  providers: 'https://auth.example.com',
  // Or array format: providers: [{ ssoUrl: 'https://auth.example.com' }],
  encPassword: 'your-encryption-password'
}));

app.listen(3000);

API Reference

router(options)

Creates and configures an Express router with complete SSO authentication flow.

Parameters:

  • options (Object): Configuration object with the following properties:
    • clientId (string, required): SSO Client ID registered with your identity provider
    • clientSecret (string, required): SSO Client Secret
    • providers (string | Array, required): Provider configuration(s). Can be:
      • A comma-separated string of provider URLs (e.g., 'https://auth1.example.com,https://auth2.example.com')
      • An array of provider configuration objects:
        • ssoUrl (string): Base URL for the provider (usually equal to iss). Used to discover OpenID Connect configuration
        • iss (string, optional): Issuer identifier. If not provided, defaults to ssoUrl
        • publicKey (string, optional): Static public key in PEM format (if not using JWKS)
    • encPassword (string, required): Password used for encrypting cookies
    • encPasswordSalt (string, optional): Salt for password derivation (default: 'C5mp4Hl$X9wby#s5')
    • encIterationCount (number, optional): Iteration count for key derivation (default: 123123)
    • publicKeyCache (number, optional): Public key caching expiration in seconds (default: 300)
    • expOffset (number, optional): Force renewal of tokens earlier (in seconds) to handle clock skew issues (default: 0)
    • groups (boolean, optional): Request groups scope from the provider (default: true)
    • userMapper (function, optional): Custom function to map tokens to user object. Signature: (token, idToken) => userObject
    • paths (Object, optional): Customize default endpoint paths
      • login (string, default: '/login'): Login initiation endpoint
      • sso (string, default: '/sso'): SSO callback endpoint
      • afterLogin (string, default: '/'): Redirect after successful login
      • logout (string, default: '/logout'): Logout initiation endpoint
      • afterLogout (string, default: '/'): Redirect after successful logout

Returns: Express Router instance with the following endpoints configured:

  • GET /login (or custom path): Initiates SSO login flow
  • GET /sso (or custom path): Handles SSO callback and token exchange
  • GET /logout (or custom path): Initiates logout flow
  • Automatic token refresh middleware
  • User injection middleware (adds req.user to authenticated requests)

Example:

import express from 'express';
import { router } from '@carisls/sso-standard';

const app = express();

app.use(router({
  clientId: 'my-app-client',
  clientSecret: 'my-secret-key',
  // Simple format: comma-separated string
  providers: 'https://auth.example.com',
  // Or detailed format: array of objects
  // providers: [
  //   {
  //     ssoUrl: 'https://auth.example.com',
  //     // iss defaults to ssoUrl if not provided
  //   }
  // ],
  encPassword: 'my-encryption-password-123',
  publicKeyCache: 600,
  expOffset: 60,
  groups: true,
  paths: {
    login: '/auth/login',
    sso: '/auth/callback',
    afterLogin: '/dashboard',
    logout: '/auth/logout',
    afterLogout: '/'
  },
  userMapper: (token, idToken) => {
    return {
      id: token.sub,
      email: token.email,
      name: token.name,
      roles: token.roles || []
    };
  }
}));

// Protected route - user is automatically available via req.user
app.get('/dashboard', (req, res) => {
  res.json({
    message: 'Welcome!',
    user: req.user
  });
});

app.listen(3000);
authorize(role, exceptions, redirectToLogin)

Express.js middleware for authorization filtering based on user roles. This middleware works in conjunction with the router to provide role-based access control.

Parameters:

  • role (string | string[] | undefined, optional): Role(s) to filter by. If undefined, only checks for authenticated user.
  • exceptions (string[] | undefined, optional): Array of URL paths to skip authorization checks.
  • redirectToLogin (boolean, default: false): If true, redirects to login page instead of returning 401.

Returns: Express middleware function (req, res, next) => void

Example:

import express from 'express';
import { router, authorize } from '@carisls/sso-standard';

const app = express();

// Setup SSO router
app.use(router({
  clientId: 'my-client-id',
  clientSecret: 'my-secret',
  // Simple format: comma-separated string
  providers: 'https://auth.example.com',
  // Or array format: providers: [{ ssoUrl: 'https://auth.example.com' }],
  encPassword: 'encryption-password'
}));

// Require any authenticated user
app.use(authorize());

// Require specific role
app.get('/admin', authorize('admin'), (req, res) => {
  res.json({ message: 'Admin access granted', user: req.user });
});

// Require one of multiple roles
app.get('/dashboard', authorize(['admin', 'user']), (req, res) => {
  res.json({ message: 'Dashboard access', user: req.user });
});

// With exceptions and redirect
app.use(authorize('user', ['/public', '/health'], true));

app.listen(3000);

Complete Example

import express from 'express';
import { router, authorize } from '@carisls/sso-standard';

const app = express();

// Configure SSO middleware
app.use(router({
  clientId: process.env.SSO_CLIENT_ID,
  clientSecret: process.env.SSO_CLIENT_SECRET,
  // Simple format: comma-separated string (iss defaults to ssoUrl)
  providers: process.env.SSO_URL,
  // Or array format with custom iss:
  // providers: [
  //   {
  //     ssoUrl: process.env.SSO_URL,
  //     iss: process.env.SSO_ISSUER // optional, defaults to ssoUrl
  //   }
  // ],
  encPassword: process.env.ENCRYPTION_PASSWORD,
  publicKeyCache: 600,
  paths: {
    login: '/login',
    sso: '/sso',
    afterLogin: '/dashboard',
    logout: '/logout',
    afterLogout: '/'
  }
}));

// Public routes
app.get('/', (req, res) => {
  res.send('Welcome! <a href="/login">Login</a>');
});

// Protected routes - require authentication
app.get('/dashboard', authorize(), (req, res) => {
  res.json({
    message: 'Dashboard',
    user: req.user
  });
});

// Admin routes - require admin role
app.get('/admin', authorize('admin'), (req, res) => {
  res.json({
    message: 'Admin panel',
    user: req.user
  });
});

// API routes with role-based access
app.get('/api/users', authorize(['admin', 'user-manager']), (req, res) => {
  res.json({ users: [] });
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

How It Works

  1. Login Flow: When a user visits /login, they are redirected to the identity provider's authorization endpoint with the appropriate OAuth2 parameters.

  2. Callback Handling: After authentication, the provider redirects back to /sso with an authorization code. The middleware exchanges this code for access, refresh, and ID tokens.

  3. Token Storage: Tokens are encrypted and stored in HTTP-only cookies:

    • x-session: Encrypted access token
    • x-session-sso: Encrypted refresh token
    • x-session-id: Encrypted ID token (used for logout)
  4. User Injection: On each request, the middleware decrypts tokens, validates them, and injects a req.user object containing user information.

  5. Token Refresh: The middleware automatically refreshes access tokens when they expire using the stored refresh token.

  6. Logout: Visiting /logout clears all cookies and redirects to the identity provider's logout endpoint.

Supported Providers

This package works with any OIDC-compliant identity provider, including:

  • Keycloak
  • Okta
  • Auth0
  • Azure AD
  • Google Identity Platform
  • Any other OIDC/OAuth2 provider

User Object Structure

By default, the req.user object follows this structure (can be customized with userMapper):

{
  iss: string;              // Issuer
  id: string;               // User ID (from 'sub')
  sid?: string;             // Session ID
  sa: boolean;              // Service account flag
  azp?: string;             // Authorized party
  name?: {                  // Name object (if available)
    full: string;
    familyName: string;
    givenName: string;
  };
  email?: string;           // Email (if available)
  roles: string[];          // User roles
}

Environment Variables

For production use, store sensitive values in environment variables:

SSO_CLIENT_ID=your-client-id
SSO_CLIENT_SECRET=your-client-secret
SSO_URL=https://auth.example.com
SSO_ISSUER=https://auth.example.com
ENCRYPTION_PASSWORD=your-strong-encryption-password

Security Considerations

  • Cookie Encryption: All tokens are encrypted before being stored in cookies
  • HTTP-Only Cookies: Prevents XSS attacks by making cookies inaccessible to JavaScript
  • Secure Cookies: Automatically enabled when using HTTPS
  • Token Validation: All tokens are validated using JWKS before use
  • Automatic Refresh: Tokens are refreshed before expiration to prevent service interruption

Dependencies

  • @carisls/sso-core: Core SSO utilities (token validation, encryption, etc.)
  • express: Web framework
  • cookie-parser: Cookie parsing middleware
  • debug: Debug logging utility

License

MIT

Author

Mihovil Strujic mstrujic@carisls.com

Keywords