swissoid-back/README.md

swissoid-back

SwissOID authentication backend for Node.js applications. Provides reusable OIDC authentication components for integrating with SwissOID (Swiss eID).

Features

• 🔐 Full OIDC Authorization Code Flow implementation
• 🍪 Session management with Redis
• 🔑 JWT verification with JWKS
• 🎯 Built for di-why dependency injection
• 📦 Reusable authentication components
• 🔄 Configurable via environment variables or appConfig

Installation

npm install swissoid-back

Requirements

• Node.js >= 18
• Redis server for session storage
• SwissOID client credentials

Usage

With express-knifey / graphql-knifey (Recommended)

swissoid-back integrates seamlessly with express-knifey's middleware system:

import DiContainer, { mergeLDs } from 'di-why';
import { apolloSubgraphServerModularLDGen } from 'graphql-knifey';
import { swissoidAuthLoadDict } from 'swissoid-back';

// Define middleware configuration including OIDC routes
const middlewareConfig = {
  '/graphql': [
    { name: 'expressCorsMiddleware', priority: 90 },
    { name: 'expressCookieParserMiddleware', priority: 80 },
    { name: 'expressBodyParserMiddleware', priority: 70 },
    { name: 'expressGraphqlMiddleware', required: true, priority: -100 },
  ],
  '*': [
    // Add OIDC routes as global middleware
    { name: 'oidcStandardRoutesMiddleware', priority: 50 },
  ]
};

const diContainer = new DiContainer({
  load: mergeLDs(
    // GraphQL server with middleware config
    apolloSubgraphServerModularLDGen({
      resolvers,
      typeDefs,
      middlewareConfig
    }),

    // SwissOID authentication components
    swissoidAuthLoadDict,

    // Your other loaders...
  )
});

Direct Express Usage

import { swissoidAuthLoadDict } from 'swissoid-back';

// Load OIDC routes directly (this will mount them on the express app)
await diContainer.load('oidcStandardRoutes');

AppConfig Integration

swissoid-back provides an appConfigMap that can be merged with your application's configuration:

import { swissoidMergeAppConfigMap } from 'swissoid-back';

const merged = swissoidMergeAppConfigMap(yourAppConfigMap);
export type AppConfig = ReturnType<typeof merged>;

Configuration

Create a .env file with the required configuration (see .env.example for all options):

# 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

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379

# Session Configuration
SESSION_COOKIE_NAME=connect.sid
SESSION_SECRET=your-session-secret

# RP Configuration
RP_FRONTEND_URL=http://localhost:3000
COOKIE_DOMAIN=localhost
OIDC_REDIRECT_BASE_URL=http://localhost:3668

Routes

The package provides the following OIDC routes when loaded:

• GET /login - Initiates OIDC authorization flow
• POST /oidc/callback - Handles OIDC callback from SwissOID
• POST /oidc/finalize - Completes authentication and sets session
• GET /auth/status - Returns current authentication status
• POST /auth/logout - Logs out the user

Components

The swissoidAuthLoadDict includes:

• redisClient: Redis connection for session storage
• sessionService: Session management service
• cookieManager: Cookie handling utilities
• oidcStandardRoutes: Express router with OIDC endpoints
• oidcStandardRoutesMiddleware: Middleware-compatible version for express-knifey integration
• swissoidAppConfigMap: AppConfig map with priority 60

Exports

// Main LoadDict for di-why
import { swissoidAuthLoadDict } from 'swissoid-back';

// AppConfig utilities
import { swissoidMergeAppConfigMap } from 'swissoid-back';

// Individual loaders if needed
import {
  sessionService,
  cookieManager,
  oidcStandardRoutes,
  oidcStandardRoutesMiddleware
} from 'swissoid-back';

License

MIT