Skip to content

Authentication and authorization

How the token is validated

Identity comes from Keycloak. The middlewares/keycloak_auth.py middleware validates the JWT with PyJWKClient and algorithms=['RS256'] — that is, it fetches the realm's public key and verifies the signature. The server issues no token of its own; it only checks what Keycloak signed.

Three dependencies come out of that, and the names matter because the test suite overrides them one by one:

get_current_user
Requires a valid token. Fails with 401 if there is none.
get_current_user_optional
Resolves the user if a token is present; returns None instead of failing.
require_admin
Requires a valid token and the admin role.

The roles

There are two, and the difference between them is narrow and precise:

admin
Can do everything: create and delete applications, create and delete parameters, change any field of any parameter, and change runtime configuration.
user
Can change only the value field of parameters flagged user_editable=True. Anything else is 403.

What enforces this is AppService._validate_permission, which diffs the restricted metadata fields. The question it answers is not "did the user touch the value?" but "did the user touch anything beyond the value?".

READ_AUTH_MODE

Out of the box, reading a parameter is anonymous. That is not an oversight: it is the historical behaviour, and the server does not negotiate client versions — tightening the control overnight would take down every fleet member that does not yet send a token.

The mode is resolved by RuntimeConfigService, which gives precedence to the value stored in the database (changeable by an admin without a redeploy) and falls back to .env when there is no override.

Mode What it does
off Historical behaviour. Anonymous reads allowed, with no resolution cost
warn Still allows them, but counts and logs every read without a token
enforce Requires a token. Without one, 401

The promotion criterion

warn exists to produce a measurement, not to warn a person. It feeds the anonymous-read metric.

Only promote to enforce with the metric at zero

While anonymous_reads_total is not zero in the environment, there is a consumer without a token — and turning enforce on will take it down.

An invalid token does not count as an anonymous read

A subtlety that looks like a detail and is not. Under warn, a request arriving with an Authorization header that does not resolve — expired token, wrong audience — is recorded as an authentication failure, not as an anonymous read.

If the two were counted together, a fleet with a momentarily expired token would keep the anonymous counter above zero forever, and the gate could never be promoted. The very signal that decides promotion would be corrupted by noise.

USER_EDITABLE_ENFORCEMENT

The same two-stage switch pattern, applied to write authorization.

legacy (default)
The diff is computed against the whole payload, with schema defaults filled in. Consequence: a plain user gets 403 even when editing a user_editable parameter, because the defaults enter the diff as if they were deliberate changes.
explicit
The diff considers only the fields the client actually sent, and preserves already stored metadata. This is the behaviour you want.

Promotion depends on adoption of client 0.5.0 or later, which started omitting user_editable from the payload when the caller does not supply it. Version 0.4.2 sends user_editable=False explicitly — under explicit, that becomes an attempt to change metadata and goes back to 403.

Authentication routes

Route Body Returns
POST /auth/token username and password as form fields The Keycloak token
POST /auth/refresh refresh_token as a form field A refreshed token
GET /auth/userinfo — (token in the header) Data about the authenticated user

The first two use application/x-www-form-urlencoded, not JSON.

What is frozen in the OpenAPI document

tests/test_openapi_contrato.py freezes securitySchemes and the per-route security block. It is what turns "the published schema did not change" from an argument into a check. Do not delete that test when touching authentication dependencies — it is the only automated barrier that exists in this area.

A secret that reaches the history

Deleting the file does not delete the commit

A Keycloak client_secret, a database password or an encrypted envelope that lands in a commit stays reachable by anyone holding the repository, even after the file disappears from the working tree. git log keeps the content, not the final state.

What ends the exposure is rotating the secret at its source — in Keycloak, in the database, wherever it is issued. Rewriting history does not replace that: in an already distributed repository, filter-repo invalidates every clone and recovers nothing that has already been read.

That is why the pipeline's secret scan runs over the whole history, not over the commit diff: what is already in has to be found where it is.