docs(access-control): document required Keycloak protocol mappers for public clients
Nobody has claimed this yet.
- 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
-
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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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