# auth.oauth-sign-in Sign users in with an OpenID Connect issuer (Google, Microsoft Entra ID, Auth0, Okta, Keycloak) or with GitHub, using the OAuth 2.0 authorisation-code flow with PKCE (RFC 7636, S256), and keep them signed in with a session cookie signed by `SESSION_SECRET`. No database is needed for either cookie. `AUTH_PROVIDER` picks the provider: - **oidc** finds the issuer's endpoints by discovery (`OIDC_ISSUER/.well-known/openid-configuration`), checks the document is for that issuer, and asks for `OIDC_SCOPES` (`openid email profile` unless you say). A confidential client sends `OIDC_CLIENT_SECRET` (client_secret_post); a public client leaves it unset and relies on PKCE. The user comes from the id_token's claims: its issuer, audience, nonce and expiry are checked. Its signature is not, because it came straight from the token endpoint over TLS (OpenID Connect Core 1.0, section 3.1.3.7); never pass this function an id_token you received any other way. - **github** uses a GitHub OAuth app (`GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`) with PKCE, then reads `/user` and the primary verified address from `/user/emails`. GitHub reports a bad code with status 200 and an `error` field; that is thrown like any other refusal. ## Wiring it up ```ts // app/login/route.ts (Next.js) import { beginSignIn } from "#fune/auth.oauth-sign-in@^1"; export async function GET() { const start = await beginSignIn("https://app.example.com/callback", "/dashboard"); return new Response(null, { status: 302, headers: { location: start.url, "set-cookie": start.setCookie } }); } // app/callback/route.ts import { completeSignIn, createSession, sessionCookie } from "#fune/auth.oauth-sign-in@^1"; import { cookies } from "next/headers"; export async function GET(request: Request) { const signIn = (await cookies()).get("fune_signin")?.value ?? ""; const user = await completeSignIn(request.url, signIn); // find or create the account by (user.provider, user.subject) here const headers = new Headers({ location: user.returnTo ?? "/" }); headers.append("set-cookie", sessionCookie(createSession(user))); headers.append("set-cookie", "fune_signin=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0"); return new Response(null, { status: 302, headers }); } // anywhere: who is this? const me = readSession((await cookies()).get("fune_session")?.value ?? null); ``` In Express it is the same three calls: `res.cookie`/`res.append('Set-Cookie', ...)` for the headers, `req.protocol + '://' + req.get('host') + req.originalUrl` for the callback URL. Signing out is `sessionCookie("", 0)`. ## What it checks, and what it leaves to you - The sign-in cookie holds the state, the PKCE verifier, the nonce, the callback URL and `returnTo`, signed and valid for ten minutes. The callback must carry the same state, and must come back to the provider that began it. `returnTo` must be a path on your site, so it cannot become an open redirect. - A session is the user's provider, subject, email and name, signed, with an expiry. It is readable by whoever holds it, so put nothing secret in it. It cannot be revoked one at a time: rotating `SESSION_SECRET` signs everyone out. If you need per-session revocation, store a session id in your database and keep it in the session's subject lookup. - Key accounts on `provider` and `subject`, never on the email: emails change, and an unverified one (`emailVerified: false`) proves nothing. - It does not fetch userinfo, refresh tokens, or call the provider's APIs on the user's behalf, and it does not do CSRF protection for your own forms (SameSite=Lax on the session cookie helps; it is not a token). ## Where the contract tests come from The exchanges follow the providers' documentation: Google's published discovery document and token response, Keycloak's endpoint layout, GitHub's OAuth app flow (including its `bad_verification_code` error body) and its `/user` and `/user/emails` shapes. Every client id and secret in them is a fake. The PKCE challenges and the cookie signatures in the expected results were computed independently with Node's crypto module. Before going live, sign in once against the real provider from a staging deployment.