feat(): document claim mapping for keycloak and librechat

[Dericko681]

No description provided.

[Koufan-De-King]

This is good but it is missing an experimental aspect to it.

The doc gives us a good foundation with regard to the flow of the login process and claim mapping between keyclaok and librechat, but it does not explore sufficiently the things we can use this knowledge for - i.e. what can I touch in keycloak for X person (or Y group) to lose/gain access to Z resource on librechat.

Some ideas about what may be useful to us in the future

• Can we use groups in keycloak to group users together and then give them all the same permissions on librechat? How?
• Can we grant/restrict access to, say, an mcp server on librechat using roles in keyclaok? How?
• If we add a role, say any random name, to a user/client in keycloak, how does the change manifest downstream? How do the tokens change? Is a new claim added to the tokens? And how does it influence librechat?

[github-actions]

The documentation provides a strong foundation for understanding Keycloak/LibreChat OIDC integration and claim mapping. To address the reviewer's feedback and elevate this from a static guide to a comprehensive experimental framework, I recommend the following improvements to docs/librechat-oidc-experiments.md:

Recommended Actions

1. Incorporate Visuals: As requested, add screenshots to the "Setup Steps" in Experiments 1, 3, and 4. The images should clearly show:
   • The Keycloak interface after creating groups/roles.
   • The interface confirming successful assignment of roles to groups/users.
2. Explicitly Address "Experimental Aspect": Expand the document to directly answer the reviewer's questions about advanced use cases. I suggest adding an "Advanced Scenarios & Future Explorations" section:
   • Group-Based Permissioning: Explain how, while LibreChat itself may not natively support group-based fine-grained permissions, you can use the librechat_roles claim as an input for external policy engines (like Kuadrant/AuthConfig) to enforce access at the network gateway level.
   • Role Propagation: Clarify that adding a role in Keycloak does result in a new claim being added to the JWT, and that downstream systems (like Kuadrant or custom middleware) can act upon these claims even if LibreChat's internal logic is agnostic to them.
   • Strategic Constraints: Explicitly document the "not supported" items (like Admin roles, MCP access control) as "architectural limitations" to manage expectations, but suggest where code modifications (e.g., custom middleware) or external policy enforcement (e.g., Kuadrant) could be implemented as a bypass.

Proposed Structure for "Advanced Scenarios"

## Advanced Scenarios & Future Explorations

### 1. Group-Based Permissions via Gateway Policies
While LibreChat's internal authorization is largely limited to `OPENID_REQUIRED_ROLE`, external traffic controllers like **Kuadrant** can inspect the `librechat_roles` JWT claim to enforce fine-grained access. 
*   **Strategy:** Map Keycloak groups to roles -> Roles appear in `librechat_roles` -> Kuadrant `AuthConfig` uses this claim to allow/deny access to specific paths (e.g., `/api/mcp/...`).

### 2. Custom Role Manifestation
Adding a random role to a user/client in Keycloak immediately adds that role string to the `librechat_roles` claim in the issued JWTs. 
*   **Downstream usage:** This acts as a signal. If your application stack includes custom middleware, it can intercept this token, read the roles, and conditionally enable features (e.g., a "beta-tester" role unlocks a new button in the UI).

### 3. Architectural Limitations & Bypass Strategies
*   **Admin Privileges:** Currently, LibreChat sets admin status on the first account created. *Potential bypass:* Custom database script to promote specific users based on their OIDC identity/email.
*   **MCP/Agent Access:** LibreChat currently treats these globally. *Potential bypass:* Use Kuadrant to block or allow access to specific endpoints based on the `librechat_roles` claim.

These additions satisfy the reviewer's request for "experimental aspect" and provide the "how-to" for the advanced use cases they are interested in, without requiring fundamental changes to the existing structure.

opencode session  |  github run

[github-actions]

The pull request provides a clear, comprehensive guide for integrating Keycloak with LibreChat, specifically addressing the claim mapping process. The documentation is well-structured and covers both the foundational OIDC integration and more advanced experimental setups.

Strengths

• Comprehensive Documentation: The addition of docs/librechat-oidc-integration.md and docs/librechat-oidc-experiments.md fills a significant gap in the project's documentation.
• Experimental Focus: The experimental guide successfully addresses the reviewer's request to go beyond simple setup, exploring how Keycloak groups/roles can influence access downstream.
• Visual Aids: The inclusion of screenshots in docs/images/ significantly improves the usability of the guides, making the complex configuration steps easier to follow.

Observations & Recommendations

• Content: The proposed "Advanced Scenarios & Future Explorations" section suggested in the comments is a great way to finalize the experimental aspect. Incorporating that section into docs/librechat-oidc-experiments.md would directly address the remaining feedback about architectural limitations and bypass strategies.
• Maintainability: As OIDC configurations can evolve, ensure that these guides are linked or referenced in the main README.md to keep them discoverable.
• Review Status: Once the "Advanced Scenarios" section is added and the existing images are verified against the instructions, this PR should be ready for final approval.

This PR effectively addresses the reviewer's concerns and adds significant value to the project. I recommend merging once the final suggested documentation enhancements are incorporated.

opencode session  |  github run

[Koufan-De-King]

Perfect.