.

Author: kantord

OIDC_SETUP.md

@@ -0,0 +1,81 @@
+# OIDC Authentication Setup
+
+This application supports authentication with any OIDC-compliant identity provider (Okta, Keycloak, Auth0, etc.).
+
+## Configuration
+
+1. **Configure your OIDC provider** with these settings:
+   - **Callback URL**: `http://localhost:3000/api/auth/oauth2/callback/oidc` (adjust domain/port for production)
+   - **Grant Types**: Authorization Code, Refresh Token
+   - **Response Type**: code
+   - **Scopes**: openid, email, profile
+
+2. **Set environment variables** in `.env.local`:
+
+```bash
+# Better Auth Configuration
+BETTER_AUTH_SECRET=your-random-secret-here
+BETTER_AUTH_URL=http://localhost:3000
+
+# OIDC Provider Configuration
+OIDC_CLIENT_ID=your-client-id
+OIDC_CLIENT_SECRET=your-client-secret
+OIDC_ISSUER_URL=https://your-oidc-provider.com
+```
+
+## Local Development
+
+For local testing, this repo includes a test OIDC provider:
+
+1. **Start the OIDC provider**:
+   ```bash
+   pnpm oidc
+   ```
+
+2. **Use these credentials** in `.env.local`:
+   ```bash
+   OIDC_CLIENT_ID=better-auth-dev
+   OIDC_CLIENT_SECRET=dev-secret-change-in-production
+   OIDC_ISSUER_URL=http://localhost:4000
+   ```
+
+3. **Run the app**:
+   ```bash
+   pnpm dev
+   ```
+
+   Or run both concurrently:
+   ```bash
+   pnpm dev
+   ```
+
+The test provider automatically logs in as `[email protected]`.
+
+## Provider-Specific Guides
+
+### Okta
+
+1. Create a new App Integration (OIDC - Web Application)
+2. Set Callback URL: `http://localhost:3000/api/auth/oauth2/callback/oidc`
+3. Use Okta domain as OIDC_ISSUER_URL (e.g., `https://dev-12345.okta.com`)
+
+### Keycloak
+
+1. Create a new Client
+2. Set Access Type: confidential
+3. Set Valid Redirect URIs: `http://localhost:3000/api/auth/oauth2/callback/oidc`
+4. Use Realm URL as OIDC_ISSUER_URL (e.g., `https://keycloak.example.com/realms/myrealm`)
+
+### Auth0
+
+1. Create a Regular Web Application
+2. Set Allowed Callback URLs: `http://localhost:3000/api/auth/oauth2/callback/oidc`
+3. Use Auth0 domain as OIDC_ISSUER_URL (e.g., `https://your-tenant.auth0.com`)
+
+## Architecture
+
+This application uses **stateless authentication**:
+- No database required
+- Session data stored in encrypted JWE cookies
+- 7-day session expiration with 30-day refresh window
+- Works with any OIDC-compliant provider

dev/oidc-provider.mjs

@@ -19,7 +19,13 @@ const configuration = {
 		{
 			client_id: "better-auth-dev",
 			client_secret: "dev-secret-change-in-production",
-			redirect_uris: ["http://localhost:3000/api/auth/callback/oidc"],
+			redirect_uris: [
+				// Better Auth genericOAuth uses /oauth2/callback/:providerId
+				"http://localhost:3000/api/auth/oauth2/callback/oidc",
+				"http://localhost:3001/api/auth/oauth2/callback/oidc",
+				"http://localhost:3002/api/auth/oauth2/callback/oidc",
+				"http://localhost:3003/api/auth/oauth2/callback/oidc",
+			],
 			response_types: ["code"],
 			grant_types: ["authorization_code", "refresh_token"],
 			token_endpoint_auth_method: "client_secret_post",
@@ -52,7 +58,6 @@ const configuration = {
 	},
 	features: {
 		devInteractions: { enabled: true }, // Enable dev interactions for easy testing
-		refreshToken: { enabled: true },
 	},
 	ttl: {
 		AccessToken: 3600, // 1 hour

lib/auth-client.ts

@@ -4,7 +4,8 @@
   "private": true,
   "packageManager": "[email protected]",
   "scripts": {
-    "dev": "next dev",
+    "dev": "concurrently -n \"OIDC,Next\" -c \"blue,green\" \"pnpm oidc\" \"pnpm dev:next\"",
+    "dev:next": "next dev",
     "build": "next build",
     "start": "next start",
     "lint": "biome check",
@@ -30,6 +31,7 @@
     "@types/react-dom": "^19",
     "@vitejs/plugin-react": "^5.1.1",
     "babel-plugin-react-compiler": "1.0.0",
+    "concurrently": "^9.2.1",
     "husky": "^9.1.7",
     "jsdom": "^27.2.0",
     "lint-staged": "^16.0.0",