Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Cerrado Apto para principiantes
#2,101 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
1/5
Tiempo estimado
Menos de una hora
Aptitud para principiantes
88/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Tranquilo
Área
authentication, documentation

Línea de trabajo

Abre docs/kubernetes/access-control.mdx y localiza la sección de Keycloak y la tabla “Provider-specific rolesClaim paths”. Añade después de la tabla la Note propuesta, incluyendo las indicaciones sobre los mapeadores Subject, Audience y User Realm Role, así como la referencia cruzada a la guía de OpenShift. La tarea estará terminada cuando la Note se renderice correctamente y explique claramente los errores de token indicados.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

state:triage-needed

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
Lenguaje dominante
Rust
Estrellas
8.7k
Forks
1.3k
Merge medio
2 d 6 h
PR fusionados (30 d)
301

Guía de contribución

Abrir la guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de NVIDIA/OpenShell

Todos los issues de NVIDIA/OpenShell

Issues similares

Más issues de Rust

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.