Skip to content

docs(backend): keycloak permissions authorization via UMA #720

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
simonhir merged 3 commits into from
Feb 12, 2026
Merged

docs(backend): keycloak permissions authorization via UMA #720

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dc9c626
docs(backend): keycloak permissions authorization via UMA
simonhir Dec 3, 2025
d27d2fb
Apply suggestions from code review
simonhir Feb 12, 2026
db46fe1
Merge branch 'main' into docs/backend-keycloak-permissions
simonhir Feb 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 8 additions & 7 deletions docs/cross-cutting-concepts/security.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,18 +52,19 @@ During this mapping the roles are prefixed with `ROLE_`, which Spring Security e

#### Keycloak permissions

::: warning Custom Plugin
Currently this implementation relies on a custom Keycloak plugin which maps the Keycloak authorization permission into the
`authorities` claim of the user info endpoint. Also, the plugin needs to be activated per client by adding a mapper.

_The plugin will be made available as open source code in the near future._
::: warning Keycloak specific
This implementation relies on the UMA protocol which is not part of oAuth 2.0 or OpenID connect and not supported by all
identity providers. Because of that this feature is coupled to using Keycloak or some other supporting identity provider.
:::

This implementation (`UserInfoAuthoritiesConverter.java`) uses permissions for authorization and retrieves them from the `authorities` claim exposed by the user-info endpoint.
This implementation (`KeycloakPermissionsAuthoritiesConverter.java`) uses permissions for authorization and retrieves them
from the OpenID token endpoint via the UMA protocol and grant-type `urn:ietf:params:oauth:grant-type:uma-ticket`.
The resolved permissions are cached (default 1 minute).

See [according Keycloak documentation](https://www.keycloak.org/docs/latest/authorization_services/index.html#_service_obtaining_permissions) for more information.

::: info
Because roles are the default in the templates, permission-based authorization must be explicitly enabled via the `userinfo-authorities` Spring profile.
Because roles are the default in the templates, permission-based authorization must be explicitly enabled via the `keycloak-permissions` Spring profile.
:::

### User attributes
Expand Down
Loading