Pocket ID on Cloudron

Pocket ID is a self-hosted OpenID Connect (OIDC) and OAuth 2.0 provider that signs users in with passkeys instead of passwords. Applications are pointed at it to authenticate their users, so there is nothing to type and no shared secret to lose - the credential is a key held on the user's own device.

Upstream version: 2.19.1 | Setup steps: POSTINSTALL.md

How accounts work

Pocket ID holds one pool of accounts for the whole instance. An application is a client - a client ID, a secret, a redirect URL, a logo - and has no users of its own inside Pocket ID.

• Administration -> Users lists every account, including the admin's. "Administrator" is a flag on an account, not a separate kind of account.
• One person using three applications has one account, not three. That is what makes single sign-on work.
• Deleting an application's client record removes the integration, never the accounts.

A new account can be created in three ways:

• Self-registration - Application Configuration -> User Creation -> Enable User Signups, set to Open. Anyone reaching /signup can register. This is instance-wide and cannot be set per application.
• Signup link - set to withToken, or call POST /api/signup-tokens with an API key and send the person to /signup?token=.... The token can carry userGroupIds.
• By an administrator - Administration -> Users -> Create user, then Login Code on the row for a one-time link.

How groups work

Groups decide which applications an account may use. Membership can be assigned automatically at creation time, from User Creation -> User Groups or from a signup token's userGroupIds. A client is then restricted with OIDC Clients -> <client> -> Allowed User Groups, and accounts outside those groups cannot sign in to it.

Membership is never inferred from the application a person signs in from.

What users see

When an application sends someone here, they get its logo paired with Pocket ID's, and a prompt naming both. They never see the admin interface.

They will see this hostname in the address bar, and that is unavoidable: it is where the credential is held. Only one hostname can serve an instance, so two brands cannot have separate addresses on one install. Separate brands with separate user bases need separate installations.

The name used in that prompt is Application Configuration -> General -> Application Name, a single value for the whole instance. There is no per-application equivalent - the client's own name appears alongside it, not instead of it.

Known limitations

• No sign-up from the sign-in flow. Someone new who arrives from an application is shown sign-in only, with no way to register. They must be sent to /signup directly - from the application's own login page, or by a link. This is upstream issue #1583, still open.
• Self-registration does not return to the application. After signing up, the person lands on Pocket ID rather than back where they started, and signs in again from there.
• No per-application branding or isolation. One account pool, one hostname, one application name. Groups gate access; they do not separate populations.

Data

The database, uploads and the encryption key live in the app's persistent volume and are included in backups. The key decrypts data in the database, so never restore one without the other.

Settings made in the admin interface are stored in the database, not in /app/data/env.sh.

---

Packaged by @timconsidine https://communityapps.appx.uk (full portfolio: https://myca.appx.uk)