Pass roles from keycloak to hedgedoc


I would like to pass roles from keycloak to hedgedoc yet cannot get the setup correct. I also sadly have to note that the documentation comes a little short here. Therefor I would like to ask for clarification here.

My version of HedgeDoc is: 1.7.2

What I expected to happen:

The roles are passed from keycloak to hedgedoc defining which capabilities the user has.

What actually happened:

The documentation does not state how to achieve this.

I already tried:

The setup works, a user can login using keycloak. Afterwards the user can create or edit notes. But passing specific roles from keycloak to hedgedoc is not very precisely described inside the documentation.
First, a better explanation of the variable CMD_OAUTH2_ROLES_CLAIM would be very welcome. I suppose it is the variable that is the same as the realm_access.roles default ones from keycloak. But I had no success to setting it to realm_access.roles or realm_access/roles. At the same time setting the variable CMD_OAUTH2_ACCESS_ROLE is also not clear. I tried roles/hedgedoc, just roles, realm_access/roles and realm_access/roles/hedgedoc. It either did not work or returned an error 500.
The section Configuration - HedgeDoc does not contain any description of the user roles. So for example which roles should a normal user and an admin be assigned to ?

Therefor, I would like to ask:

  1. How do the roles are passed from or set inside keycloak ?
  2. Which roles exist ?


First of all I wanna suggest to update your version of HedgeDoc because since 1.7.2 we had several releases with security fixes. See Releases for more information.

HedgeDoc doesn’t have admin users. All logged-in users have the same privileges.

Hello mrdrogdrog,

thanks for the clarification. I would still like to ask about the usage of the variables CMD_OAUTH2_ROLES_CLAIM and CMD_OAUTH2_ACCESS_ROLE.

To answer the question:

CMD_OAUTH2_ROLES_CLAIM should contain the path to the array containing the roles of the user in the user profile (yes, this is technically not ideal, but it is how it is).

CMD_OAUTH2_ACCESS_ROLE is the name of the role, that needs to be in the array mentioned above.

Relevant code section: