@flink-app/oidc-plugin 0.13.0

package/examples/basic-oidc.ts

@@ -0,0 +1,151 @@
+/**
+ * Basic OIDC Authentication Example
+ *
+ * Demonstrates:
+ * - Single OIDC provider configuration
+ * - OIDC Discovery
+ * - JIT (Just-In-Time) user provisioning
+ * - JWT token generation
+ */
+
+import { FlinkApp } from "@flink-app/flink";
+import { jwtAuthPlugin } from "@flink-app/jwt-auth-plugin";
+import { oidcPlugin } from "@flink-app/oidc-plugin";
+
+interface User {
+    _id?: string;
+    email: string;
+    name: string;
+    oidcConnections: Array<{
+        issuer: string;
+        subject: string;
+        provider: string;
+    }>;
+    createdAt: Date;
+}
+
+async function start() {
+    const app = new FlinkApp({
+        name: "Basic OIDC Example",
+
+        // Step 1: Configure JWT Auth Plugin
+        auth: jwtAuthPlugin({
+            secret: process.env.JWT_SECRET || "your-jwt-secret-min-32-chars-long",
+            getUser: async (tokenData) => {
+                // Fetch user from database using token data
+                return await app.ctx.repos.userRepo.getById(tokenData.userId);
+            },
+            rolePermissions: {
+                user: ["read", "write"],
+                admin: ["read", "write", "delete"],
+            },
+        }),
+
+        db: {
+            uri: process.env.MONGODB_URI || "mongodb://localhost:27017/oidc-example",
+        },
+
+        // Step 2: Configure OIDC Plugin
+        plugins: [
+            oidcPlugin({
+                providers: {
+                    // Provider name (used in URLs: /oidc/acme/initiate)
+                    acme: {
+                        // OIDC Issuer URL
+                        issuer: process.env.OIDC_ISSUER || "https://idp.acme.com",
+
+                        // Client credentials from IdP
+                        clientId: process.env.OIDC_CLIENT_ID || "your-client-id",
+                        clientSecret: process.env.OIDC_CLIENT_SECRET || "your-client-secret",
+
+                        // Callback URL (must match IdP configuration)
+                        callbackUrl: process.env.OIDC_CALLBACK_URL || "http://localhost:3000/oidc/acme/callback",
+
+                        // OIDC Discovery URL (automatic endpoint configuration)
+                        discoveryUrl: `${process.env.OIDC_ISSUER || "https://idp.acme.com"}/.well-known/openid-configuration`,
+
+                        // Scopes to request
+                        scope: ["openid", "email", "profile"],
+                    },
+                },
+
+                // Step 3: Implement JIT user provisioning
+                onAuthSuccess: async ({ profile, claims, provider }, ctx) => {
+                    console.log("OIDC authentication successful");
+                    console.log("Provider:", provider);
+                    console.log("Profile:", profile);
+                    console.log("Claims:", claims);
+
+                    // Find user by OIDC subject + issuer
+                    let user = await ctx.repos.userRepo.getOne({
+                        "oidcConnections.subject": claims.sub,
+                        "oidcConnections.issuer": claims.iss,
+                    });
+
+                    if (!user) {
+                        // JIT provisioning - create new user
+                        console.log("Creating new user via JIT provisioning");
+
+                        user = await ctx.repos.userRepo.create({
+                            email: claims.email,
+                            name: claims.name || profile.name || "Unknown User",
+                            oidcConnections: [
+                                {
+                                    issuer: claims.iss,
+                                    subject: claims.sub,
+                                    provider,
+                                },
+                            ],
+                            createdAt: new Date(),
+                        });
+
+                        console.log("User created:", user._id);
+                    } else {
+                        console.log("Existing user found:", user._id);
+                    }
+
+                    // Generate JWT token for the application
+                    const token = await ctx.plugins.jwtAuth.createToken(
+                        {
+                            userId: user._id,
+                            email: user.email,
+                        },
+                        ["user"]
+                    );
+
+                    console.log("JWT token generated");
+
+                    return {
+                        user,
+                        token,
+                        redirectUrl: "/dashboard",
+                    };
+                },
+
+                // Step 4: Handle authentication errors
+                onAuthError: async ({ error, provider }) => {
+                    console.error(`OIDC error for ${provider}:`, error);
+
+                    if (error.code === "access_denied") {
+                        return {
+                            redirectUrl: "/login?error=user_cancelled",
+                        };
+                    }
+
+                    return {
+                        redirectUrl: "/login?error=authentication_failed",
+                    };
+                },
+            }),
+        ],
+    });
+
+    await app.start();
+    console.log("App started on port 3000");
+    console.log("Visit: http://localhost:3000/oidc/acme/initiate to start OIDC flow");
+}
+
+start().catch((error) => {
+    console.error("Failed to start app:", error);
+    process.exit(1);
+});

package/examples/multi-provider.ts

@@ -0,0 +1,146 @@
+/**
+ * Multiple OIDC Providers Example
+ *
+ * Demonstrates:
+ * - Multiple OIDC providers (Azure AD, Okta)
+ * - Provider-specific configuration
+ * - User linking to multiple IdPs
+ */
+
+import { FlinkApp } from "@flink-app/flink";
+import { jwtAuthPlugin } from "@flink-app/jwt-auth-plugin";
+import { oidcPlugin } from "@flink-app/oidc-plugin";
+
+async function start() {
+    const app = new FlinkApp({
+        name: "Multi-Provider OIDC Example",
+
+        auth: jwtAuthPlugin({
+            secret: process.env.JWT_SECRET!,
+            getUser: async (tokenData) => {
+                return await app.ctx.repos.userRepo.getById(tokenData.userId);
+            },
+            rolePermissions: {
+                user: ["read", "write"],
+                admin: ["read", "write", "delete"],
+            },
+        }),
+
+        db: {
+            uri: process.env.MONGODB_URI!,
+        },
+
+        plugins: [
+            oidcPlugin({
+                providers: {
+                    // Azure AD / Entra ID
+                    azure: {
+                        issuer: `https://login.microsoftonline.com/${process.env.AZURE_TENANT_ID}/v2.0`,
+                        clientId: process.env.AZURE_CLIENT_ID!,
+                        clientSecret: process.env.AZURE_CLIENT_SECRET!,
+                        callbackUrl: "https://myapp.com/oidc/azure/callback",
+                        discoveryUrl: `https://login.microsoftonline.com/${process.env.AZURE_TENANT_ID}/v2.0/.well-known/openid-configuration`,
+                        scope: ["openid", "email", "profile"],
+                    },
+
+                    // Okta
+                    okta: {
+                        issuer: `https://${process.env.OKTA_DOMAIN}`,
+                        clientId: process.env.OKTA_CLIENT_ID!,
+                        clientSecret: process.env.OKTA_CLIENT_SECRET!,
+                        callbackUrl: "https://myapp.com/oidc/okta/callback",
+                        discoveryUrl: `https://${process.env.OKTA_DOMAIN}/.well-known/openid-configuration`,
+                        scope: ["openid", "email", "profile"],
+                    },
+
+                    // Auth0
+                    auth0: {
+                        issuer: `https://${process.env.AUTH0_DOMAIN}`,
+                        clientId: process.env.AUTH0_CLIENT_ID!,
+                        clientSecret: process.env.AUTH0_CLIENT_SECRET!,
+                        callbackUrl: "https://myapp.com/oidc/auth0/callback",
+                        discoveryUrl: `https://${process.env.AUTH0_DOMAIN}/.well-known/openid-configuration`,
+                        scope: ["openid", "email", "profile"],
+                    },
+                },
+
+                onAuthSuccess: async ({ profile, claims, provider }, ctx) => {
+                    // Try to find existing user by OIDC connection
+                    let user = await ctx.repos.userRepo.getOne({
+                        "oidcConnections.subject": claims.sub,
+                        "oidcConnections.issuer": claims.iss,
+                    });
+
+                    if (!user) {
+                        // Try to find by email (link existing account)
+                        user = await ctx.repos.userRepo.getOne({ email: claims.email });
+
+                        if (user) {
+                            // Link new provider to existing user
+                            console.log(`Linking ${provider} to existing user ${user._id}`);
+
+                            user.oidcConnections = user.oidcConnections || [];
+                            user.oidcConnections.push({
+                                issuer: claims.iss,
+                                subject: claims.sub,
+                                provider,
+                            });
+
+                            await ctx.repos.userRepo.updateOne(user._id, {
+                                oidcConnections: user.oidcConnections,
+                            });
+                        } else {
+                            // Create new user
+                            console.log(`Creating new user via ${provider}`);
+
+                            user = await ctx.repos.userRepo.create({
+                                email: claims.email,
+                                name: claims.name || profile.name || "Unknown User",
+                                oidcConnections: [
+                                    {
+                                        issuer: claims.iss,
+                                        subject: claims.sub,
+                                        provider,
+                                    },
+                                ],
+                                createdAt: new Date(),
+                            });
+                        }
+                    }
+
+                    const token = await ctx.plugins.jwtAuth.createToken(
+                        {
+                            userId: user._id,
+                            email: user.email,
+                        },
+                        ["user"]
+                    );
+
+                    return {
+                        user,
+                        token,
+                        redirectUrl: "/dashboard",
+                    };
+                },
+
+                onAuthError: async ({ error, provider }) => {
+                    console.error(`OIDC error for ${provider}:`, error);
+                    return {
+                        redirectUrl: `/login?error=${error.code}&provider=${provider}`,
+                    };
+                },
+            }),
+        ],
+    });
+
+    await app.start();
+    console.log("App started with multiple OIDC providers:");
+    console.log("- Azure AD: /oidc/azure/initiate");
+    console.log("- Okta: /oidc/okta/initiate");
+    console.log("- Auth0: /oidc/auth0/initiate");
+}
+
+start().catch((error) => {
+    console.error("Failed to start app:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@flink-app/oidc-plugin",
+  "version": "0.13.0",
+  "description": "Flink plugin for OIDC authentication with generic IdP support",
+  "author": "joel@frost.se",
+  "license": "MIT",
+  "types": "dist/index.d.ts",
+  "main": "dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "openid-client": "^5.7.0"
+  },
+  "peerDependencies": {
+    "mongodb": "^6.15.0",
+    "@flink-app/flink": "0.13.0",
+    "@flink-app/jwt-auth-plugin": "0.13.0"
+  },
+  "peerDependenciesMeta": {
+    "@flink-app/flink": {
+      "optional": false
+    },
+    "@flink-app/jwt-auth-plugin": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/jasmine": "^3.7.1",
+    "@types/node": "22.13.10",
+    "ts-node": "^10.9.2",
+    "tsc-watch": "^4.2.9",
+    "@flink-app/flink": "0.13.0",
+    "@flink-app/jwt-auth-plugin": "0.13.0",
+    "@flink-app/test-utils": "0.13.0"
+  },
+  "scripts": {
+    "test": "jasmine-ts --config=./spec/support/jasmine.json",
+    "test:watch": "nodemon --ext ts --exec 'jasmine-ts  --config=./spec/support/jasmine.json'",
+    "build": "tsc --project tsconfig.dist.json",
+    "watch": "tsc-watch --project tsconfig.dist.json",
+    "clean": "rimraf dist .flink"
+  }
+}

package/spec/handlers/InitiateOidc.spec.ts

@@ -0,0 +1,62 @@
+/**
+ * Tests for InitiateOidc handler
+ *
+ * Note: These are unit tests for handler logic.
+ * For full integration tests, use the test-utils package in a demo app.
+ */
+
+import InitiateOidc from "../../src/handlers/InitiateOidc";
+import { validateProvider } from "../../src/utils/error-utils";
+import { generateState, generateSessionId, generateNonce } from "../../src/utils/state-utils";
+
+describe("InitiateOidc handler", () => {
+    describe("Route configuration", () => {
+        it("should export correct route configuration", () => {
+            const { Route } = require("../../src/handlers/InitiateOidc");
+            expect(Route.path).toBe("/oidc/:provider/initiate");
+            expect(Route.method).toBe("get");
+        });
+    });
+
+    describe("Provider validation", () => {
+        it("should validate provider name format", () => {
+            expect(() => validateProvider("google")).not.toThrow();
+            expect(() => validateProvider("microsoft")).not.toThrow();
+            expect(() => validateProvider("custom-provider")).not.toThrow();
+        });
+
+        it("should reject invalid provider names", () => {
+            expect(() => validateProvider("")).toThrow();
+            expect(() => validateProvider("provider/slash")).toThrow();
+            expect(() => validateProvider("provider with spaces")).toThrow();
+        });
+    });
+
+    describe("Security parameter generation", () => {
+        it("should generate unique state", () => {
+            const state1 = generateState();
+            const state2 = generateState();
+
+            expect(state1).toBeDefined();
+            expect(state2).toBeDefined();
+            expect(state1).not.toBe(state2);
+            expect(state1.length).toBe(64);
+        });
+
+        it("should generate unique session ID", () => {
+            const id1 = generateSessionId();
+            const id2 = generateSessionId();
+
+            expect(id1).not.toBe(id2);
+            expect(id1.length).toBe(32);
+        });
+
+        it("should generate unique nonce", () => {
+            const nonce1 = generateNonce();
+            const nonce2 = generateNonce();
+
+            expect(nonce1).not.toBe(nonce2);
+            expect(nonce1.length).toBe(32);
+        });
+    });
+});

package/spec/helpers/reporter.ts

@@ -0,0 +1,34 @@
+/**
+ * Configure Jasmine spec reporter for verbose output
+ */
+
+import { SpecReporter } from "jasmine-spec-reporter";
+
+jasmine.getEnv().clearReporters();
+jasmine.getEnv().addReporter(
+    new SpecReporter({
+        spec: {
+            displaySuccessful: true,
+            displayFailed: true,
+            displayPending: true,
+            displayDuration: true,
+        },
+        summary: {
+            displaySuccessful: true,
+            displayFailed: true,
+            displayPending: true,
+            displayDuration: true,
+        },
+        colors: {
+            enabled: true,
+            successful: "green",
+            failed: "red",
+            pending: "yellow",
+        },
+        prefixes: {
+            successful: "✓ ",
+            failed: "✗ ",
+            pending: "- ",
+        },
+    })
+);

package/spec/helpers/test-helpers.ts

@@ -0,0 +1,108 @@
+/**
+ * Test helpers for OIDC plugin tests
+ */
+
+import { Db, MongoClient } from "mongodb";
+import { OidcProviderConfig } from "../../src/OidcProviderConfig";
+
+/**
+ * Create a mock MongoDB database for testing
+ */
+export async function createMockDb(): Promise<{ db: Db; client: MongoClient; cleanup: () => Promise<void> }> {
+    const client = new MongoClient("mongodb://localhost:27017", {
+        serverSelectionTimeoutMS: 5000,
+    });
+
+    await client.connect();
+    const db = client.db("oidc_plugin_test_" + Date.now());
+
+    const cleanup = async () => {
+        await db.dropDatabase();
+        await client.close();
+    };
+
+    return { db, client, cleanup };
+}
+
+/**
+ * Create a test OIDC provider configuration
+ */
+export function createTestProviderConfig(overrides?: Partial<OidcProviderConfig>): OidcProviderConfig {
+    return {
+        issuer: "https://test-idp.example.com",
+        clientId: "test-client-id",
+        clientSecret: "test-client-secret-at-least-32-chars-long",
+        callbackUrl: "http://localhost:3000/oidc/test/callback",
+        discoveryUrl: "https://test-idp.example.com/.well-known/openid-configuration",
+        scope: ["openid", "email", "profile"],
+        ...overrides,
+    };
+}
+
+/**
+ * Create a mock OIDC token set
+ */
+export function createMockTokenSet() {
+    return {
+        accessToken: "mock-access-token",
+        idToken: "mock-id-token",
+        refreshToken: "mock-refresh-token",
+        tokenType: "Bearer",
+        expiresIn: 3600,
+        scope: "openid email profile",
+        claims: {
+            sub: "user-123",
+            iss: "https://test-idp.example.com",
+            aud: "test-client-id",
+            exp: Math.floor(Date.now() / 1000) + 3600,
+            iat: Math.floor(Date.now() / 1000),
+            email: "test@example.com",
+            email_verified: true,
+            name: "Test User",
+            given_name: "Test",
+            family_name: "User",
+        },
+    };
+}
+
+/**
+ * Create a mock OIDC profile
+ */
+export function createMockProfile() {
+    return {
+        id: "user-123",
+        email: "test@example.com",
+        emailVerified: true,
+        name: "Test User",
+        givenName: "Test",
+        familyName: "User",
+        raw: {
+            sub: "user-123",
+            email: "test@example.com",
+            email_verified: true,
+            name: "Test User",
+            given_name: "Test",
+            family_name: "User",
+        },
+    };
+}
+
+/**
+ * Wait for a condition to be true
+ */
+export async function waitFor(condition: () => boolean | Promise<boolean>, timeout: number = 5000): Promise<void> {
+    const startTime = Date.now();
+    while (!(await condition())) {
+        if (Date.now() - startTime > timeout) {
+            throw new Error("Timeout waiting for condition");
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+}
+
+/**
+ * Sleep for a given number of milliseconds
+ */
+export function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/spec/plugin/OidcPlugin.spec.ts

@@ -0,0 +1,126 @@
+/**
+ * Tests for OidcPlugin factory
+ *
+ * Note: These are unit tests for plugin configuration and initialization logic.
+ * For full integration tests, use the test-utils package in a demo app.
+ */
+
+import { oidcPlugin } from "../../src/OidcPlugin";
+import { createTestProviderConfig } from "../helpers/test-helpers";
+
+describe("OidcPlugin", () => {
+
+    describe("configuration validation", () => {
+        it("should throw error if no providers configured", () => {
+            expect(() => {
+                oidcPlugin({
+                    providers: {},
+                    onAuthSuccess: async () => ({ user: {}, token: "", redirectUrl: "" }),
+                });
+            }).toThrowError(/At least one provider must be configured/);
+        });
+
+        it("should throw error if onAuthSuccess is missing", () => {
+            expect(() => {
+                oidcPlugin({
+                    providers: {
+                        test: createTestProviderConfig(),
+                    },
+                    onAuthSuccess: undefined as any,
+                });
+            }).toThrowError(/onAuthSuccess callback is required/);
+        });
+
+        it("should throw error if provider missing required fields", () => {
+            expect(() => {
+                oidcPlugin({
+                    providers: {
+                        test: {
+                            issuer: "https://test.example.com",
+                            clientId: "",
+                            clientSecret: "",
+                            callbackUrl: "",
+                        } as any,
+                    },
+                    onAuthSuccess: async () => ({ user: {}, token: "", redirectUrl: "" }),
+                });
+            }).toThrowError(/clientId is required/);
+        });
+
+        it("should throw error if encryption key too short", () => {
+            expect(() => {
+                oidcPlugin({
+                    providers: {
+                        test: createTestProviderConfig(),
+                    },
+                    encryptionKey: "short",
+                    onAuthSuccess: async () => ({ user: {}, token: "", redirectUrl: "" }),
+                });
+            }).toThrowError(/at least 32 characters/);
+        });
+
+        it("should accept valid configuration", () => {
+            expect(() => {
+                oidcPlugin({
+                    providers: {
+                        test: createTestProviderConfig(),
+                    },
+                    encryptionKey: "valid-encryption-key-at-least-32-chars-long",
+                    onAuthSuccess: async () => ({ user: {}, token: "", redirectUrl: "" }),
+                });
+            }).not.toThrow();
+        });
+    });
+
+    describe("plugin structure", () => {
+        it("should return plugin with correct ID", () => {
+            const plugin = oidcPlugin({
+                providers: {
+                    test: createTestProviderConfig(),
+                },
+                onAuthSuccess: async () => ({ user: {}, token: "", redirectUrl: "" }),
+            });
+
+            expect(plugin.id).toBe("oidc");
+        });
+
+        it("should configure database usage", () => {
+            const plugin = oidcPlugin({
+                providers: {
+                    test: createTestProviderConfig(),
+                },
+                onAuthSuccess: async () => ({ user: {}, token: "", redirectUrl: "" }),
+            });
+
+            expect(plugin.db).toBeDefined();
+            expect(plugin.db?.useHostDb).toBe(true);
+        });
+
+        it("should provide plugin context with API methods", () => {
+            const plugin = oidcPlugin({
+                providers: {
+                    test: createTestProviderConfig(),
+                },
+                onAuthSuccess: async () => ({ user: {}, token: "", redirectUrl: "" }),
+            });
+
+            expect(plugin.ctx).toBeDefined();
+            expect(plugin.ctx.getConnection).toBeDefined();
+            expect(plugin.ctx.getConnections).toBeDefined();
+            expect(plugin.ctx.deleteConnection).toBeDefined();
+            expect(plugin.ctx.options).toBeDefined();
+        });
+
+        it("should provide init function", () => {
+            const plugin = oidcPlugin({
+                providers: {
+                    test: createTestProviderConfig(),
+                },
+                onAuthSuccess: async () => ({ user: {}, token: "", redirectUrl: "" }),
+            });
+
+            expect(plugin.init).toBeDefined();
+            expect(typeof plugin.init).toBe("function");
+        });
+    });
+});