fix(health): name flagged groups and reasons in the mapper check #39

2026-10-16T16:37:57Z

KofTwentyTwo commented

2026-10-16 16:37:57 +00:00

(Migrated from github.com)

Why

kof22 prod (0.1.0-RC.7) shows authentik.mapper DEGRADED with only "Mapper drift detected" and findingCodes=group_attributes.warning. Nothing says which group or why.

The likely cause in kof22: the file-gateway-admins group grants file_gateway.connect, file_gateway.view and file_gateway.admin. qbit-file-gateway checks those names only in code. They are not in the instance's permission metadata, so they are not in the resolver catalog. The mapper reports them as "grants nothing" and does not grant them. That is a real gap, and this PR does not fix it; it is tracked separately. A group with no qqq.io/* attributes, such as kof22-admins on its static floor, was never flagged.

What

DriftFinding gets an optional reason: a short, safe summary for health outcomes. A 4-argument constructor keeps every existing call site.
The group-attribute findings set reasons:
- grants nothing: <permission>. The permission name must match [A-Za-z0-9_.*-]{1,120}; otherwise it shows as (unprintable name).
- malformed <attribute>. This gives the attribute name only, never the typed value.
- superuser group carries qqq.io/permissions.
The authentik.mapper outcome message is now Mapper drift: <group> (<reasons>); ..., cut to 500 characters. New details: flaggedGroups and summary, alongside the existing findingCodes.
Service-account activity subjects (people) stay private and appear only as service-account activity (see the identity drift report). A group check that cannot run appears as group attributes check could not run.
The "grants nothing" drift message notes that a name an app checks only in code is not in the catalog.

Tests

AuthentikHealthChecksTest.mapperStates:
- A group with no attributes is UP.
- Unknown, malformed and superuser findings produce the exact message and details.
- Typed values and person subjects never appear.
mapperOutcomeEdges covers a check that cannot run, control characters, unnamed groups, and the 500-character and 4 KiB bounds.
AuthentikDriftReportTest.malformedReasonKeepsOnlyTheAttribute.
./mvnw verify -DskipITs passes locally.

🤖 Generated with Claude Code

## Why kof22 prod (`0.1.0-RC.7`) shows `authentik.mapper` DEGRADED with only "Mapper drift detected" and `findingCodes=group_attributes.warning`. Nothing says which group or why. The likely cause in kof22: the `file-gateway-admins` group grants `file_gateway.connect`, `file_gateway.view` and `file_gateway.admin`. qbit-file-gateway checks those names only in code. They are not in the instance's permission metadata, so they are not in the resolver catalog. The mapper reports them as "grants nothing" and does not grant them. That is a real gap, and this PR does not fix it; it is tracked separately. A group with no `qqq.io/*` attributes, such as `kof22-admins` on its static floor, was never flagged. ## What - `DriftFinding` gets an optional `reason`: a short, safe summary for health outcomes. A 4-argument constructor keeps every existing call site. - The group-attribute findings set reasons: - `grants nothing: <permission>`. The permission name must match `[A-Za-z0-9_.*-]{1,120}`; otherwise it shows as `(unprintable name)`. - `malformed <attribute>`. This gives the attribute name only, never the typed value. - `superuser group carries qqq.io/permissions`. - The `authentik.mapper` outcome message is now `Mapper drift: <group> (<reasons>); ...`, cut to 500 characters. New details: `flaggedGroups` and `summary`, alongside the existing `findingCodes`. - Service-account activity subjects (people) stay private and appear only as `service-account activity (see the identity drift report)`. A group check that cannot run appears as `group attributes check could not run`. - The "grants nothing" drift message notes that a name an app checks only in code is not in the catalog. ## Tests - `AuthentikHealthChecksTest.mapperStates`: - A group with no attributes is UP. - Unknown, malformed and superuser findings produce the exact message and details. - Typed values and person subjects never appear. - `mapperOutcomeEdges` covers a check that cannot run, control characters, unnamed groups, and the 500-character and 4 KiB bounds. - `AuthentikDriftReportTest.malformedReasonKeepsOnlyTheAttribute`. - `./mvnw verify -DskipITs` passes locally. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

gitea-actions Bot referenced this issue from a commit

2026-11-05 11:43:17 +00:00

Merge develop into release/0.1 for 0.1.0-RC.8 (#37 broker probe, #38 maintenance service principal, #39 mapper drift message; QQQ RC.19)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: QRun-IO/qbit-authentik#39