ssso

A modular, extensible authentication library for enterprise SSO (Single Sign-On) with first-class support for Next.js and React.

Features

✅ Modular Architecture - Pluggable authentication providers (SAML, OAuth, OIDC)
✅ OKTA SAML Support - Production-ready OKTA SAML 2.0 integration
✅ Next.js Integration - Server Components, API Routes, and Middleware support
✅ React Hooks & Components - Client-side authentication utilities
✅ Type-Safe - Full TypeScript support with generic user types
✅ Custom User Attributes - Type-safe custom SSO attributes from your provider
✅ Session Management - Secure encrypted sessions with iron-session
✅ Development Mode - Bypass authentication during local development
✅ Framework Agnostic Core - Use with any Node.js framework
✅ Minimal Dependencies - Only essential packages included

Installation

npm install ssso
# or
yarn add ssso
# or
pnpm add ssso

Quick Start

1. Configure Environment Variables

Create a .env.local file:

# Session Secret (Required - min 32 characters)
SESSION_SECRET=your-super-secret-key-min-32-characters-long

# OKTA SAML Configuration
OKTA_ENTRY_POINT=https://your-org.okta.com/app/your-app/sso/saml
OKTA_ISSUER=http://www.okta.com/exkabc123
OKTA_CALLBACK_URL=https://your-app.com/api/auth/saml/callback
OKTA_AUDIENCE=https://your-app.com/api/auth/saml/callback
OKTA_CERT=MIIDmjCCAoKgAwIBAgI...

2. Create Auth Configuration

// lib/auth.ts
import { createNextAuth } from "ssso/next";
import { OktaSamlProvider } from "ssso/providers/okta-saml";

export const auth = createNextAuth({
  session: {
    secret: process.env.SESSION_SECRET!,
    cookieName: "auth-session",
  },
  provider: new OktaSamlProvider(),
  providerConfig: {
    entryPoint: process.env.OKTA_ENTRY_POINT!,
    issuer: process.env.OKTA_ISSUER!,
    callbackUrl: process.env.OKTA_CALLBACK_URL!,
    audience: process.env.OKTA_AUDIENCE!,
    cert: process.env.OKTA_CERT!,
  },
});

3. Create API Routes

// app/api/auth/login/route.ts
import { auth } from "@/lib/auth";

export const GET = auth.handleLogin;

// app/api/auth/saml/callback/route.ts
export const POST = auth.handleCallback;

// app/api/auth/logout/route.ts
export const GET = auth.handleLogout;

// app/api/auth/user/route.ts
export const GET = auth.handleGetUser;

4. Protect Server Components

// app/dashboard/page.tsx
import { auth } from "@/lib/auth";

export default async function DashboardPage() {
  const user = await auth.requireAuth();

  return <div>Welcome, {user.email}!</div>;
}

5. Use in Client Components

"use client";

import { AuthProvider, useAuth } from "ssso/react";

export function App({ children }) {
  return <AuthProvider>{children}</AuthProvider>;
}

export function Profile() {
  const { user, loading } = useAuth();

  if (loading) return <div>Loading...</div>;
  if (!user) return <div>Not authenticated</div>;

  return <div>Hello, {user.email}</div>;
}

Documentation

• Getting Started Guide - Complete setup walkthrough
• Core Concepts - Understanding SSO, SAML, and authentication
• API Reference - Complete API documentation
• Next.js Integration - Next.js-specific features
• React Integration - React hooks and components
• OKTA SAML Setup - OKTA configuration guide
• Creating Custom Providers - Build your own auth provider
• Advanced Configuration - Production deployment & security
• Troubleshooting - Common issues and solutions

For AI/LLM Integration

• AI Quick Reference - Concise guide for AI assistants
• AI Complete Context - Full project understanding for AI

Examples

See the examples/ directory for complete working examples:

• OKTA SAML with Next.js - Full implementation
• Custom Provider - Building your own auth provider
• Middleware Protection - Route protection examples

Project Structure

ssso/
├── src/
│   ├── core/           # Core authentication logic
│   ├── providers/      # Authentication providers
│   │   └── okta-saml/  # OKTA SAML provider
│   ├── next/           # Next.js integration
│   ├── react/          # React hooks & components
│   ├── middleware/     # Next.js middleware
│   └── utils/          # Utilities
├── test/               # Comprehensive tests
├── docs/               # Documentation
└── examples/           # Example implementations

Why ssso?

Compared to NextAuth.js

• Enterprise SSO Focus - Built specifically for SAML/OKTA enterprise authentication
• Simpler API - Less configuration, more conventions
• Type-Safe - Full TypeScript support out of the box
• Modular - Use only what you need
• Next.js Native - Built for Next.js App Router

Compared to Passport.js

• Modern - Built for modern React/Next.js applications
• Session Management - Secure session handling included
• Type-Safe - Full TypeScript support
• React Integration - Hooks and components included

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines.

Support

• Documentation: ./docs
• Examples: ./examples
• Issues: GitHub Issues