NVIDIA / NVIDIA/OpenShell

docs(access-control): document required Keycloak protocol mappers for public clients

Aperta Adatta ai principianti
#2,101 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

state:triage-needed
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

  1. 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.

  2. 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

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. 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

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.