# How signo works

signo is an OpenID Connect provider: the same kind of service as "Sign in with Google", run without Google. Your site sends people to signo, signo checks who they are, and sends them back with a signed statement of their email address.

## A sign-in, step by step

1. Someone presses "Sign in" on your site. Your auth library sends them to signo's `/auth` endpoint with your client ID, a PKCE challenge and the scopes it wants.
2. signo shows a sign-in page with your site's name. The person uses their passkey, or asks for an email link.
3. The first time a person signs in to your site, signo lists what your site will receive and the domain they will return to. They allow it or cancel.
4. signo sends them back to your callback URL with a one-time code. Your server exchanges the code for tokens, sending its client secret and the PKCE verifier.
5. The ID token is signed with signo's key (RS256, published at `/jwks`). It carries `sub`, `email`, `email_verified` and, if the person gave one, `name`.

## Accounts

- An account is created only when someone opens a sign-in link sent to their email. Every email signo sends to sites is therefore verified, and nobody can create an account in someone else's name.
- After that, people sign in with a passkey: their fingerprint, face or screen lock. A passkey only works on signo's own domain, so a lookalike site can't use it.
- Someone who has lost their passkeys asks for an email link, signs in, and adds a passkey on the new device.
- `sub` is a random ID for the account. Every site receives the same `sub` for the same person.

## What signo remembers

- A signo session lasts 14 days. While it lasts, people go through other sites' sign-ins without signing in again.
- Consent is remembered per person and site for up to a year, so the consent screen appears once.
- Signing out of signo ends the signo session and revokes the tokens of the sites used in it, in all of the person's browsers, but keeps consent. A site with its own session keeps it; a single-page app using signo.js signs the person out the next time it checks with signo.

## What sites receive

| Scope | Claims |
|---|---|
| `openid` | `sub` |
| `email` | `email`, and `email_verified`, which is always `true` |
| `profile` | `name`, if the person gave one |

[Scopes and claims](https://usesigno.co.uk/docs/scopes-and-claims.md) has the details, and [Security model](https://usesigno.co.uk/docs/security.md) lists everything signo stores.