Sign-in and passkeys
The server keeps no passwords. People sign in with a passkey the server checks itself, through an OpenID Connect provider, or either, as the owner chooses.
How sign-in works
tinyclient never sees a password and never picks a provider. It asks the server to start a sign-in, opens the address it gets back in the person’s own browser, and listens on the loopback address of that computer for a one-time code. The code lasts 60 seconds and works once. tinyclient trades it for a session.
Signing in proves who someone is to the server. It never grants decryption: the keys for end-to-end encrypted conversations belong to devices.
The owner’s choice
Passkeys are always on in the server. What the community accepts is the owner’s choice, made in tinyclient at Server Settings › Privacy. It takes effect at once, with no restart.
| Choice | What opens at sign-in | Who can get in |
|---|---|---|
| Through Pocket ID only (the default) | The provider’s sign-in page | Provider accounts. Passkeys already made stay stored and are not offered. |
| Passkeys, or through Pocket ID | The server’s passkey page, with a link to the provider | Both |
| Passkeys only | The server’s passkey page | Passkeys |
The choices carry the provider’s name, Pocket ID unless you set another. A server with no provider configured is always passkeys only, whatever is stored.
Sessions already open carry on until they expire or the person signs out. A switch to one sign-in only is refused unless the owner has that sign-in themself, so the owner cannot lock themself out. If other members lack it, the app says how many and offers Switch anyway: they stay members and cannot sign in again until the owner gives them a passkey link.
Adding a provider to a passkey-only server. Once a provider is configured the stored choice applies at once, and it starts at Through Pocket ID only, which shuts out every member whose only sign-in is a passkey. Choose Passkeys, or through Pocket ID before you add one. The server logs a warning at start when the stored choice would leave members without a way in.
Passkeys
A passkey is a key pair made on a person’s device. The device keeps the private half; the server keeps the public half and a counter. Signing in is the device signing a fresh challenge. There is no password to steal or reuse.
The pages are served by the community’s own server, at TINYSERVER_PUBLIC_URL. They carry one fixed script that talks only to that server and load nothing from anywhere else. They are not part of tinyclient.io.
- Sign up needs an invite. The person types the name others will see, makes a passkey, and is shown 10 recovery codes before they continue. A failed attempt spends nothing, the invite included.
- Sign in asks for no username. The browser offers the passkeys it holds for the site.
- A lost passkey: a recovery code lets the person make a new passkey and sign in. The code is used up at that moment.
- Another device is one more passkey on the same account. In tinyclient, Server Settings › Sign-in › Add a passkey makes a link, good for an hour and for one use; opening it on the other device makes a passkey there.
- Managing them: the same page lists a person’s passkeys, removes one, and makes a new set of recovery codes. Each of those needs a sign-in within the last 10 minutes, so a stolen old session cannot plant a passkey of its own. The last passkey can be removed only while a recovery code is left.
- A passkey that looks copied, one whose counter did not go up, is refused and turned off until its owner removes it. Passkeys that sync keep the counter at zero and are not subject to this.
When everything is lost. If a person loses every passkey and every recovery code, the account cannot be signed in to again. The server holds nothing that proves who they are: no email, no phone number. The owner can invite them again as a new account; their old messages stay with the old one. Tell your members before they depend on it.
What the server stores for a passkey
For each passkey: its credential id, the public key and counter, whether the platform may sync it, a label, when it was made and when it was last used. For each account: the display name typed at sign-up, a random id, and the recovery codes as hashes.
Not stored for a passkey, in any table or log: an IP address, a user agent, an email address, a phone number, or a device model. A test fails if a column named for one of those is added.
The hostname is permanent
A passkey works only for the site it was made for. By default that is the host of TINYSERVER_PUBLIC_URL, such as chat.example.org. If the community later moves to another host, every passkey stops working, and everyone needs a recovery code or a new passkey link.
If you may ever move between subdomains, set TINYSERVER_PASSKEY_RP_ID to the domain above them, such as example.org, before anyone makes a passkey. The cost: any site under that domain can then ask the browser for these passkeys, so a taken-over subdomain becomes a place to phish them. The default, the exact host, is the safer choice.
Passkey links
A passkey link, called a claim link in the server’s documents, lets one existing member make a passkey for their account. The owner makes them at Server Settings › Privacy, where the page also shows who has a passkey and who does not.
- Each link works once, for that member only, and expires after 14 days unless you choose 1 to 90.
- A new link for a person replaces their old one.
- The app shows each link once. The server keeps only a hash.
- The token sits after the
#, which a browser never sends, so it is in no server or proxy log.
Send each person only their own link, by a way you trust. Anyone who holds an unused link can set up a passkey on that account, so treat one like a password reset.
Moving a community from Pocket ID to passkeys
A member’s account does not change in the move. They keep their id, name, roles, messages and device keys; the move adds a passkey to the same account. Pocket ID’s own passkeys cannot be carried over, because they belong to Pocket ID’s hostname, so everyone makes a new one.
- Back up the database and the uploads, and check the backup.
- Update the server. Sign-in does not change yet.
- Add your own passkey: Server Settings › Sign-in › Add a passkey.
- Choose Passkeys, or through Pocket ID. Then sign in with your passkey in every browser your members use, on a phone and on a computer, before you send anyone a link.
- Make and send the passkey links.
- Watch the counts on the same page, and send new links as needed.
- Choose Passkeys only.
- Check: sign in with a passkey, then make an invite and sign up a test account with it.
- Optional, from a shell: remove the Pocket ID identities of members who have a passkey, then stop Pocket ID with
docker compose -f compose.yml -f compose.passkey.yml up -d. The auth hostname is then no longer needed.
Until the last step, going back is one choice in the app. The full runbook has the exact commands, the shell alternatives, and how to go back after the last step. Rehearse it on a restored backup first.
Test it in your browsers. The passkey pages are tested against a software authenticator, not a real browser, and the sign-in code has had no independent security review. Try every browser your members use, on your own hostname, before you move anyone.
Other providers
Any OpenID Connect provider with discovery, the authorization code flow and a confidential client works: Authentik, Keycloak, Zitadel, Google and others. Register the redirect address ${TINYSERVER_PUBLIC_URL}/v1/auth/callback.
| Variable | Meaning |
|---|---|
TINYSERVER_OIDC_ISSUER | The issuer. Discovery is read from it, and it must match exactly. |
TINYSERVER_OIDC_CLIENT_ID | The client id |
TINYSERVER_OIDC_CLIENT_SECRET_FILE | The secret. Or TINYSERVER_OIDC_PRIVATE_KEY_FILE for private_key_jwt; not both. |
TINYSERVER_OIDC_SCOPES | openid profile email unless set |
TINYSERVER_OIDC_PROVIDER_NAME | Shown in tinyclient. The issuer’s host unless set. |
TINYSERVER_OIDC_INTERNAL_URL | Where the server reaches the provider, when not at the issuer |
TINYSERVER_OIDC_MEMBER_GROUPS | Comma list. Someone in one of these groups joins without an invite. Unset is invite only. |
TINYSERVER_OIDC_ADMIN_GROUPS | Comma list. A member in one of these gets the admin role when they sign in. Leaving the group does not take it away. No group makes an owner. |
TINYSERVER_OIDC_GROUPS_CLAIM | The token claim with the person’s groups. groups unless set. |
TINYSERVER_OIDC_SIGNUP | pocket-id lets an invite make the person’s account at Pocket ID. Unset or none for every other provider. |
TINYSERVER_OIDC_PROVIDERS | Several providers at once, such as pocket-id,google. The first is the default. Each then has its own variables, such as TINYSERVER_OIDC_GOOGLE_ISSUER. |
A person is the pair of issuer and subject, so the same person at two providers is two accounts. Email never links accounts. A provider that supports OpenID Connect Back-Channel Logout can end the sessions it started; register ${TINYSERVER_PUBLIC_URL}/v1/auth/backchannel-logout.
deploy/README.md has the Pocket ID setup, the rest of the variables, and how an invite makes a Pocket ID account.
Sessions
- A session lasts
TINYSERVER_SESSION_MAX_DAYS, 30 unless set, 1 to 365. Nothing extends it; tinyclient then signs in again. - The database stores only the SHA-256 of the session token, with no address, user agent or device name.
- Signing out in tinyclient ends that session. Sign out everywhere ends all of that person’s sessions.
- A kick or a ban ends every session the person has.
- A session token is not tied to a device or an address. A stolen one works until it is ended or expires.
Rate limits
Starting a sign-in and trading its code allow 5 tries a minute per address. The passkey routes allow 30 posts a minute per address; recovery codes and passkey links allow 8. The address is the connection’s, or the header your proxy sets when the proxy is trusted. It is kept as a keyed hash in memory for a minute and is not written anywhere. Behind your own proxy, set that header, or every member shares one allowance.
What an operator can do
Someone with access to the database can make a session for any account, read who is a member, and delete or ban anyone. Passkeys do not defend against the person who runs the server; nothing that signs people in to a server can. What they give is that nobody else learns a secret that signs them in as a member, and that a leaked database hands over no passwords. Server privacy and security has the rest.