Single Sign-On (SSO)

Use the AuthForm component

import { AuthForm } from '@entity-auth/components';

<AuthForm 
  client={ea} 
  workspaceTenantId="your-tenant"
  redirectTo="/dashboard"
/>

The user clicks "Sign in with Google", completes OAuth, and is redirected back with a session cookie. It just works!

Add Entity Auth middleware

For Next.js 13+ apps, create middleware.ts in your app root:

import { entityAuthMiddleware } from '@entityauth/nextjs/middleware';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  return entityAuthMiddleware(request, {
    entityAuthUrl: process.env.NEXT_PUBLIC_ENTITY_AUTH_URL || 'https://entity-auth.com',
    workspaceTenantId: process.env.NEXT_PUBLIC_ENTITY_AUTH_WORKSPACE_TENANT_ID || '',
    protectedRoutes: ['/dashboard/*', '/profile'],
    publicRoutes: ['/'],
    loginUrl: '/auth',
  });
}

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

What this does:

Detects SSO redirect with __ea_ticket parameter, exchanges ticket for refresh token server-side (before page loads), sets cookie on your domain, redirects to clean URL, protects authenticated routes. Zero client-side complexity!

Update your AuthProvider

Ensure your auth provider seeds the refresh token from the cookie:

import { EntityAuthClient } from '@entityauth/auth-client';

const ea = new EntityAuthClient({
  baseURL: process.env.NEXT_PUBLIC_ENTITY_AUTH_URL,
});

useEffect(() => {
  // Seed refresh token from cookie (set by middleware)
  const cookieMatch = document.cookie.match(/(?:^|;\s*)ea_refresh=([^;]+)/);
  const cookieToken = cookieMatch?.[1];
  if (cookieToken) {
    localStorage.setItem("ea_refresh_token", cookieToken);
    ea.setRefreshToken(cookieToken);
  }
}, []);

Add SSO buttons to your login page

async function loginWithGoogle() {
  try {
    const { authorizationUrl } = await client.startSSO({
      provider: "google",
      returnTo: "/dashboard",
    });
    window.location.href = authorizationUrl;
  } catch (e) {
    const error = e as Error;
    alert(`Google sign-in error: ${error.message}`);
  }
}

async function loginWithGitHub() {
  try {
    const { authorizationUrl } = await client.startSSO({
      provider: "github",
      returnTo: "/dashboard",
    });
    window.location.href = authorizationUrl;
  } catch (e) {
    const error = e as Error;
    alert(`GitHub sign-in error: ${error.message}`);
  }
}

Flow:

1. User clicks "Sign in with Google"
2. client.startSSO() calls Entity Auth service (uses configured baseURL)
3. Completes OAuth on EntityAuth
4. EntityAuth redirects to https://your-app.com/dashboard?__ea_ticket=abc123
5. TicketExchangeHandler detects the ticket and exchanges it for a refresh token
6. Refresh token is stored and user is authenticated!