You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
155 lines
4.0 KiB
Markdown
155 lines
4.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
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):
|
|
|
|
```env
|
|
# 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
|
|
|
|
```typescript
|
|
// 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 |