docs(access-control): document required Keycloak protocol mappers for public clients
Nessuno ha ancora preso questa issue.
- Lingua principale
- Rust
- Stelle
- 8.7k
- Fork
- 1.3k
- Merge medio
- 2g 11h
- PR unite (30g)
- 253
Descrizione
Problem Statement
The access control docs (docs/kubernetes/access-control.mdx) document OIDC configuration with Keycloak including the rolesClaim paths table. However, it does not mention that Keycloak public clients do not include sub, aud, or realm_access.roles in access tokens by default.
Users following the guide with a fresh Keycloak setup hit confusing errors:
missing field 'sub'— no Subject mapper- Token rejected — no Audience mapper with
included.client.audience role 'openshell-user' required— no User Realm Role mapper in the access token
These errors give no indication that the fix is adding Keycloak protocol mappers, not changing OpenShell configuration.
Proposed Design
Add a <Note> callout in the Keycloak section of docs/kubernetes/access-control.mdx, near the rolesClaim paths table:
<Note>
Keycloak public clients do not include `sub`, `aud`, or realm roles in access tokens by default.
Add protocol mappers for Subject (sub), Audience (`openshell-cli`), and User Realm Role
(`realm_access.roles`) to the client. For step-by-step instructions, refer to
[OIDC with Keycloak on OpenShift](/kubernetes/openshift/oidc-keycloak#add-required-protocol-mappers).
</Note>
Changes required
docs/kubernetes/access-control.mdx— add the<Note>after the "Provider-specific rolesClaim paths" table
Alternatives Considered
-
Document the full mapper setup inline: Would add ~40 lines of Keycloak-specific content to a generic OIDC page. The OpenShift guide already has the full instructions — a cross-reference is cleaner.
-
Add a dedicated Keycloak page under
/kubernetes/: Overkill for a note about protocol mappers. The OpenShift guide covers the full Keycloak setup end-to-end.
- I've reviewed existing issues and the architecture docs
- This is a design proposal, not a "please build this" request
Guida per i contributori
Apri la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Direzione di ricerca
Apri docs/kubernetes/access-control.mdx e individua la sezione Keycloak e la tabella “Provider-specific rolesClaim paths”. Aggiungi dopo la tabella la Note proposta, includendo le indicazioni sui mapper Subject, Audience e User Realm Role e il riferimento incrociato alla guida OpenShift. Il lavoro è completato quando la Note viene renderizzata correttamente e spiega chiaramente gli errori del token elencati.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Ambito
- authentication, documentation
- Tipo di issue
- Documentazione
- Difficoltà
- 1/5
- Tempo stimato
- Meno di un'ora
- Stato di attività
- Tranquilla
- Chiarezza
- Specificata chiaramente
- Idoneità per principianti
- 88/100