Auth0 Infrastructure

Auth0 handles authentication and organisation-based SSO for the FSA Platform.

Key Files

Type	Location
Auth0 Client	`packages/core/src/infrastructure/auth0/client.ts`
Auth Utilities	`apps/web/src/lib/auth.ts`
Repositories	`packages/core/src/infrastructure/repositories/auth0-*-repository.ts`

Authentication Flow

Authentication is handled by Next.js middleware (proxy.ts). Unauthenticated users are redirected automatically.

JWT Claims

interface Auth0User {
  sub: string;           // Auth0 user ID (auth0|abc123)
  email: string;
  email_verified: boolean;
  name?: string;
  org_id?: string;       // Auth0 organisation ID
}

Organisation-Based SSO

Each Account links to an Auth0 Organisation for SSO:

Linking Account to Auth0 Org

const useCase = new CreateAndLinkAuth0Organisation();
await useCase.execute({ accountId, orgName, auth0UserId });

Management API

// packages/core/src/infrastructure/auth0/client.ts
import { ManagementClient } from 'auth0';

const management = new ManagementClient({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_MGMT_CLIENT_ID!,
  clientSecret: process.env.AUTH0_MGMT_CLIENT_SECRET!,
});

Common Operations

// Create organisation
await management.organizations.create({ name: 'slug', display_name: 'Name' });

// Invite member
await management.organizations.createInvitation(
  { id: orgId },
  { inviter: { name }, invitee: { email }, client_id, send_invitation_email: true }
);

// Get members
await management.organizations.getMembers({ id: orgId });

// Check user exists
const users = await management.users.getByEmail(email);

Environment Variables

AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=xxx
AUTH0_CLIENT_SECRET=xxx
AUTH0_MGMT_CLIENT_ID=xxx
AUTH0_MGMT_CLIENT_SECRET=xxx

Best Practices

Rely on middleware for auth - proxy.ts handles authentication
Sync with local data - keep User entity updated with Auth0
Handle org context - check org_id claim for multi-tenant
Validate roles server-side - never trust client claims
Secure Management API - keep credentials safe

Type	Location
Client	`packages/core/src/infrastructure/auth0/client.ts`
Middleware	`apps/web/src/middleware.ts`
Auth Utilities	`apps/web/src/lib/auth.ts`
Repositories	`packages/core/src/infrastructure/repositories/auth0-*-repository.ts`

On this page