Quick start
This page builds the smallest working backend: sign-in, session cookie, /auth/me and one protected route. It uses in-memory stores, which are only fit for a demo or a single instance: see Production checklist before deploying.
Prerequisites
- The SDK installed, with
fastify>=5.12.6. - An application registered in auth-service with the redirect URI
https://app.example.com/auth/callbackand a back-channel logout URIhttps://app.example.com/auth/backchannel-logout. - Three values in your environment:
AUTH_ISSUER(the auth-service URL),AUTH_CLIENT_SECRETandAUTH_COOKIE_SECRET(at least 32 random characters, for exampleopenssl rand -base64 48).
The server
import Fastify from "fastify";
import {
GrantManager,
MemoryGrantStore,
createAuthClient,
} from "@circle-rd/auth-ai";
import { authPlugin, requireAuth } from "@circle-rd/auth-ai/fastify";
import { MemorySessionStore, createAuthHandlers } from "@circle-rd/auth-ai/web";
// A missing secret must stop the process: an undefined clientSecret would
// silently turn the client into a public one.
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Missing environment variable ${name}`);
return value;
}
const auth = createAuthClient({
issuer: env("AUTH_ISSUER"),
clientId: "my-app",
clientSecret: env("AUTH_CLIENT_SECRET"),
redirectUri: "https://app.example.com/auth/callback",
postLogoutRedirectUri: "https://app.example.com/auth/logout/callback",
});
const grants = new GrantManager({ auth, store: new MemoryGrantStore() });
const handlers = await createAuthHandlers({
auth,
grants,
sessions: new MemorySessionStore(),
secret: env("AUTH_COOKIE_SECRET"),
});
const app = Fastify();
await app.register(authPlugin, { handlers });
app.get("/api/profile", { preHandler: requireAuth(handlers) }, async (request) => {
const { claims } = request.authSession!;
return { sub: claims.sub, roles: claims.roles ?? [] };
});
await app.listen({ host: "0.0.0.0", port: 3000 });
createAuthClient validates its configuration and throws CFG_001 on any invalid value (a trailing slash on issuer, a non-HTTPS URL, a missing openid scope…). createAuthHandlers also checks that redirectUri ends with <basePath>/callback; basePath defaults to /auth.
What you get
authPlugin serves five routes below /auth:
| Route | Method | What it does |
|---|---|---|
/auth/login | GET | Redirects to auth-service. Accepts ?next=/path (same-origin paths only) and ?prompt=. |
/auth/callback | GET | Completes the sign-in, creates the session and redirects to next. |
/auth/me | GET | Returns { user, expiresAt }, or 401 with SES_001 when signed out. |
/auth/logout | POST | Ends the session, then redirects (303) to the provider's logout URL, or answers { logoutUrl } when the request sends Accept: application/json. Without a session the provider's logout URL is still returned, without id_token_hint: the provider asks the user to confirm, then ends the single sign-on session. |
/auth/backchannel-logout | POST | Called by auth-service to end sessions. |
Open https://app.example.com/auth/login?next=/api/profile in a browser: you are sent to auth-service, sign in, and land on /api/profile with a session cookie. The cookie is HttpOnly, Secure, SameSite=Lax and prefixed with __Host- on HTTPS; the browser never sees a token.
redirectUri may be http://localhost:3000/auth/callback (and only for localhost, 127.0.0.1 or [::1]). The cookies then lose the Secure flag and the __Host- prefix.Where to go next
- Fastify backend for the complete setup: logging, AI routes, logout hooks.
- React app or Vue app for the frontend.
- Architecture to understand why the browser holds no token.