The provider

The OAuth 2.1 and OpenID Connect server, in Flask. It owns every account, every session and every token on the platform, and every rule about who may do what. The console, the portal and the sign-in pages hold no rules of their own: they call this server and show what it answers.

Setup, deployment and the platform's concepts (accounts, organizations, apps, the catalogue) are in the repository README. Plugins are in docs/plugins.md.

What it serves

Grants: authorization code with PKCE, refresh token (rotated, with reuse detection), client credentials, and the device code. Tokens are JWTs signed with the newest key in IDP_SIGNING_KEYS_DIR; every key in the directory still verifies.

Sessions end everywhere they reached: a sign-out, a device signed out from the account area, or a deleted account sends an OpenID back-channel logout token to every app with a backchannel_logout_uri that took part in that session.

Layout

src/idp/
  app.py          create_app: settings, extensions, blueprints, plugins
  config.py       every setting, read from IDP_* variables and .env
  cli.py          the flask commands
  models/         SQLAlchemy models
  db/             the session and utcnow
  oauth/          Authlib server, grants, claims, JWT helpers
  security/       passwords, TOTP, CSRF, signing keys, encryption at rest
  services/       the rules: accounts, sessions, MFA, passkeys, platform, profile, ...
  web/            the blueprints: pages, api, developer, admin, oidc, openapi
  plugins/        the plugin interface and the catalogue sync
  templates/      the page shell
  static/idp/     the built sign-in pages (from frontend/, not edited here)
migrations/       Alembic revisions
tests/            pytest, against a real PostgreSQL database
platform.example.toml   the platform's apps, copied to platform.toml per deployment

The rule of thumb when changing something: a view in web/ parses the request and shapes the answer; the decision lives in services/. A rule that two endpoints share is one function in a service, never two copies in two views.

Commands

Run from idp/ as ../.venv/bin/flask --app idp.app:create_app <command>.

Migrations: ../.venv/bin/alembic upgrade head, with IDP_DATABASE_URL set. A new revision goes in migrations/versions/ and names its down_revision; there is one head.

Settings

All of them are in src/idp/config.py, each with a comment, and read from the environment with the IDP_ prefix or from idp/.env (see .env.example). The ones every deployment sets:

With an issuer that is not on this machine, the provider refuses to start when the issuer is not https, email test mode is on, cookies are not Secure, or IDP_RATE_LIMIT_STORAGE is not set. It then also sends Strict-Transport-Security.

Lifetimes (IDP_ACCESS_TOKEN_TTL, IDP_REFRESH_TOKEN_TTL, IDP_SESSION_TTL, ...) are in seconds. What prune keeps is in days: IDP_SESSION_RETENTION_DAYS (30) for ended sign-ins, IDP_AUDIT_RETENTION_DAYS (365) for the audit trail.

Checks

../.venv/bin/python -m pytest      # needs the idp_test database on localhost
../.venv/bin/ruff check src tests
../.venv/bin/mypy src

Every change to a rule comes with a test in tests/ that fails without it.