docs(backend): keycloak permissions authorization via UMA

[simonhir]

Pull Request

Changes

• document: keycloak permissions via UMA instead of custom plugin

Reference

Issue: https://git.muenchen.de/ccse/refarch-security/-/issues/8

• feat(backend): keycloak permissions authorities refarch-templates#1158

Checklist

Note: If some checklist items are not relevant for your PR, just remove them.

General

• Added meaningful PR title and list of changes in the description
• Created / Updated documentation (in English)

Summary by CodeRabbit

• Documentation
  • Updated Keycloak permissions configuration documentation with current implementation details
  • Permissions are now cached with a default 1-minute TTL
  • Updated the enabling profile identifier for Keycloak permissions authentication
  • Added reference to relevant Keycloak documentation

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Documentation updated to replace Keycloak's custom plugin permissions approach with a Keycloak-specific UMA-based method. Permissions now retrieved from the OpenID token endpoint via UMA grant-type instead of authorities claim. Class reference updated from UserInfoAuthoritiesConverter to KeycloakPermissionsAuthoritiesConverter, enabling profile changed, and caching behavior noted.

Changes

Cohort / File(s)

Summary

Keycloak Permissions Documentation docs/cross-cutting-concepts/security.md

Updated Keycloak permissions subsection from custom plugin narrative to UMA-based approach; changed permission retrieval source from user info endpoint to OpenID token endpoint; renamed class reference from UserInfoAuthoritiesConverter to KeycloakPermissionsAuthoritiesConverter; updated enabling profile from userinfo-authorities to keycloak-permissions; added permission caching details and documentation link

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

• Verify that the class name change (UserInfoAuthoritiesConverter → KeycloakPermissionsAuthoritiesConverter) aligns with the actual codebase implementation
• Confirm the UMA grant-type and endpoint details are technically accurate
• Check that the profile name update (userinfo-authorities → keycloak-permissions) matches the actual Spring profile configuration

Poem

🐰 From plugins custom-made to standards true,
UMA brings a better way for you!
The tokens dance through OpenID's gate,
While permissions cache in moments eight.
No more mappers per client to maintain,
Just Keycloak's way—simple and plain! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: documenting Keycloak permissions authorization via UMA instead of a custom plugin approach.
Description check	✅ Passed	The description includes the required Changes section, References section with issue links, and a completed Checklist. However, several optional sections from the template are removed without justification, and some non-critical checklist items are omitted.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/backend-keycloak-permissions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6ba6bb8 and dc9c626.

📒 Files selected for processing (1)

• docs/cross-cutting-concepts/security.md (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: build-maven

🔇 Additional comments (2)

docs/cross-cutting-concepts/security.md (2)

55-58: Clear and appropriate warning about UMA protocol limitation.

The warning accurately conveys that UMA is Keycloak-specific and not universally supported, helping users make informed decisions about this approach.

---

66-68: Remove or correct the reference to keycloak-permissions profile—it does not exist in the codebase.

The Spring profile keycloak-permissions mentioned on line 67 is not defined anywhere in the Spring configuration or code. No profile-based conditional logic exists to enable permission-based authorization, and the current SecurityConfiguration only implements role-based authentication via oauth2ResourceServer without any mechanism to switch authorization models. Either remove this reference or document the actual profile name if such a feature is planned.

Likely an incorrect or invalid review comment.