Namespaced Roles #318

dgozalo · 2021-10-01T12:28:33Z

Creating a separate PR as this proposal is too large for having the whole text in Github discussions as defined in https://github.com/keycloak/keycloak/pull/8503/files#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055R48

Coming from: keycloak/keycloak#8516

design/namespaced-roles.md

stianst · 2021-10-04T09:32:21Z

design/namespaced-roles.md

+
+If the role name is another reference to a free form role, starting with `frole_v1:/`, this role will also be represented in a hierarchical way, making it possible for protocol mappers to show them as such in tokens.
+
+## Use Cases


Would be good to explicitly mention how role namespaces can clean-up the roles used "internally" by Keycloak's admin APIs. Getting rid of the strange clients, and having a separate/dedicated namespace for the roles so they don't conflict with "custom roles". I had something like the following in mind:

kc/admin/{realm-name}/{role-name}

design/namespaced-roles.md

stianst · 2021-10-04T09:35:31Z

design/namespaced-roles.md

+
+- `Group:devops` has the `role_v1:/realm1/tenant1//devops/devops_role` role.
+
+#### Representation in the tokens


Would like to see some alternatives on how roles can be represented in a token. For example options to flatten them if that makes sense. For example a client may not understand the concept of role namespaces, but would only want the roles for a specific namespace flattened.

Also, would be good to touch on how the roles can be represented in the current way they are being done in tokens with regards to realm and client roles.

…understand and add more use cases

stianst · 2021-10-08T07:15:35Z

design/namespaced-roles.md

+## Specification
+
+A Namespaced Role would contain a version, a path that start with a known particle to identify the nature of the role, and finally the role name.
+


Is particle a common term in this context?

stianst · 2021-10-08T07:16:34Z

design/namespaced-roles.md

+
+User defined roles, but still used to interact with Keycloak entities would start with `/ud`.
+
+Totally custom namespaces created with a specific business meaning for users wouldn't contain any of the previous particles.


Does this mean we've reserved /kc and /ud, but folks can define anything else if they want like /myorg/ or do you think there's always a "short" special start to the path?

stianst · 2021-10-08T07:17:25Z

design/namespaced-roles.md

+
+A few examples would be:
+
+`role_v1:/kc/groups/{group-name}/roleName`


Wouldn't this be role_v1:/ud/groups/{group-name}/roleName?

stianst · 2021-10-08T07:19:08Z

design/namespaced-roles.md

+**Tenant**: There's a proposal to make Keycloak multitenant aware, so even if it's not currently supported, for future compatibility, it should be considered when defining a unique identifier.
+ - Example: `role_v1:/kc/tenants/tenantA/roleName`.


I'm a little bit concerned with making the role namespace proposal mix-up with multi-tenant proposal. Also, a little bit unsure if "tenant" is an optional part in your head. Will need to discuss this with you to get some more clarification.

One thought is to leave the multi-tenant part a bit out of this design, perhaps just including it at the end as a separate section on how we could leverage role namespaces for multi-tenancy.

stianst · 2021-10-08T07:19:54Z

design/namespaced-roles.md

+**Client**: Roles can be defined and assigned for a certain client in Keycloak, so a unique identifier has to support this possibility.
+ - Example: `role_v1:/kc/clients/clientId/roleName`.
+
+Alternatively, if a namespace wants to be created for roles that can be shared among clients, it could be defined such as: `role_v1:/clients/*/roleName`.


Not sure I understand why there's a * here

Wonder if in this case you'd just use a free-form role namespace instead.

stianst · 2021-10-08T07:24:00Z

design/namespaced-roles.md

+
+- `role_v1:/groups/{group-name}/role-path/business-units/myBusinessUnit/const-centers/myCostCenter/roleName`
+
+But not convinced on the way to let Keycloak know that that's not a role name but rather a new namespace.


I was thinking that clients, groups, tenants, etc, would instead of having a fixed path to their namespace would allow configuring the namespace that is associated with them.

So, a client could have it's default namespace be /kc/clients/{client-id}, but could be configured to use a different namespace like /my-roles/my-group-of-apps

stianst · 2021-10-08T07:25:26Z

design/namespaced-roles.md

+
+## Management Roles
+
+These roles would only exist in the Master realm and would have a meaning for Keycloak, hence the `kc` fragment.


We have roles in the master realm that is used to control both the master realm and other realms when authenticating to the master console, but there are also the roles within each realm that can be used to grant users within a given realm access to only that realms admin endpoints.

stianst · 2021-10-08T07:26:31Z

design/namespaced-roles.md

+
+- `role_v1:/kc/admin/{role-name}` -> Roles to manage the Keycloak instance.
+
+When a new Realm is created in Keycloak, a new client is created in the Master realm to represent a namespace for this new Realm's admin roles. With the exception of the previous one, they will be used to deprecate the Clients that Keycloak creates to group certain management roles together.


There's also a client created within the new realm

stianst · 2021-10-08T07:28:19Z

design/namespaced-roles.md

+
+The rest of these roles would always be scoped to a specific realm that would replace the current client-per-realm.
+
+- `role_v1:/kc/realms/{realm-name}/clients/{client-name}/{role-name}` -> Roles to manage a certain client.


This is more fine-grained than what we have today. Right now, we have just manage-clients, not ability to manage an individual client. Wonder if this level is too fine-grained for roles, and rather we should look at fine-grained admin permission to manage individual clients (and also could look at integrating with external authz services in the future).

stianst · 2021-10-08T07:34:21Z

design/namespaced-roles.md

+
+or with a regexp, they could be namespaced to a specific subset of clients:
+
+- `role_v1:/ud/clients/{regexp-containing-wildcard}/{role-name}`


Wouldn't this be incredibly complex to resolve? Also, we'd want to use client-id to specify a client rather than client-name, and often these are just generated (and really should be), so is there a meaningful regex here?

stianst · 2021-10-08T07:35:46Z

design/namespaced-roles.md

+```
+Or even scope this custom namespace to a specific client or client sets:
+
+- `role_v1:/ud/clients/{client-name-or-regexp}/frole:/mycompany/resources/department-a-roles/developer`


Hmmm... I'm struggling to understand this one ;)

stianst · 2021-10-08T08:30:07Z

design/namespaced-roles.md

+- On resource deletion: The system should query all roles with the resource in its namespace and delete them.
+ - Example: Role `role_v1:/ud/groups/groupA/developer` exists. User deletes `groupA`. The system will query `getRoles("v1", "ud, "/groups/groupA")` and delete any returned entries. 
+
+### Extensibility


Versioning is important, but may be complicated to incorporate at least in a first pass of role namespaces. Versioning has implications on versioning of other entity types, Rest APIs, UI, Java APIs, etc. and should probably be done as an overall concept rather than something "bespoke" for role namespace.

initial draft

c5ee38d