feat: automatic Kimai onboarding for OIDC logins

[glazperle]

Adds optional automatic Kimai onboarding on top of the OIDC login backend from #14, plus the Kimai-side plugin it needs.

Why

The OIDC backend federates the login, but the mapping to a Kimai account is still a hand-maintained oidc_identity entry in users.json — and each entry needs an API token an administrator first clicked together in Kimai's web UI. For a new colleague that is two manual steps before they can use the connector at all.

With --auto-provision, an identity that matches no configured user is resolved against Kimai's own user list and Kimai mints that user's personal API token on the spot. After that, signing in with the identity provider is the only step a user ever performs.

Design

Off by default and strictly additive. Every failure mode — no match, ambiguous match, plugin missing, admin token without permission, Kimai unreachable — answers with the same generic "not authorized" page the OIDC callback already returned, with the reason server-side in the log only. Enabling it cannot change behaviour for a deployment that works today.

One hook point. The whole wiring in oauth.py is a two-line fallback in the match is None branch, because provision() returns the same (slug, UserConfig) shape as get_user_by_oidc_identity(). Everything downstream — _issue_auth_code, /token, subject, _ensure_session — is untouched, and a runtime slug is live on the next request because _ensure_session() already reads users_config.users[slug] per request.

Matching refuses to guess. Rules run strongest-first and stop at the first that matches; a rule hitting more than one user aborts with "ambiguous" rather than falling through to a weaker one, because a wrong match hands one employee another employee's token. The minted token is verified against /api/users/me and discarded if it resolves elsewhere — but that guards a wrong token, not a wrong match, which is why --provision-match gates how far matching goes and the two name-based heuristics need fuzzy.

Persistence follows the OAuth client store. In-memory by default (access and refresh tokens are too, so a restart already means a silent SSO redirect); opt-in --provision-store FILE for deployments that would rather not churn Kimai tokens on every deploy. That file holds tokens in plaintext, so it is written 0600. Hand-written users.json always wins over a stored entry.

The Kimai plugin

kimai-plugin/ApiTokenBundle supplies the endpoint Kimai lacks: core Kimai can only delete access tokens through the API (DELETE /users/api-token/{id}); creating one is a web-form action in ProfileController::createAccessToken. The alternative would have been driving an admin web session through that HTML form — CSRF token, throttling, 2FA and all.

The bundle reuses Kimai's own api-token voter, so it grants nothing the Kimai UI would not: the caller needs api-token_other_profile, which only ROLE_SUPER_ADMIN holds by default. Requires Kimai 2.65+. It is part of neither the wheel nor the Docker image.

It has no automated tests, and this repository's CI cannot give it any — there is no PHP toolchain or Kimai checkout here. The Python side is covered; the PHP side is verified by the curl sequence in its README. Its assumptions were cross-checked against Kimai 2.65.0 (AccessToken entity, AccessTokenRepository, the api-token voter, and byte-identical token generation).

Incidental fixes

UsersConfig.load(allow_empty=True) and a softened initialize_users() check. Without them a provisioning-only deployment — the actual selling point — could not boot: both loaders and the session init insisted on at least one user existing before anybody had signed in.

Notes for review

• The security-critical question is the matching. tests/test_provisioning.py has one test per rule plus the ambiguity cases; the last commit closes a collision found in review, where a single-given-name address (max@corp.example) matched a colleague whose alias was Max or whose address was max@ on another mail domain — one candidate each, so the ambiguity guard could not catch it.
• The fuzzy tier remains a documented heuristic: it will match a namesake who has no account of their own. It is opt-in for that reason.
• A provisioned slug is a credential on the deprecated /mcp/{slug} routes. Slugs are generated with the strength users.example.json recommends, and the server warns at startup when auto-provisioning and legacy slugs are both active.
• 382 tests pass, ruff clean.

🤖 Generated with Claude Code