Search code examples
keycloakkeycloak-services

Keycloak automatically creates realm client in master realm

I've read many tutorials on setting up a realm in Keycloak but it's nowhere mentioned that Keycloak is creating a client called <your-realm-name>-realm in master realm with set of roles:

Creating a realm called test

A client created in master realm

Why is it needed?

Is the custom realm a form of a client for a Keycloak itself so it needs to create a kind of "virtual" client to handle that relation?

This automatically created client has a set of roles which look to me like a Keycloak internal roles:

enter image description here

Where can I find them in a documentation?

Solution

  • Is the custom realm a form of a client for a Keycloak itself so it needs to create a kind of "virtual" client to handle that relation?

    Kind of; from the Keycloak Documentation itself:

    The master realm is a special realm that allows admins to manage more than one realm on the system. You can also define fine-grained access to users in different realms to manage the server.

    The master realm in Keycloak is a special realm and treated differently than other realms. Users in the Keycloak master realm can be granted permission to manage zero or more realms that are deployed on the Keycloak server. When a realm is created, Keycloak automatically creates various roles that grant fine-grain permissions to access that new realm.

    Admin users within the master realm can be granted management privileges to one or more other realms in the system. Each realm in Keycloak is represented by a client in the master realm. The name of the client is [realm name]-realm. These clients each have client-level roles defined which define varying level of access to manage an individual realm.

    It is just an implementation detail; Notwithstanding, it makes it easier to conceptually think of the master realm as the top of the pyramid followed by its clients, in which are included the other realms as well. Furthermore, it also allows you to managed the realms from the point of view of the master realm, for instance:

    enter image description here

    Adding permissions in the form of roles to the other realms. Other approaches would likely be good as well, but the Keycloak developers opted for this one.