NVIDIA / NVIDIA/OpenShell

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

Open Beginner friendly
#2,101 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

state:triage-needed
Dominant language
Rust
Stars
8.7k
Forks
1.3k
Avg merge
2d 11h
Merged PRs (30d)
253

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Open docs/kubernetes/access-control.mdx and locate the Keycloak section and the “Provider-specific rolesClaim paths” table. Add the proposed Note after the table, including the Subject, Audience, and User Realm Role mapper guidance and the cross-reference to the OpenShift guide. Done means the note renders correctly and clearly explains the listed token errors.

Written by the indexing model from the issue text.

Assessment

Domain
authentication, documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
88/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.