Auth0 IntegrationCopy Anchor Link

Use Auth0 when the identity provider should host login and enterprise connections while Farm owns the application-facing OAuth routes and local session.

The built-in flow uses Authorization Code with PKCE, validates signed state, reads the user profile, and stores that profile in a signed HTTP-only cookie.

Add Auth0Copy Anchor Link

farm add integration auth0 --ui

ConfigureCopy Anchor Link

import { auth0 } from "@farm.js/auth0";

export const appIntegrations = {
  auth: auth0({
    domain: process.env.AUTH0_DOMAIN,
    clientId: process.env.AUTH0_CLIENT_ID,
    clientSecret: process.env.AUTH0_CLIENT_SECRET,
    secret: process.env.AUTH0_SECRET,
    appBaseUrl: process.env.APP_BASE_URL,
    callbackPath: "/auth/callback",
    protectedRoutes: ["/dashboard(.*)"],
  }),
} as const;

export type AppIntegrations = typeof appIntegrations;

callbackPath stays root-relative. Farm combines it with APP_BASE_URL, or the incoming request origin, to create the callback URL sent to Auth0.

You can use callbackUrl instead, but it must be absolute:

auth0({
  callbackUrl: "https://app.example.com/auth/callback",
});

Choose route ownershipCopy Anchor Link

Let Farm construct the Auth0 flowCopy Anchor Link

The configuration above is the default path. When instance is omitted, Farm constructs the OAuth flow from the Auth0 domain, client credentials, session secret, callback settings, and scopes. Farm then owns the login, signup, callback, logout, profile, and protected-route behavior.

Provide application-owned middlewareCopy Anchor Link

auth0({
  instance: {
    matcher: ["/auth(.*)", "/dashboard(.*)"],
    middleware(request) {
      return myAuth0Middleware(request);
    },
  },
});

This advanced path accepts a compatible middleware adapter rather than the Auth0 SDK itself. The supplied instance wins and Farm only mounts its middleware; it does not create the built-in login, callback, logout, or profile routes.

Environment variablesCopy Anchor Link

Without AUTH0_SECRET, development generates a random secret once per app in .farm/auth0-secret (gitignored) and reuses it across restarts. Production startup fails when no secret is configured.

Routes and methodsCopy Anchor Link

Every path can be changed with loginPath, signUpPath, callbackPath, logoutPath, or profilePath.

Start loginCopy Anchor Link

Normal document navigation redirects directly:

<a href="/auth/login?returnTo=/dashboard">Sign in</a>

The typed integration client asks for the redirect URL as JSON:

const result = await apiClient.auth.login.get({
  query: {
    returnTo: "/dashboard",
  },
});

if (result.data) {
  window.location.assign(result.data.redirectTo);
}

Signup uses the same shape through apiClient.auth.signup.get(...).

Read the profileCopy Anchor Link

const result = await api.auth.profile.get();

if (result.error && "status" in result.error && result.error.status === 401) {
  // No valid local Auth0 session.
}

const user = result.data?.user;

The session cookie contains the fetched Auth0 profile and an expiry derived from the token response. The integration does not persist refresh tokens, so an expired local session requires a new login.

Session lifetime and sign-outCopy Anchor Link

The session is a signed cookie, not a server-side record. Sign-out clears the cookie in that browser, but a copy of it (from another device, a log, or malware) keeps working until it expires, which by default is the token lifetime Auth0 returns (often 24 hours). Two options narrow that:

const revoked = new Set<string>(); // use a shared store (Redis, your database) in production

auth0({
  // Sign-ins last at most an hour, whatever the token lifetime.
  sessionMaxAge: 60 * 60,
  // Record the ending session on sign-out, and reject it on every later read.
  onSignOut(session) {
    if (session.sessionId) revoked.add(session.sessionId);
  },
  isSessionRevoked(session) {
    return session.sessionId !== undefined && revoked.has(session.sessionId);
  },
});

isSessionRevoked runs for the profile route and protected routes. Sessions issued before these options existed carry no sessionId or issue time; they end at their original expiry.

Protect app routesCopy Anchor Link

auth0({
  protectedRoutes: ["/dashboard(.*)", "/settings(.*)"],
});

A signed-out request is redirected with status 303, so the browser follows it with a GET, to:

/auth/login?returnTo=/the/original/path

Only root-relative returnTo values are accepted. Invalid or external values fall back to /dashboard.

OptionsCopy Anchor Link

Cookie namesCopy Anchor Link

A sibling subdomain (evil.example.com next to app.example.com) can set a cookie for .example.com with a longer Path. Browsers send that cookie first, so it would pick which session or login state the app reads. A __Host- name cannot be set from another host, so use one in production:

auth0({
  cookieName: "__Host-farm_auth0_session",
  stateCookieName: "__Host-farm_auth0_state",
});

Farm adds the Secure, Path=/, and no-Domain attributes the prefix requires. Browsers accept such cookies over https and from http://localhost; on another plain-http dev host keep the defaults. Renaming the session cookie signs existing users out once.

Cross-site request protectionCopy Anchor Link

The sign-out route (GET /auth/logout) only accepts requests from the app's own origin. A cross-site request is answered with 403 before the session is cleared, so another site cannot force a visitor to sign out.

List any other trusted origin explicitly. The pattern syntax matches serverActions.allowedOrigins:

auth0({
  allowedOrigins: ["https://portal.example.com", "*.example.com"],
});

A sign-out link or bookmark keeps working; only an explicitly cross-site navigation is rejected.

Production checklistCopy Anchor Link

• Allow the exact callback URL in Auth0.
• Allow the app origin as a logout URL.
• Use a strong AUTH0_SECRET.
• Set APP_BASE_URL behind proxies or custom domains.
• Test bad state, callback errors, expired cookies, login return paths, and logout.