swissoid-back

SwissOID authentication package for Node.js backends. Provides reusable authentication components for integrating SwissOID (OpenID Connect) authentication into Node.js applications.

Features

• 🔐 Complete OIDC Authorization Code Flow implementation
• 🍪 Secure cookie-based session management
• 🔑 JWT verification with JWKS support
• 📦 Dependency Injection ready (di-why compatible)
• 🚀 TypeScript support with full type definitions
• ⚡ Redis-based session storage

Installation

npm install swissoid-back

Usage

Basic Setup with Dependency Injection

import {
  oidcRoutesLDEGen,
  swissoidSessionServiceLDEGen,
  cookieManagerLDEGen,
  swissoidJWTVerifierLDEGen,
  redisClientLDEGen
} from 'swissoid-back';
import DiContainer from 'di-why';

const container = new DiContainer({
  load: {
    // Redis client for session storage
    redisClient: redisClientLDEGen(),

    // Session service
    sessionService: swissoidSessionServiceLDEGen(),

    // Cookie manager
    cookieManager: cookieManagerLDEGen({
      domain: '.example.com',
      sessionName: 'app_session'
    }),

    // JWT verifier
    jwtVerifier: swissoidJWTVerifierLDEGen(),

    // OIDC routes
    oidcRoutes: oidcRoutesLDEGen({
      clientId: 'your-client-id',
      cookieDomain: '.example.com'
    })
  }
});

Express Integration

import express from 'express';
import cookieParser from 'cookie-parser';

const app = express();

// Required middleware
app.use(cookieParser());

// Mount OIDC routes
const oidcRoutes = await container.get('oidcRoutes');
app.use(oidcRoutes);

// Routes provided:
// GET  /login           - Initiates OIDC flow
// POST /oidc/callback   - Handles callback from IdP
// GET  /oidc/finalize   - Sets cookies in first-party context
// GET  /auth/status     - Returns authentication status
// GET  /auth/userinfo   - Returns user information
// GET  /auth/logout     - Destroys session
// POST /auth/logout     - Destroys session (JSON response)

Configuration

Required environment variables:

# SwissOID Configuration
SWISSOID_ISSUER=https://api.swissoid.com
SWISSOID_CLIENT_ID=your-client-id
SWISSOID_CLIENT_SECRET=your-client-secret
SWISSOID_TOKEN_ENDPOINT=https://api.swissoid.com/token
SWISSOID_JWKS_URI=https://api.swissoid.com/.well-known/jwks.json
SWISSOID_AUTHORIZE_ENDPOINT=https://api.swissoid.com/authorize

# RP Configuration
RP_CALLBACK_URL=https://your-app.com/oidc/callback
RP_COOKIE_DOMAIN=.your-app.com
RP_FRONTEND_URL=https://app.your-app.com

# Session Configuration
SESSION_COOKIE_NAME=app_session
SESSION_SECRET=your-session-secret
STATE_SIGNING_SECRET=your-state-signing-secret

# Redis
REDIS_URL=redis://localhost:6379

Manual Usage (without DI)

import { createOIDCRoutes, SwissOIDSessionService, CookieManager } from 'swissoid-back';
import Redis from 'ioredis';

// Create Redis client
const redisClient = new Redis('redis://localhost:6379');

// Create session service
const sessionService = new SwissOIDSessionService(redisClient, console);

// Create cookie manager
const cookieManager = new CookieManager({
  domain: '.example.com',
  sessionName: 'app_session',
  secureCookie: true,
  sameSite: 'lax'
});

// Create OIDC routes
const oidcRoutes = createOIDCRoutes({
  logger: console,
  sessionService,
  redisClient,
  issuer: 'https://api.swissoid.com',
  clientId: 'your-client-id',
  // ... other config
});

app.use(oidcRoutes);

API Reference

Components

• oidcRoutesLDEGen: Loader for OIDC route handlers
• swissoidSessionServiceLDEGen: Loader for session management service
• cookieManagerLDEGen: Loader for cookie operations
• swissoidJWTVerifierLDEGen: Loader for JWT verification
• redisClientLDEGen: Loader for Redis client

Types

interface OIDCConfig {
  issuer: string;
  clientId: string;
  clientSecret?: string;
  tokenEndpoint: string;
  jwksUri: string;
  authorizeEndpoint: string;
  callbackUrl: string;
  cookieDomain: string;
  frontendUrl: string;
  sessionCookieName: string;
  sessionSecret: string;
  stateSigningSecret: string;
}

interface SessionData {
  sub: string;
  email?: string;
  name?: string;
  iat: number;
  exp: number;
  createdAt?: number;
  lastAccessedAt?: number;
  metadata?: Record<string, any>;
}

License

MIT