# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. ## Data model Use the database in the `database` input. | Table | Columns | | --- | --- | | `oauth_identities` | `id`, `provider`, `provider_user_id`, `user_id`, `email_at_link`, `created_at`; unique on `provider` and `provider_user_id` | `users` needs an `email` and a way to tell whether it is confirmed. ## Addresses These were right when this was written. Confirm them in each provider's own documentation before building. | | Google | GitHub | | --- | --- | --- | | Authorize | `https://accounts.google.com/o/oauth2/v2/auth` | `https://github.com/login/oauth/authorize` | | Token | `https://oauth2.googleapis.com/token` | `https://github.com/login/oauth/access_token` | | Who it is | The `id_token` in the token answer | `https://api.github.com/user` and `/user/emails` | | Keys | `https://www.googleapis.com/oauth2/v3/certs` | none | | Issuer | `https://accounts.google.com` | none | Ask GitHub's token address for JSON with `Accept: application/json`. Take every address from configuration, so tests can point at a stand-in. ## What the redirect carries | Parameter | Value | | --- | --- | | `client_id` | The app's client id for the provider | | `redirect_uri` | This site's callback address, exactly as registered | | `response_type` | `code` | | `scope` | As in R1 | | `state` | 32 random bytes, base64url | | `code_challenge` | From the verifier, as below | | `code_challenge_method` | `S256` | | `nonce` | Google only: 32 random bytes, base64url | Send the PKCE parameters to both providers. One that ignores them loses nothing. ## PKCE test vector The challenge is the SHA-256 of the verifier's ASCII bytes, in base64url without padding. From RFC 7636: | | | | --- | --- | | Verifier | `dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk` | | Challenge | `E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM` | ## Rules - The cookie that holds the `state`, the verifier, the nonce and `next` is `HttpOnly`, `Secure`, `SameSite=Lax`, lasts 10 minutes, and is signed or encrypted with `SESSION_SECRET` so the browser cannot change it. - Cache Google's keys as their `Cache-Control` header allows. Fetch them again once when a token names a key that is not in the cache. - Use a maintained library to check the ID token's signature. Check the issuer, audience, expiry and nonce yourself as well, each with a test. - Rule 2 of R4 needs both sides proven: the provider vouches for the email, and the account's own email was confirmed. Linking on one side alone is how an account is taken over. - Adding an identity and starting the session is one transaction. The unique index is the last guard against two requests linking one identity twice. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | | `SESSION_SECRET` | Protects the cookie in R1. At least 32 random bytes. | | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | From the Google OAuth client. Not needed without Google. | | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | From the GitHub OAuth app. Not needed without GitHub. | ## Named here - The provider says the person declined with `error=access_denied`. - The token request also carries `grant_type=authorization_code` and the same `redirect_uri`. - The audience may be the client id as text, or a list that holds it. - A session lasts 30 days. Email addresses are compared trimmed and in lowercase. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.