← All templates

Google, GitHub and Microsoft sign-in, account linking, session rotation.

Spec — Sign-in with OAuth and OIDC

Status: draft · Created: 2026-11-10

1. Context and goal

People sign in with their Google, GitHub or Microsoft account instead of a password, and keep one account in the product whichever provider they use.

2. Functional requirements (EARS)

  • FR-1: WHEN a person chooses a provider, THE SYSTEM SHALL start the authorization code flow with PKCE (S256) and a single-use state and nonce that expire after 10 minutes.
  • FR-2: IF the callback carries a state that is unknown, already used or expired, THEN THE SYSTEM SHALL answer 400 and create no session.
  • FR-3: WHEN the provider returns an ID token, THE SYSTEM SHALL verify its signature against the provider's JWKS and its issuer, audience, nonce and expiry, with at most 60 seconds of clock skew, before signing anyone in.
  • FR-4: THE SYSTEM SHALL identify an external account by the pair of issuer and sub, never by email alone.
  • FR-5: WHEN a verified identity matches no linked account and its email belongs to no account, THE SYSTEM SHALL create an account and link the identity to it.
  • FR-6: IF the provider's email matches an existing account not linked to that identity, THEN THE SYSTEM SHALL link it only after the person signs in to that account, and never on an email the provider marks unverified.
  • FR-7: WHEN a signed-in person links or unlinks a provider, THE SYSTEM SHALL record the change in the account history, and SHALL answer 409 to unlinking the last remaining sign-in method.
  • FR-8: WHEN sign-in succeeds, THE SYSTEM SHALL issue a new session id, invalidate any session id held before sign-in, and set the cookie HttpOnly, Secure and SameSite=Lax.
  • FR-9: WHEN a session is refreshed, THE SYSTEM SHALL rotate its refresh token, and IF a rotated token is presented again, THEN THE SYSTEM SHALL revoke every session of that sign-in and answer 401.
  • FR-10: WHILE a session has been idle for 30 minutes or 30 days have passed since sign-in, THE SYSTEM SHALL require a new sign-in.

3. Out of scope

  • SAML single sign-on for enterprises.
  • Password sign-in.
  • Syncing profile data from the provider beyond name and email.