docs(access-control): document required Keycloak protocol mappers for public clients
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 1/5
- 预计耗时
- 1 小时以内
- 新手友好度
- 88/100
- Issue 类型
- 文档
- 描述清晰度
- 描述清楚
- 活跃度
- 冷清
调研方向
打开 docs/kubernetes/access-control.mdx，找到 Keycloak 部分和“Provider-specific rolesClaim paths”表格。在表格后添加提议的 Note，其中包括 Subject、Audience 和 User Realm Role mapper 的指导，以及对 OpenShift 指南的交叉引用。完成标准是 Note 能正确渲染，并清楚解释列出的 token 错误。
由索引模型根据 Issue 内容生成。
描述
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
- 主要语言
- Rust
- 星标
- 13.2k
- 派生
- 1.6k
- 平均合并
- 1 天 21 小时
- 30 天内合并 PR
- 346
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
NVIDIA/OpenShell 的其他 Issue
-
area:cli os:linux os:macos state:validated
难度 2/5 1-3 小时 新手友好度 88/100
NVIDIA/OpenShell#4042 · 2 条评论 ·
维护者通常 1 天内回复
-
state:triage-needed
难度 2/5 1-3 小时 新手友好度 72/100
NVIDIA/OpenShell#3995 · 2 条评论 ·
维护者通常 1 天内回复
-
state:triage-needed
难度 2/5 1-3 小时 新手友好度 72/100
维护者通常 1 天内回复
-
state:triage-needed
难度 1/5 1-3 小时 新手友好度 88/100
维护者通常 1 天内回复
-
area:docs
难度 1/5 1 小时以内 新手友好度 88/100
维护者通常 1 天内回复
相似的 Issue
-
tech-debt
难度 2/5 1-3 小时 新手友好度 74/100
维护者通常 1 天内回复
-
documentation
难度 1/5 1 小时以内 新手友好度 85/100
维护者通常 1 天内回复
-
discover: `sudo RTK_DISABLED=$VAR …` is not detected as a bypass when `sudo` is a transparent prefix未关闭area:cli bug good first issue priority:medium
难度 2/5 1-3 小时 新手友好度 88/100
维护者通常 1 天内回复
-
skill:code-review
难度 1/5 1-3 小时 新手友好度 88/100
维护者通常 1 天内回复
-
component:sight
难度 2/5 1-3 小时 新手友好度 84/100
agentic-os-org/ANOLISA#4115 · 1 条评论 ·
维护者通常 1 天内回复