Add sign‑in in ten lines

The ten lines

With openid-client 6. Lines 2–3 find hApp Auth, 4–7 send the person to it, 8–10 turn the code into the person. callbackUrl is the URL hApp Auth sent the person back to, and the verifier lives in their session between the two requests.

1import * as oidc from "openid-client";
2const config = await oidc.discovery(new URL("https://happauth.com"),
3  "https://yoursite.example/oauth/client.json", undefined, oidc.None());
4const verifier = oidc.randomPKCECodeVerifier();
5const signInUrl = oidc.buildAuthorizationUrl(config, { scope: "openid profile",
6  redirect_uri: "https://yoursite.example/callback", code_challenge_method: "S256",
7  code_challenge: await oidc.calculatePKCECodeChallenge(verifier) });
8const tokens = await oidc.authorizationCodeGrant(config, callbackUrl,
9  { pkceCodeVerifier: verifier });
10const { sub } = tokens.claims()!;

1. Host your client metadata

   Your client id is the HTTPS URL of a small JSON document on your own site (a client ID metadata document). hApp Auth fetches it when a person first signs in; there is nothing to register.

   1{
   2  "client_id": "https://yoursite.example/oauth/client.json",
   3  "client_name": "Your site",
   4  "client_uri": "https://yoursite.example",
   5  "redirect_uris": ["https://yoursite.example/callback"],
   6  "grant_types": ["authorization_code"],
   7  "response_types": ["code"],
   8  "token_endpoint_auth_method": "none"
   9}
   

   client_id must be the document’s own URL. Keep redirect URIs on the same origin; a redirect to localhost works for development and shows the person a warning line. The document is fetched with a 5 KB cap, no redirects and a short timeout, and cached by its HTTP headers.

2. Point the library at the issuer

   The issuer is https://happauth.com. Discovery, keys and endpoints come from its metadata:

   curl https://happauth.com/.well-known/openid-configuration
   

   The same flow, spread over the two routes a server needs:

   1import * as oidc from "openid-client";
   2
   3const SITE = "https://yoursite.example";
   4const config = await oidc.discovery(
   5  new URL("https://happauth.com"),   // the issuer
   6  `${SITE}/oauth/client.json`,        // your client id: a URL you host
   7  undefined,
   8  oidc.None(),                       // a public client: no secret
   9);
   10
   11// GET /sign-in — send the person to hApp Auth.
   12export async function signIn(session: Session) {
   13  const verifier = oidc.randomPKCECodeVerifier();
   14  session.set("pkce", verifier);     // keep it until the callback
   15  return Response.redirect(oidc.buildAuthorizationUrl(config, {
   16    redirect_uri: `${SITE}/callback`,
   17    scope: "openid profile email",
   18    code_challenge: await oidc.calculatePKCECodeChallenge(verifier),
   19    code_challenge_method: "S256",
   20  }));
   21}
   22
   23// GET /callback — the code becomes a verified person.
   24export async function callback(request: Request, session: Session) {
   25  const tokens = await oidc.authorizationCodeGrant(config, new URL(request.url), {
   26    pkceCodeVerifier: session.take("pkce"),
   27  });
   28  const claims = tokens.claims()!;   // sub, acr, amr, auth_time, and what you asked for
   29  session.set("user", claims.sub);
   30  return Response.redirect(SITE);
   31}
   

3. Place the button

   Link it to your /sign-in route. Use it as it is: recognition is what lets a person notice a fake.

   Sign in with hApp AuthSign in with hApp Auth

   Two variants (Emerald on light grounds; White on dark grounds and beside other providers), one height (44 px), English and Turkish. Coming: the 2 KB web component and the SVG set

What comes back

The ID token always carries sub and auth_time; acr and amr, which say how the person signed in, are coming. Ask for more with scopes; the person sees one line for each and can turn the optional ones off. Refusing an optional claim still signs them in, so read what you received, not what you asked for.

More scopes, the assurance values and the subject rules are on OpenID Connect for Holochain.

Rules the provider keeps

• Authorization code with PKCE (S256) for every client. No implicit grant, no password grant.
• Codes work once and expire in ten minutes (60 seconds is coming). Every authorization response carries iss; openid-client checks it for you.
• Access tokens are JWTs that live 5 minutes and name one audience. Refresh tokens rotate, and reusing an old one revokes the family.
• A third-party site gets a pairwise sub: the same person has a different id on every site.