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

[akram]

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