OIDC Integration Guide

Download Markdown

Complete guide for integrating iuv.one OIDC authentication into your applications.

This guide covers setup for iuv.so, iuv.app, iuv.sh, and any other applications in the iuv ecosystem.

🚀 Quick Start (5 minutes)

1. Create OAuth app in iuv.one dashboard

2. Add redirect URI: http://localhost:3000/auth/callback

3. Install dependencies: npm install next-auth

4. Configure provider with your client credentials

5. Test login flow between your app and iuv.one

Jump to configuration →

Overview

iuv.one provides unified authentication across the entire iuv ecosystem. By integrating with iuv.one's OIDC provider, your application gains:

Single Sign-On

Secure by Default

OAuth 2.0 + OpenID Connect standards

User Management

Centralized user profiles and permissions

Developer Friendly

Standard libraries and easy integration

Prerequisites

✓iuv.one running locally on port 3001
✓Your application running on localhost (any port)
✓OAuth application created in iuv.one dashboard
✓Client ID and Client Secret from iuv.one
✓Redirect URI configured: http://localhost:YOUR_PORT/auth/callback

Configuration

Local Development Endpoints

Use these endpoints when developing locally:

json

{
  "issuer": "http://localhost:3001",
  "authorization_endpoint": "http://localhost:3001/oauth/authorize",
  "token_endpoint": "http://localhost:3001/api/oauth/token",
  "userinfo_endpoint": "http://localhost:3001/api/oauth/userinfo",
  "jwks_uri": "http://localhost:3001/api/oauth/jwks",
  "revocation_endpoint": "http://localhost:3001/api/oauth/revoke"
}

OAuth Application Settings

Create an OAuth application in iuv.one with these settings:

Name	`your-app-local`
Client ID	`your-app-local`
Client Secret	`generate-secure-secret`
Redirect URIs	`http://localhost:3000/auth/callback`
Grant Types	`authorization_code, refresh_token`
Scopes	`openid, profile, email`
PKCE	`Required`

Environment Variables

Add these to your application's .env.local file:

bash

# iuv.one OIDC Configuration
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-nextauth-secret-here

IUV_ONE_CLIENT_ID=your-app-local
IUV_ONE_CLIENT_SECRET=your-generated-client-secret
IUV_ONE_ISSUER=http://localhost:3001

Implementation

Next.js with NextAuth.js (Recommended)

For Next.js applications, use NextAuth.js for seamless integration:

1. Install dependencies

bash

npm install next-auth

2. Configure NextAuth

typescript

// app/api/auth/[...nextauth]/route.ts
import NextAuth from 'next-auth';

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    {
      id: 'iuv-one',
      name: 'iuv.one',
      type: 'oidc',
      issuer: process.env.IUV_ONE_ISSUER,
      clientId: process.env.IUV_ONE_CLIENT_ID!,
      clientSecret: process.env.IUV_ONE_CLIENT_SECRET!,
      authorization: {
        params: {
          scope: 'openid profile email',
        },
      },
    },
  ],
  callbacks: {
    async jwt({ token, account }) {
      if (account) {
        token.accessToken = account.access_token;
      }
      return token;
    },
    async session({ session, token }) {
      session.accessToken = token.accessToken;
      return session;
    },
  },
});

export const { GET, POST } = handlers;

3. Create login page

tsx

// app/login/page.tsx
'use client';

import { signIn } from 'next-auth/react';

export default function LoginPage() {
  return (
    <div className="flex items-center justify-center min-h-screen">
      <button
        onClick={() => signIn('iuv-one')}
        className="bg-blue-600 text-white px-6 py-3 rounded-lg hover:bg-blue-700"
      >
        Sign in with iuv.one
      </button>
    </div>
  );
}

4. Protect routes

tsx

// components/AuthGuard.tsx
'use client';

import { useSession } from 'next-auth/react';
import { useRouter } from 'next/navigation';

export function AuthGuard({ children }: { children: React.ReactNode }) {
  const { data: session, status } = useSession();
  const router = useRouter();

  if (status === 'loading') return <div>Loading...</div>;
  if (!session) {
    router.push('/login');
    return null;
  }

  return <>{children}</>;
}

React with oidc-client-ts

For vanilla React applications, use oidc-client-ts:

1. Install dependencies

bash

npm install oidc-client-ts

2. Configure OIDC client

typescript

// src/auth/oidc.ts
import { UserManager, WebStorageStateStore } from 'oidc-client-ts';

export const userManager = new UserManager({
  authority: 'http://localhost:3001',
  client_id: process.env.REACT_APP_IUV_ONE_CLIENT_ID!,
  redirect_uri: 'http://localhost:3000/auth/callback',
  response_type: 'code',
  scope: 'openid profile email',
  post_logout_redirect_uri: 'http://localhost:3000/',
  userStore: new WebStorageStateStore({ store: window.localStorage }),
  automaticSilentRenew: true,
});

export const login = () => userManager.signinRedirect();
export const logout = () => userManager.signoutRedirect();
export const getUser = () => userManager.getUser();

Other Frameworks

Most web frameworks have OIDC libraries. Here are popular options:

Vue.js

vue-oidc-client or oidc-client-ts

Angular

angular-auth-oidc-client

Svelte

@auth/sveltekit or oidc-client-ts

Express.js

openid-client or passport-openidconnect

Testing & Verification

Test Flow

✓Start iuv.one locally: cd iuv-one && bun dev
✓Start your app locally: bun dev
✓Create OAuth app in iuv.one dashboard
✓Visit your app's login page
✓Click 'Sign in with iuv.one'
✓Complete authentication in iuv.one
✓Verify redirect back to your app with valid session

Success Criteria

✓User can sign in using iuv.one credentials
✓Session persists across page refreshes
✓Protected routes are accessible after login
✓Logout clears session across platforms
✓No console errors in browser dev tools
✓OIDC compliance (check with debugger tool)

Debug Commands

Check OIDC discovery:

bash

curl http://localhost:3001/.well-known/openid-configuration

Test JWKS endpoint:

bash

curl http://localhost:3001/api/oauth/jwks

Check browser storage:

Open DevTools → Application → Local Storage → look for oidc.user:...

Troubleshooting

CORS Errors

Solution: Ensure iuv.one allows your localhost origin in CORS settings.

Check iuv.one's CORS configuration to include http://localhost:YOUR_PORT

Invalid Redirect URI

Solution: Ensure redirect URI in iuv.one exactly matches your callback URL.

Must be: http://localhost:YOUR_PORT/auth/callback

PKCE Required Error

Solution: Use a modern OIDC library that supports PKCE (NextAuth.js, oidc-client-ts).

Token Validation Fails

Solution: Verify JWKS endpoint is accessible and certificates are valid.

bash

curl http://localhost:3001/api/oauth/jwks

Session Not Persisting

Solution: Check localStorage is enabled and not being cleared by browser settings.

Production Deployment

⚠️

Before deploying to production, update your OAuth application configuration:

Update Redirect URIs

Change from localhost to your production domain:

text

https://yourapp.com/auth/callback https://yourapp.com/api/auth/callback/iuv-one

Update Environment Variables

bash

# Production
NEXTAUTH_URL=https://yourapp.com
IUV_ONE_ISSUER=https://iuv.one

# Keep client credentials secure
IUV_ONE_CLIENT_ID=your-production-client-id
IUV_ONE_CLIENT_SECRET=your-production-client-secret

Security Checklist

✓Use HTTPS in production
✓Store client secrets securely (not in code)
✓Validate all redirect URIs
✓Enable token rotation
✓Monitor authentication logs

Need Help?

If you run into issues or need clarification:

Main Documentation - General OIDC information
API Reference - Detailed endpoint documentation
GitHub Repository - Source code and issue tracker
OIDC Discovery Document - Live configuration