Allow individual grants for client scopes (according to GDPR)

[Fesenmeyer Daniel (IOC/PAU-PM)]

Hi Keycloak developers,

 

We plan to provide a PR with several improvements regarding consent.

 

Currently, the template login-oauth-grant.ftl is not able to distinguish between client consent text and client scope consent text.

We currently use a hack by setting a gui order for all client scopes and detect the client by not having a gui order.

We plan to provide the client consent text in a separate property instead of "clientScopesRequested" (OAuthGrantBean).

 

Furthermore, we have the requirement to handle consent individually per scope. This is because we have to be GDPR compliant. According to GDPR, consent must be freely given and must be specific.

The GDPR website states: "you must explain each data use case separately, giving data subjects an opportunity to consent to each activity individually" [1].

We like to provide a checkbox for each client scope, so that the end-user can decide for each grant, whether she wants to accept or reject it.

A simple approach would be to handle all grants for client scopes as optional. Alternatively, we could add a "required" or "optional" flag to the client scope, which can be configured by the admin.

This way the admin could define scopes which are required by the client (in this case, according to GPDR, consent can be mandatory).

 

The access token will contain all granted scopes - it will not contain the rejected ones.

 

The Account UI currently shows all grants which are provided for a client and allows to revoke them all at once. We would change this UI to also display the client scopes which have not been granted.

We would also provide the possibility to decide per client scope, whether to grant or reject it.

 

What do you think about these improvements? Do you have similar or different requirements?

 

[1] https://gdpr.eu/gdpr-consent-requirements/

 

 

Mit freundlichen Grüßen / Best regards

Daniel Fesenmeyer

Bosch IoT Permissions - Product Area User Management (IOC/PAU-PM)
Bosch.IO GmbH | Ziegelei 7 | 88090 Immenstaad | GERMANY | www.bosch.io
Tel. +49 7545 202-360 | Telefax +49 7545 202-301 | Daniel.F...@bosch.io

Sitz: Berlin, Registergericht: Amtsgericht Charlottenburg; HRB 148411 B
Aufsichtsratsvorsitzender: Dr.-Ing. Thorsten Lücke; Geschäftsführung: Dr. Stefan Ferber, Dr. Aleksandar Mitrovic, Yvonne Reckling

​

[Fesenmeyer Daniel (IOC/PAU-PM)]

Hi Keycloak developers,

 

Since I haven’t got any feedback on this topic yet, I wonder how you handle the GDPR requirements?

 

As we understand it, we have to make it possible that the user can grant or reject consent individually per scope.

 

We are currently considering how to make our PR backwards compatible and have found the following points which have to be considered:

1.      We plan to provide a new default template login-oauth-grant.ftl, which allows to grant or reject consent individually per scope. In order to still support custom templates based on the old “all-or-nothing” logic, we will keep the corresponding logic in the controller.

2.      We are currently considering to make all scopes optional, but we are not sure whether that is an API break. If client code relies on claims like “email” (provided by the “email” scope) or “preferred_user” (provided by the “profile” scope), it will break if the user does not grant consent to the corresponding scopes. Maybe it is better to handle all scopes as required per default and only allow scopes to be rejected when they are explicitly configured as optional? What do you think about this?

 

We would be glad to get your feedback.

 

 

Mit freundlichen Grüßen / Best regards

Daniel Fesenmeyer

Bosch IoT Permissions - Product Area User Management (IOC/PAU-PM)
Bosch.IO GmbH | Ziegelei 7 | 88090 Immenstaad | GERMANY | www.bosch.io
Tel. +49 7545 202-360 | Telefax +49 7545 202-301 | Daniel.F...@bosch.io

Sitz: Berlin, Registergericht: Amtsgericht Charlottenburg; HRB 148411 B
Aufsichtsratsvorsitzender: Dr.-Ing. Thorsten Lücke; Geschäftsführung: Dr. Stefan Ferber, Dr. Aleksandar Mitrovic, Yvonne Reckling

​

--
You received this message because you are subscribed to the Google Groups "Keycloak Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to keycloak-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/keycloak-dev/1091f2148747419d8ff0cd987e1d0899%40bosch.io.

[Stian Thorgersen]

On Tue, 8 Sep 2020 at 13:47, 'Fesenmeyer Daniel (IOC/PAU-PM)' via Keycloak Dev <keyclo...@googlegroups.com> wrote:

Hi Keycloak developers,

 

We plan to provide a PR with several improvements regarding consent.

 

Currently, the template login-oauth-grant.ftl is not able to distinguish between client consent text and client scope consent text. 

We currently use a hack by setting a gui order for all client scopes and detect the client by not having a gui order.

We plan to provide the client consent text in a separate property instead of "clientScopesRequested" (OAuthGrantBean).

What is "client consent text"? I thought we only had consent text associated with client scopes.

 

 

Furthermore, we have the requirement to handle consent individually per scope. This is because we have to be GDPR compliant. According to GDPR, consent must be freely given and must be specific.

The GDPR website states: "you must explain each data use case separately, giving data subjects an opportunity to consent to each activity individually" [1].

We like to provide a checkbox for each client scope, so that the end-user can decide for each grant, whether she wants to accept or reject it.

A simple approach would be to handle all grants for client scopes as optional. Alternatively, we could add a "required" or "optional" flag to the client scope, which can be configured by the admin.

We have an open issue around this here https://issues.redhat.com/browse/KEYCLOAK-7019 - I believe we also have mockups of how the screens should look like somewhere.

Whether or not a client scope is required or optional should be independent of each client. One client may want to have "DoB" for example, while another client has to have "DoB".

Take a look at this for the new admin console and how client scopes are associated with a client:

https://www.keycloak.org/keycloak-community/design/admin-console/#/clients/clientscopes

Take a look at https://issues.redhat.com/browse/KEYCLOAK-8323 for a discussion on the different association types for a client scope. What I proposed there is:

• Always - always added
• Default - added if scope parameter is not specified, or if scope parameter is specified and includes the client scope
• Requested - added only if scope parameter includes the client scope
• Optional - added only if scope parameter includes the client scope, but allows the user to opt-out of the scope on the consent screen

Although thinking about it I think there's a gap there. A client scope can be optional+always or optional+requested, so perhaps "optional" is a separate box, but then again I somewhat don't think it makes sense to have a client scope always added that is not explicitly requested by the client, so perhaps what we have there is good enough.

This way the admin could define scopes which are required by the client (in this case, according to GPDR, consent can be mandatory).

 

The access token will contain all granted scopes - it will not contain the rejected ones.

 

The Account UI currently shows all grants which are provided for a client and allows to revoke them all at once. We would change this UI to also display the client scopes which have not been granted.

We would also provide the possibility to decide per client scope, whether to grant or reject it.

It seems you are summarizing a fairly big feature into a small paragraph here. So basically what you are asking for here is the ability for users to finely manage consents through the account UI, as well as pre-consent? Sounds interesting, but I think this would be worthy its own thread, to not mix it too much with the optional client scopes discussion.

 

 

What do you think about these improvements? Do you have similar or different requirements?

 

[1] https://gdpr.eu/gdpr-consent-requirements/

 

 

Mit freundlichen Grüßen / Best regards

Daniel Fesenmeyer

Bosch IoT Permissions - Product Area User Management (IOC/PAU-PM)
Bosch.IO GmbH | Ziegelei 7 | 88090 Immenstaad | GERMANY | www.bosch.io
Tel. +49 7545 202-360 | Telefax +49 7545 202-301 | Daniel.F...@bosch.io

Sitz: Berlin, Registergericht: Amtsgericht Charlottenburg; HRB 148411 B
Aufsichtsratsvorsitzender: Dr.-Ing. Thorsten Lücke; Geschäftsführung: Dr. Stefan Ferber, Dr. Aleksandar Mitrovic, Yvonne Reckling

[Stian Thorgersen]

On Tue, 15 Sep 2020 at 11:10, 'Fesenmeyer Daniel (IOC/PAU-PM)' via Keycloak Dev <keyclo...@googlegroups.com> wrote:

Hi Keycloak developers,

 

Since I haven’t got any feedback on this topic yet, I wonder how you handle the GDPR requirements?

 

As we understand it, we have to make it possible that the user can grant or reject consent individually per scope.

 

We are currently considering how to make our PR backwards compatible and have found the following points which have to be considered:

1.      We plan to provide a new default template login-oauth-grant.ftl, which allows to grant or reject consent individually per scope. In order to still support custom templates based on the old “all-or-nothing” logic, we will keep the corresponding logic in the controller.

Not sure what you are saying here. Are you saying that you are creating a new template? Or making updates to the existing template. Isn't this just about displaying a checkbox pretty much if a client scope is optional? 

2.      We are currently considering to make all scopes optional, but we are not sure whether that is an API break. If client code relies on claims like “email” (provided by the “email” scope) or “preferred_user” (provided by the “profile” scope), it will break if the user does not grant consent to the corresponding scopes. Maybe it is better to handle all scopes as required per default and only allow scopes to be rejected when they are explicitly configured as optional? What do you think about this?

You can not make scopes optional by default. A client has to explicitly be able to handle optional scopes, otherwise it will not get the information it is expecting. It basically has to be an option when assigning a client scope with a client to make it optional or not.

To view this discussion on the web visit https://groups.google.com/d/msgid/keycloak-dev/c24c894346494746b3eebe4017ca7786%40bosch.io.

[Fesenmeyer Daniel (IOC/PAU-PM)]

Hi Stian,

 

Thanks for your answers and feedback.

 

With “client consent text” I meant what is called “Client Consent Screen Text” in the Admin UI, when displaying a client.

This text can only be configured when both “Consent Required” and “Display Client On Consent Screen” are enabled.

This text is displayed in the template login-oauth-grant.ftl in a list together with the “Consent Screen Text”s of the client scopes (from method OAuthGrantBean#getClientScopesRequested).

We would like to separate this client information from the client scopes information, by adding new methods for the client and client scopes information. We will keep the existing method for backwards compatibility. Is this the way to go, or do you have some other versioning mechanism for view-models?

Regarding optional consent: Thanks for pointing us to the issue https://issues.redhat.com/browse/KEYCLOAK-8323. We would like to prepare a PR for this.

You mentioned four types of client scope assignments: always, default, requested and optional. You already mentioned that it probably makes sense to have a separate checkbox for the optional type.

We suggest to distinguish these two properties for client scope assignments:

·         Condition for displaying the client scope (as defined in your mail below):

o   Always - always added

o   Default - added if scope parameter is not specified, or if scope parameter is specified and includes the client scope

o   Requested - added only if scope parameter includes the client scope

·         Whether consent is required by the user

o   Mandatory: User has to grant consent in order to proceed with the login flow

o   opt-in: Consent is optional and inactive per default, can be explicitly granted at the consent screen

o   opt-out: Consent is optional and active per default, can be explicitly rejected at the consent screen

We are not sure what possible use cases of the “default” type are. Maybe “always” and “requested” are sufficient?

 

As you already suggested, we consider to discuss possible extensions to the Account UI (like fine-grained consent management) in another thread.

 

Mit freundlichen Grüßen / Best regards

Daniel Fesenmeyer

Bosch IoT Permissions - Product Area User Management (IOC/PAU-PM)
Bosch.IO GmbH | Ziegelei 7 | 88090 Immenstaad | GERMANY | www.bosch.io
Tel. +49 7545 202-360 | Telefax +49 7545 202-301 | Daniel.F...@bosch.io

Sitz: Berlin, Registergericht: Amtsgericht Charlottenburg; HRB 148411 B
Aufsichtsratsvorsitzender: Dr.-Ing. Thorsten Lücke; Geschäftsführung: Dr. Stefan Ferber, Dr. Aleksandar Mitrovic, Yvonne Reckling

​

[Stian Thorgersen]

On Thu, 17 Sep 2020 at 12:00, Fesenmeyer Daniel (IOC/PAU-PM) <Daniel.F...@bosch.io> wrote:

Hi Stian,

 

Thanks for your answers and feedback.

 

With “client consent text” I meant what is called “Client Consent Screen Text” in the Admin UI, when displaying a client.

This text can only be configured when both “Consent Required” and “Display Client On Consent Screen” are enabled.

This text is displayed in the template login-oauth-grant.ftl in a list together with the “Consent Screen Text”s of the client scopes (from method OAuthGrantBean#getClientScopesRequested).

We would like to separate this client information from the client scopes information, by adding new methods for the client and client scopes information. We will keep the existing method for backwards compatibility. Is this the way to go, or do you have some other versioning mechanism for view-models?

Thanks for explaining it, as I didn't even know about this. It is rather strange both how it is configured and certainly even stranger that it is just added in the list of "consents".

Wondering a bit about what the intended use of "client consent screen text" is. If it's included in the "consents" then it can be assumed it's supposed to be something that the user consents to, but that makes no sense. The client is the entity asking for permissions, not the entity providing any access. 

What do you use this field for? Just wondering why this wouldn't really just be the description field.

 

Regarding optional consent: Thanks for pointing us to the issue https://issues.redhat.com/browse/KEYCLOAK-8323. We would like to prepare a PR for this.

You mentioned four types of client scope assignments: always, default, requested and optional. You already mentioned that it probably makes sense to have a separate checkbox for the optional type.

We suggest to distinguish these two properties for client scope assignments:

·         Condition for displaying the client scope (as defined in your mail below):

o   Always - always added

o   Default - added if scope parameter is not specified, or if scope parameter is specified and includes the client scope

o   Requested - added only if scope parameter includes the client scope

·         Whether consent is required by the user

o   Mandatory: User has to grant consent in order to proceed with the login flow

o   opt-in: Consent is optional and inactive per default, can be explicitly granted at the consent screen

o   opt-out: Consent is optional and active per default, can be explicitly rejected at the consent screen

We are not sure what possible use cases of the “default” type are. Maybe “always” and “requested” are sufficient?

* If no scope query param is passed, then client scopes with "default" is used. 

* If scope query param is passed, then all "always" client scopes are used, but matching "requested" client scopes

I'm not convinced it should be a separate property. From my reasoning here "always" should be used for client scopes the client must have to do its job, hence these can not be optional. So I would probably argue that only "requested" type client scopes can be opt-in/out. So I would think we could do this with a single property with the values:

* Always - always added (user can not opt-in/out)

* Default - only added if client has requested a specific scope (user can not opt-in/out)
* Requested - added only if scope parameter includes the client scope (user can not opt-in/out)
* Optional - added only if scope parameter includes the client scope, but allows the user to opt-out of the scope on the consent screen

Perhaps an alternative could be to be able to specify default scope for a client separately, then have the options:

* Always

* Requested

* Optional

[Schuster Sebastian (IOC/PDL22)]

As usual late to the party… J

 

I see two cases here:

1.     Client scopes are defined by the accessing client

Each scope text would describe a certain function of that client and the necessary data. The user can pick which scopes/functions/purposes to allow.
Then, client consent screen text would probably just be another short description of the client.
In this case client scopes might be mapped to roles defined by resource servers. This mapping is created during some client onboarding process.

Simple example from the top of my head:
client consent screent text: “Home Automator is the newest App by Home Automation INC. We need your consent to…”
client scope 1 text: “Warn you when you are running out of beer. To do that, we need to access your fridge camera.” Internally, this might be mapped
to a role home-connect.view-fridge-camera that is understood by the Home Connect API controlling the fridge.
client scope 2 text: “Optimize energy consumption of your household devices. For this, we need to control all your household devices.” Internally, this might be mapped to roles like home-connect.control-fridge, home-connect.control-heating, etc.

In this scenario, there is a nice level of indirection as resource servers only have to understand the roles and what they give access to not caring about
the scopes defined by the client. Also, the consent could be made GDPR compliant

2.     Client scopes are defined by the resource server

Each scope could only define what data/functions the client gets access to.
Then the client consent screen text would have to describe the client and what it wants to do and why it needs access.
The user could still deny some of the scopes and it would be up to the client to deal with this situation, maybe it just won’t work so some scopes might have to be mandatory.
This scenario is pretty much what you currently find in the web or when allowing access to calendar etc. on your mobile phone. So it should definitely be supported.

 

Best regards,

Sebastian

 

Mit freundlichen Grüßen / Best regards

Dr.-Ing. Sebastian Schuster

Project Delivery Berlin 22 (IOC/PDL22)
Bosch.IO GmbH | Ullsteinstr. 128 | 12109 Berlin | GERMANY | www.bosch.io
Tel. +49 30 726112-485 | Mobil +49 152 02177668 | Telefax +49 30 726112-100 | Sebastian...@bosch.io

Sitz: Berlin, Registergericht: Amtsgericht Charlottenburg; HRB 148411 B
Aufsichtsratsvorsitzender: Dr.-Ing. Thorsten Lücke; Geschäftsführung: Dr. Stefan Ferber, Dr. Aleksandar Mitrovic, Yvonne Reckling

To view this discussion on the web visit https://groups.google.com/d/msgid/keycloak-dev/CAJgngAchSDTVhywUcyDDopQLQLaTbAicv024ndQOrPMyDj8m1Q%40mail.gmail.com.

[Stian Thorgersen]

Now you're making things complicated, but interesting as well ;)

On Wed, 23 Sep 2020 at 18:07, Schuster Sebastian (IOC/PDL22) <Sebastian...@bosch.io> wrote:

As usual late to the party… J

 

I see two cases here:

1.     Client scopes are defined by the accessing client

Each scope text would describe a certain function of that client and the necessary data. The user can pick which scopes/functions/purposes to allow.
Then, client consent screen text would probably just be another short description of the client.
In this case client scopes might be mapped to roles defined by resource servers. This mapping is created during some client onboarding process.

Simple example from the top of my head:
client consent screent text: “Home Automator is the newest App by Home Automation INC. We need your consent to…”
client scope 1 text: “Warn you when you are running out of beer. To do that, we need to access your fridge camera.” Internally, this might be mapped
to a role home-connect.view-fridge-camera that is understood by the Home Connect API controlling the fridge.
client scope 2 text: “Optimize energy consumption of your household devices. For this, we need to control all your household devices.” Internally, this might be mapped to roles like home-connect.control-fridge, home-connect.control-heating, etc.

In this scenario, there is a nice level of indirection as resource servers only have to understand the roles and what they give access to not caring about
the scopes defined by the client. Also, the consent could be made GDPR compliant

I'm not sure about this one - it's a nicer user experience, but I don't think it's up to the accessing client to describe what it is accessing. 

As an example an application could say "Warn you when you are running out of beer. To do that, we need to access your fridge camera.", but actually behind the scenes request "Super user admin privileges".

Perhaps instead an application could label why it is requesting different scopes, so it would be something like:

Beer app <client display name>

-------------------------------------------------------------------------------------------------------------------------

Home Automator is the newest App by Home Automation INC. We need your consent to… <client consent screen text>

-------------------------------------------------------------------------------------------------------------------------

Warn you when you are running out of beer, to do that we need: <dunno what this is, but something that let's the client associate text with what scopes it is requesting>

* Access to your fridge camera <client scope consent text>

* Access to your email address <client scope consent text>

2.     Client scopes are defined by the resource server

Each scope could only define what data/functions the client gets access to.
Then the client consent screen text would have to describe the client and what it wants to do and why it needs access.
The user could still deny some of the scopes and it would be up to the client to deal with this situation, maybe it just won’t work so some scopes might have to be mandatory.
This scenario is pretty much what you currently find in the web or when allowing access to calendar etc. on your mobile phone. So it should definitely be supported.

This is pretty much what we have today isn't it? With the exception of allowing users to opt-out of individual client scopes? 

[Schuster Sebastian (IOC/PDL22)]

Hi Stian,

 

Your proposal sound cool in that it allows to reuse existing scopes and their texts as defined by the resource server. However, this way you cannot really enable or disable complete functions/purposes. I assume that most of the time, for a function a client might actually need access to different things. E.g. for the beer warning, to fridge and email address. The function would not work without both so it would not make sense to have a fridge and an email scope and allowing the user to enable one and disable the other.

This should be done on a function level – and function is in the domain of the client. So function as scope should be defined by the client. But you are right, the client could write anything about what he is accessing and there would not be any guarantees. So maybe we should add descriptions of what can be accessed to the roles defined by the resource server and print this on the consent screen. Could be just a list of bullet points like:

 

“Warn you when you are running out of beer. To do that, we need to access your fridge camera”  <-switch->  <- client scope consent screen text defined by client

 

“The client will be able to:” <- text by Keycloak

·         “Access your fridge camera” <- role text defined by resource server

·         “Access your email address” <- role text defined by resource server

 

“Optimize energy consumption of your household devices. For this, we need to control all your household devices”  <-switch->  <- client scope consent screen text defined by client

 

“The client will be able to:” <- text by Keycloak

·         “Access your fridge camera” <- role text defined by resource server

·         “Access your oven” ” <- role text defined by resource server

·         …

 

There must definitely be some kind of relation between texts by the client describing functions which the user may trust or not and texts by the resource server which he obviously trusts…

 

Best regards,

Sebastian

 

 

Von: Stian Thorgersen <stho...@redhat.com>
Gesendet: Freitag, 25. September 2020 08:59
An: Schuster Sebastian (IOC/PDL22) <Sebastian...@bosch.io>
Cc: Fesenmeyer Daniel (IOC/PAU-PM) <Daniel.F...@bosch.io>; keyclo...@googlegroups.com
Betreff: Re: [keycloak-dev] Allow individual grants for client scopes (according to GDPR)

 

Now you're making things complicated, but interesting as well ;)

 

Exactly!

[Stian Thorgersen]

That makes a lot of sense. I do like the idea of the client being able to list the high-level functions/capabilities it can provide, allowing the user to opt-in/out to those functions, and with some details on what access those functions require.

Not sure how we'd do what with OAuth 2.0 scopes, and Keycloak Client Scopes, though. An OAuth 2.0 scope is a "permissions" rather than a function (group of scopes), and we'd want to do this in a standard way.

This does cry for a complete design proposal, as there's quite a few parts involved here, and we'd want to design something that is easy to configure/setup and can be used with standard RP libraries.

Perhaps also we'd want to approach this in stages - first stage to add support for opt-in/out scopes, then second stage to look at the functions vs client-scopes?

[Schuster Sebastian (IOC/PDL22)]

Hi Stian,

 

Thankfully, OAuth2 doesn’t really say anything about scopes except a) they give access and b) more scopes means more access. I would say having a scope description combining a description of what is being accessed and what happens with it is still covered by the spec. ;)

Anyways, I would also propose we first try to do the opt-in or out of individual scopes and separate the client consent screen texts. I will see if I can find a volunteer to write the design document for the client scope as client function feature. Daniel? ;)

 

Best regards,

Sebastian

 

Mit freundlichen Grüßen / Best regards

Dr.-Ing. Sebastian Schuster

Project Delivery Berlin 22 (IOC/PDL22)
Bosch.IO GmbH | Ullsteinstr. 128 | 12109 Berlin | GERMANY | www.bosch.io
Tel. +49 30 726112-485 | Mobil +49 152 02177668 | Telefax +49 30 726112-100 | Sebastian...@bosch.io

Sitz: Berlin, Registergericht: Amtsgericht Charlottenburg; HRB 148411 B
Aufsichtsratsvorsitzender: Dr.-Ing. Thorsten Lücke; Geschäftsführung: Dr. Stefan Ferber, Dr. Aleksandar Mitrovic, Yvonne Reckling

 

[Stian Thorgersen]

On Tue, 29 Sep 2020 at 17:58, Schuster Sebastian (IOC/PDL22) <Sebastian...@bosch.io> wrote:

Hi Stian,

 

Thankfully, OAuth2 doesn’t really say anything about scopes except a) they give access and b) more scopes means more access. I would say having a scope description combining a description of what is being accessed and what happens with it is still covered by the spec. ;)

Sure, but the interesting aspect is that you are asking for scope on a resource server, while what we want to display is the functions that the client uses those scopes for ;)

[Schuster Sebastian (IOC/PDL22)]

The same thing used to be in the client consent screen text before, so it’s not a dramatic change. It’s just a question how you implement the client onboarding. There might be a fancy editor where developers can create clients and their scopes with texts and attach some of the available roles provided by the resource servers. But that would most likely be outside of Keycloak…