oidc-client-ts with Redis Server-Side Support

Library to provide OpenID Connect (OIDC) and OAuth2 protocol support for client-side, browser-based JavaScript client applications with additional server-side Redis support for distributed session management. Also included is support for user session and access token management.

This project is a fork of IdentityModel/oidc-client-js which halted its development in June 2021. It has since been ported to TypeScript here with a similar API for the initial 2.0 release.

This fork extends the original with Redis server-side support for distributed session management, enabling server-side OIDC flows in Node.js environments.

Going forward, this library will focus only on protocols that continue to have support in OAuth 2.1. As such, the implicit grant is not supported by this client. Additional migration notes from oidc-client are available here.

Contributions and help are greatly appreciated!

Implements the following OAuth 2.0 protocols and supports OpenID Connect Core 1.0:

• Authorization Code Grant with Proof Key for Code Exchange (PKCE)
• Authorization Code Grant
• Resource Owner Password Credentials (ROPC) Grant
• Refresh Token Grant
• Silent Refresh Token in iframe Flow

✨ New: Server-Side Redis Support

This fork adds powerful server-side capabilities:

• RedisStateStore: Redis-backed state storage for distributed sessions
• ServerSideOidcClient: Process OIDC callbacks on the server side
• ServerSideUserManager: High-level session management with Redis
• Distributed Sessions: Share authentication state across multiple server instances
• Production Ready: Built for microservices and load-balanced environments

Quick Start with Redis

npm install @ridha.bouazizi/oidc-client-ts-redis redis

import { ServerSideUserManager } from '@ridha.bouazizi/oidc-client-ts-redis';
import { createClient } from 'redis';

const redisClient = createClient({ url: 'redis://localhost:6379' });
await redisClient.connect();

const userManager = new ServerSideUserManager({
    authority: 'https://your-oidc-provider.com',
    client_id: 'your-client-id', 
    client_secret: 'your-client-secret',
    redirect_uri: 'https://your-app.com/auth/callback',
    scope: 'openid profile email',
    redisClient,
    redisConfig: { keyPrefix: 'app:oidc:', ttl: 3600 }
});

// Handle signin callback
const user = await userManager.signinCallback(callbackUrl);

// Store user session in Redis
await userManager.storeUserSession(sessionId, user);

📖 Complete Server-Side Guide

Table of Contents

• 📚 Documentation Index - Complete documentation guide
• Documentation
• Server-Side Redis Guide
• Redis State Store Documentation
• Implementation Summary
• Working Examples
• Changelog
• Installation
• Building the Source
• Contributing
• License

Installation

Client-Side (Browser)

Using npm

$ npm install oidc-client-ts --save

Server-Side with Redis

Using npm

$ npm install @ridha.bouazizi/oidc-client-ts-redis redis --save

Or with ioredis:

$ npm install @ridha.bouazizi/oidc-client-ts-redis ioredis --save

Building the Source

$ git clone https://github.com/ridha-bouazizi/oidc-client-ts.git
$ cd oidc-client-ts
$ npm install
$ npm run build

Running the Redis Examples

Server-side examples with Redis

$ cd examples
$ npm install
$ cp .env.sample .env
# Edit .env with your OIDC provider and Redis settings
$ npm run setup    # Test setup
$ npm run server   # Start demo server

Browse to http://localhost:3000 to test the server-side OIDC flow.

Running the Sample

Parcel project

$ cd samples/Parcel
$ npm install
$ npm run start

and then browse to http://localhost:1234.

Angular app

can be found here.

Running the Tests

$ npm test

What's New in This Fork

This Redis-enabled fork adds powerful server-side capabilities while maintaining 100% backward compatibility:

🔥 Key Features

• Distributed Sessions: Share authentication state across multiple server instances
• Redis Integration: Production-ready Redis state storage with automatic cleanup
• Server-Side OIDC: Process signin callbacks on the server side for enhanced security
• Framework Agnostic: Works with Express, Next.js, Fastify, and any Node.js framework
• Production Ready: Built for microservices and load-balanced environments

🚀 Quick Example

// Install the Redis-enabled package
npm install @ridha.bouazizi/oidc-client-ts-redis redis

// Use server-side session management
const userManager = new ServerSideUserManager({
    authority: 'https://your-oidc-provider.com',
    client_id: 'your-client-id',
    client_secret: 'your-client-secret', 
    redisClient: createClient({ url: 'redis://localhost:6379' }),
    redisConfig: { keyPrefix: 'app:oidc:', ttl: 3600 }
});

// Handle signin callback on server
const user = await userManager.signinCallback(req.url);
await userManager.storeUserSession(sessionId, user);

📚 Complete Documentation

• 🔧 Server-Side Setup Guide - Complete integration guide
• ⚡ Quick Start - Get up and running in minutes
• 💡 Working Examples - Copy-paste examples for Express, Next.js
• 🔍 Implementation Details - Technical deep dive
• 📝 Changelog - What's new and changed

Contributing

We appreciate feedback and contribution to this repo!

License

This project is licensed under the Apache-2.0 license. See the LICENSE file for more info.