# 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.