Usability improvements for Client Scope configuration #19869

jbman · 2023-04-21T10:15:48Z

jbman
Apr 21, 2023

Recently we conducted a Keycloak training with sixteen participants. They learned how to configure a client including client scope configuration, so that the access token contains only roles which are relevant for the client app. We found the following issues within the Admin console.

Mappers and Token Evaluate feature

The feature was found to be very valuable.

Issues:

Participants had a hard time to remember how to find it. New users will probably not find it.
Many participants struggled to select a user, as you need to start typing a username which exists, to get a user suggested.

Proposals for improvement:

Get rid of second-level tabs. Move both tabs top-level.
Use the current user as default, so that you can view evaluated tokens right away
Unify selection of a user. When a user is added to a group, the user can be searched in a popup dialog, but at Evaluate feature it is different

Dedicated client scope and "Full scope allowed" setting

Least privilege is an important security principle. To create tokens with the right subset of roles, the dedicated client scope must be opened, full scope allowed must be switched off and the right subset of roles must be selected.

Client level:

Client scope level:

Issues:

The text of the "Scope" tab where "Full Scope allowed" can be set is the same as for defining roles. ("No roles for this client
You haven't created any roles for this client. Create a role to get started.").
The dedicated client scope and the full scope allowed setting are quite some clicks away and hard to find. They set of roles which may be delegated to the client should be easier to find.

Proposals for improvement:

Add the tabs "Mappers" and "Scope" of the dedicated scopes back to the client level. Tab "Scope" could be named "Delegated Roles" and the setting "All roles allowed" (or "Role Scope" and still "Full Scope allowed")
Use a dedicated text to explain that only selected roles are delegated to the client.

jonkoops · 2023-04-21T10:19:05Z

jonkoops
Apr 21, 2023

ping @ssilvert @xianli123

0 replies

xianli123 · 2023-04-22T12:48:04Z

xianli123
Apr 22, 2023

@jonkoops Thanks for involving me. I agree with displaying the "Mapper" and "Scope" tabs at the client level. But I'm not sure if the dedicated scope will be removed in the future. What's the latest decision on it? Could we display the "Mapper" and "Scope" tabs at the client level? @stianst Thanks.

0 replies

ssilvert · 2023-04-24T12:16:15Z

ssilvert
Apr 24, 2023
Collaborator

I tend to agree with all the above proposals for improvement. But I think we do need @stianst to weigh in with his broader perspective.

0 replies

pedroigor · 2023-06-12T12:36:28Z

pedroigor
Jun 12, 2023
Collaborator

I also tend to agree with most of the points.

Default to the current user when evaluating client scopes reduces steps and makes it easier to quickly achieve what you want. Most of the time, you are evaluating client scopes to check token claims and their format. Regardless of the user.
Change Full Scope Allowed to Include Default Roles or something similar when managing the dedicated client scope. The current text is confusing and I think it does not make clear the impact of this setting during authentication. I might be wrong, but for me, this flag is basically changing what is included by default in a token.
The tab for the second bullet above is also not clear about the purpose of assigning roles to scope when Full Scope Allowed is disabled. We should make more clear that it is related to the user roles to be included in tokens when the scope is granted.

0 replies

xianli123 · 2023-06-13T04:42:04Z

xianli123
Jun 13, 2023

@pedroigor Thanks for your comments.

0 replies

xianli123 · 2023-06-13T06:05:40Z

xianli123
Jun 13, 2023

Hi @pedroigor,

Change Full Scope Allowed to Include Default Roles or something similar when managing the dedicated client scope.

As for your suggestion for the Full Scope Allowed, I checked the Keycloak official documentation. It goes:

By default, the effective roles of scopes are every declared role in the realm. To change this default behavior, toggle Full Scope Allowed to OFF and declare the specific roles you want in each client. You can also use client scopes to define the same role scope mappings for a set of clients.

So does it make sense to change the Full Scope Allowed to All effective roles allowed?

5 replies

jbman Jun 13, 2023
Author

+1 for "All effective roles allowed?"
In addition the tab needs an other name like "Delegated Roles" or "Delegation Scope" to gradually move away from the term "Scope"which is to generic.

xianli123 Jun 14, 2023

Hi @pedroigor @jbman Based on your suggestions and thoughts. I came up with an idea to improve the Dedicated-client-scope as shown in the screenshot below. The Dedicated-client-scope will be removed from the Client scopes tab.

Move the "Mappers" to the first-level tab bar. Users can add dedicated mappers for this client.
Move the "Scopes" from the dedicated-client-scope to the Roles tab. The name will be changed to the "Delegated roles".
Change the Full Scope Allowed to All effective roles allowed and add some descriptions for this feature. If the All effective roles allowed is disabled, users can select some roles to add.

What do you think? Please take a look and share your thoughts. Thanks!

jbman Jun 14, 2023
Author

I like the naming, but I'm not in favor of using these sub-tabs in general
In addition in this specific case, the two tabs "Defined roles" (Dedicated roles doesn't seem to be the right name) and "Delegated roles" are very different things:

The defined roles are roles defined in context of the client.
The delegated roles (f.k.a "scope" or "Role Scope") are any realm or client roles the client application can use on behalf of the user.

Would prefer to have top level tabs "Roles" (as is) and "Delegated Roles"

xianli123 Jun 14, 2023

@jbman I Understood. That makes sense to set "Delegated Roles" as a top-level tab according to your explanation. Thanks! What do you think? @pedroigor

pedroigor Jul 4, 2023
Collaborator

Sorry for the late reply. It looks much clear now.

I agree with @jbman that Roles and Delegated Roles are different things.

I'm not 100% sure about the Delegated Roles but I don't have a better alternative. If we could find some term that makes more explicit that this is about "restricting which client roles are mapped to tokens", better.

Regarding the tab position/level, I like both. Having a single tab kinda creates a workspace where you are managing roles but I see the concern about using sub-tabs. No strong opinion :)

We can also work a bit on the description of the Delegated Roles tab but it can be a follow-up.

xianli123 · 2023-06-15T02:38:21Z

xianli123
Jun 15, 2023

Hi@pedroigor @jbman, with regard to the Evaluate function, does it make sense to move it to the Action menu as shown below?

After clicking the Evaluate tab, there will be a modal popup. The modal seems like the current UI.

3 replies

xianli123 Jun 27, 2023

Hi @jbman @pedroigor Could you please take a look at the "Evaluate" function above? What do you think of the updates? Thanks!

jbman Jun 30, 2023
Author

Hi @xianli123,
think it would be better to use the whole screen, as quite some data needs to be displayed. In addition "Evaluate" is not really an "Action" on the client like "Export" or "Delete". The feature would be hidden again. Still voting for using a top level tab on the client.
Would use popup dialogs only for selection of values where this doesn't fit into an UI element at the page.

Note: "Evaluation settings" should be "Evaluation result" in the screen design.

pedroigor Jul 4, 2023
Collaborator

Yeah, I also think we should not use a modal.

The current overall design of the UI works for me.

xianli123 · 2023-06-30T08:32:20Z

xianli123
Jun 30, 2023

@jbman @pedroigor Thanks for your reply. According to your suggestions, I updated the current design.

The client-dedicated scopes and Evaluate will be moved from the Client scopes tab to the top-level tab bar. In addition, client-dedicated scopes will be split into 2 tabs named "Dedicated roles" and "Mappers". There will just be a client scope list in the Client scopes tab. I pasted the image as shown below. Does it make sense?

6 replies

xianli123 Jun 30, 2023

@jbman That's a good point. Thanks for your suggestions.

@pedroigor @stianst Could you please take a look? Shall we go ahead with the new design? Thanks!

pedroigor Jul 4, 2023
Collaborator

I would change the text description to:

By default, a client gets all the effective roles of the user they are acting on behalf of. To change this behavior, toggle `All effective roles allowed` to `OFF`. Then declare which roles are allowed, when this client or client scope is used.

I agree about renaming the tab Client Scope -> Scope to Delegated Roles.

The Evaluate tab as a top-level tab also makes sense to me. It is not strictly related to client scopes but to mappers, etc.

xianli123 Jul 4, 2023

Thanks. @pedroigor

By default, a client gets all the effective roles of the user they are acting on behalf of. To change this behavior, toggle All effective roles allowed to OFF. Then declare which roles are allowed, when this client or client scope is used.

That makes more sense.

pedroigor Jul 4, 2023
Collaborator

Perhaps make clear that "gets" means mapping roles into tokens. Not sure ...

xianli123 Jul 27, 2023

Hi @stianst, could you please look at the updates above and share your thoughts? Could we change the client scopes inside the client? Thanks!

Usability improvements for Client Scope configuration #19869

Uh oh!

Uh oh!

Mappers and Token Evaluate feature

Dedicated client scope and "Full scope allowed" setting

Replies: 8 comments · 14 replies

Uh oh!

Uh oh!

Uh oh!

ssilvert Apr 24, 2023 Collaborator

Uh oh!

Uh oh!

pedroigor Jun 12, 2023 Collaborator

Uh oh!

Uh oh!

Uh oh!

jbman Jun 13, 2023 Author

Uh oh!

Uh oh!

jbman Jun 14, 2023 Author

Uh oh!

Uh oh!

pedroigor Jul 4, 2023 Collaborator

Uh oh!

Uh oh!

Uh oh!

jbman Jun 30, 2023 Author

pedroigor Jul 4, 2023 Collaborator

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pedroigor Jul 4, 2023 Collaborator

Uh oh!

Uh oh!

pedroigor Jul 4, 2023 Collaborator

Uh oh!

Replies: 8 comments 14 replies

ssilvert
Apr 24, 2023
Collaborator

pedroigor
Jun 12, 2023
Collaborator

jbman Jun 13, 2023
Author

jbman Jun 14, 2023
Author

pedroigor Jul 4, 2023
Collaborator

jbman Jun 30, 2023
Author

pedroigor Jul 4, 2023
Collaborator

pedroigor Jul 4, 2023
Collaborator

pedroigor Jul 4, 2023
Collaborator