Zen IdP Zen IdP Zen IdP

Documentation

Zen IdP is a declarative OpenID Connect identity provider. You describe your users, your applications, and your security policy in YAML, you protect one root secret, and a single binary does the rest: TOTP sign-in, OIDC for your applications, and a small administration interface.

These pages are written for the person who runs Zen IdP, not the person who develops it. Every page explains what something does, why it works the way it does, and what you need to type.

How to read this documentation

The pages follow the natural order of a deployment. If you are new, read them top to bottom:

  1. Get Started takes you from nothing to your first working login.
  2. Installation covers Docker images and building from source.
  3. Configuration documents the complete YAML model, field by field.
  4. Users explains how identities are declared and managed.
  5. Clients explains how applications are registered and connected.
  6. Authentication explains sign-in, enrollment, and recovery.
  7. Administration covers the admin interface and the audit log.
  8. Security explains the trust model and where every secret lives.
  9. Operations covers running, upgrading, rotating, and recovering.

If you just want to see it work, start with Get Started and come back to the rest when you need it.

The three moving parts

Everything in Zen IdP reduces to three inputs, and it helps to keep them separate in your head from the beginning:

  • YAML configuration holds every identity, client, and policy decision. It is the source of truth. If a user is in the YAML, the user exists. You change identity data the same way you change any other code: edit, review, deploy.
  • The root secret (ZEN_IDP_SECRET) is one high-entropy value you keep in your secret manager. Zen IdP derives its signing key and every user's TOTP credential from it, deterministically, on every start. Nothing sensitive is stored to be stolen.
  • The state database is a single SQLite file that holds sessions, one-use tokens, rate-limit counters, locks, and audit records. It is disposable operational state, not identity data. Lose it and nobody's identity changes, everyone just signs in again.

The rest of this documentation is what those three statements mean in practice.

Where to go next