Skip to content

Stop teaching a group naming convention that will not match - #129

Merged
ChrisonSimtian merged 1 commit into
developfrom
docs/oidc-group-names
Aug 23, 2026
Merged

Stop teaching a group naming convention that will not match#129
ChrisonSimtian merged 1 commit into
developfrom
docs/oidc-group-names

Conversation

@ChrisonSimtian

Copy link
Copy Markdown
Contributor

A teammate session working on the Homelab repo flagged that its eight access groups were renamed to lowercase-hyphenated forms (Homelab Adminshomelab-admins), because a group name travels inside the groups claim and consumers re-split it with their own rules — Pulse splits on whitespace and commas, so Homelab Admins arrived as two tokens and matched nothing, failing closed with no message.

Krautwatch's blueprint entry is unaffected (it references blueprint entry ids via !KeyOf, which did not change), but the documentation here was wrong twice over:

  1. It put one homelab's specific group names into generic self-hosting docs.
  2. Those names no longer exist, so anyone copying them would get a deployment that authenticates fine and then admits nobody — the worst shape of failure, since the sign-in succeeds and the refusal looks like a permissions bug.

Now neutral examples, plus the thing that actually matters: the names must be exactly what your provider emits in the claim. Also documented that Krautwatch splits the list on commas only — so a name with a space works here — while noting that other consumers of the same claim split on whitespace, which is why hyphenated names travel better. That is a nudge, not a rule we enforce: forcing our parser to split on whitespace would break legitimate names like Domain Admins for everyone else.

No behaviour change; ./build.sh Test green.

The OIDC examples used "Homelab Admins,Media Admins" — a homelab's own group
names in generic documentation, and as of that homelab's rename they no longer
exist. Copying them would have produced a config that authenticates and then
admits nobody, which fails closed and says nothing.

Neutral examples now, plus what actually matters: the names must be whatever the
provider puts in the claim. Krautwatch splits on commas only, so spaces are fine
here — but other consumers of the same claim split on whitespace, which is why
hyphenated names travel better.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@ChrisonSimtian ChrisonSimtian added the documentation Improvements or additions to documentation label Aug 23, 2026
@ChrisonSimtian
ChrisonSimtian merged commit 4a1df5c into develop Aug 23, 2026
1 check passed
@ChrisonSimtian
ChrisonSimtian deleted the docs/oidc-group-names branch August 23, 2026 07:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant