Dynamic Scopes vs Rich Authorization Requests (RAR) for resource-specific tokens and fine-grained permissions #8488

dgozalo · 2021-09-27T14:24:50Z

dgozalo
Sep 27, 2021

Note: This discussion will be unified in: #8532, please continue any contributions in the new one.

After starting to work on the Dynamic Scopes Proposal that I created earlier today, I've started considering how this feature would interact with OAuth 2 Rich Authorization Requests spec (Currently an early stages draft).

I wanted to go through the pros and cons of going for one or the other and have a discussion on what we want to implement in Keycloak.

Pros of Dynamic Scopes:

Easy to use and implement, with a simple syntax and use cases.
It piggybacks on an already established mechanism such as Scopes, and the spec allows for it.
It's already implemented by some Identity Providers with great success.
There's already a POC proving they can work pretty well in Keycloak.

Cons of Dynamic Scopes:

Even if it's supported by the OAuth spec, it's still based on a loose interpretation of it.
It will allow for very simple use cases, more complex authorization needs may not be supported.
Scopes will not be directly supported by GNAP as of Sept 27th latest version of the specification. Backwards compatibility seems to be assured, albeit following GNAP's constructs, but there's no guarantees that dynamic scopes as such will be supported entirely.

========

Pros of RAR:

It allows for some very complex authorization use cases. Granting Keycloak the possibility to include finer-grained permissions in the JWTs.
It's a completely new parameter in the Auth endpoint, meaning we don't need to mess with the already implemented scopes code.
It's being developed in parallel with GNAP's specification, so by implementing it in Keycloak, we'll have the first stone to eventually move to GNAP.
It's part of FAPI's Lodging Intent future work together with Pushed Authorization Requests.

Cons of RAR:

Harder to implement. We'd need to make sure we make it decoupled enough so we don't have to duplicate the work when eventually implementing GNAP.
The draft is still in progress, changes will most likely emerge, together with GNAP's spec.

Let's discuss the direction we want to go with considering everything presented here.

stianst · 2021-09-28T08:03:10Z

stianst
Sep 28, 2021
Maintainer

One way of dealing with dynamic scopes vs RAR could be to just do a basic translation of a dynamic scope request to a RAR request. That way we're mostly "just implementing RAR".

For example a client that requests "?scope=groups:my-group" that could just be "expanded" into something like "?authorization_details=[{type:groups, identifier:my-group}]". Effectively we would get the "best of both" with a single implementation.

1 reply

dgozalo Sep 28, 2021
Author

I like this idea.

It would essentially translate this user facing feature into a common language that we can use in Keycloak for future implementations such as RAR and GNAP authorization primitives.

stianst · 2021-09-28T15:59:49Z

stianst
Sep 28, 2021
Maintainer

@dgozalo https://github.com/keycloak/keycloak-community/pull/266/files/3aae0909d86b72be110689d6411f0abf5f2aca0c..a7172ec941f754b08ee8124f42d24fbf9d3306b1?notification_referrer_id=MDE4Ok5vdGlmaWNhdGlvblRocmVhZDE4MzMwNjYwMzE6MjI3MTUxMQ%3D%3D

0 replies

stianst · 2021-09-29T10:51:43Z

stianst
Sep 29, 2021
Maintainer

I've come to the conclusion that we must not extend "scopes" without considering RAR, and at the same time we must not implement RAR as a separate thing. The two have very similar needs: a) client includes some additional details in authz request, b) some policies decide if it's permitted or not, c) the user optionally consents to some stuff, and d) some claims are added to tokens.

5 replies

dgozalo Sep 29, 2021
Author

Considering how GNAP, which also implements RAR as its main authorization mechanism, handles Scopes by adding them to the RAR authorization data object, we could most likely support both use cases by implementing the most simple RAR features.

I'm thinking about doing a new design proposal merging both, just to verify whether we could solve both use cases with a single implementation.

10000

jbman Sep 30, 2021

I totally agree with the a,b,c,d wrap up and with supporting two representations (Dynamic scopes and RARs) with the same processing logic.

Here is one option how Keycloak could receive dynamic scope values and translates them into a RAR Authorization data element also called authorization details object.

Scope "group:group-a" is translated to

{
  "type": "group",
  "identifier":"group-a"
}

A handler fro the type "group" would work with the identifier value "group-a" as input. It would also be free to further parse the identifier, if some custom dynamic scope syntax is are required to be accepted.

A RAR request like this

{
   "type": "account_information",
   "actions": [
      "list_accounts",
      "read_balances",
      "read_transactions"
   ],
   "locations": [
      "https://example.com/accounts"
   ]
}

could also be sent as scope with URL encoded JSON after the type prefix:

account_information:%7B%0A%20%20%20%22type%22%3A%20%22account_information%22%2C%0A%20%20%20%22actions%22%3A%20%5B%0A%20%20%20%20%20%20%22list_accounts%22%2C%0A%20%20%20%20%20%20%22read_balances%22%2C%0A%20%20%20%20%20%20%22read_transactions%22%0A%20%20%20%5D%2C%0A%20%20%20%22locations%22%3A%20%5B%0A%20%20%20%20%20%20%22https%3A%2F%2Fexample.com%2Faccounts%22%0A%20%20%20%5D%0A%7D

Keycloak could recognize the JSON (starting with %7B) after the registered type "account_information" or prefix "account_information:". The JSON is send as authorization details object to the registered authorization details handler.

Note 1:
Scope values can become very long this way. Clients could switch to pushed auth requests (PAR) still using scopes, then the
length of scopes is not an issue so much. Or they could switch to RAR and PAR. It is a good to keep this choice up to the clients and to support all in parallel by the authorization server.

Note 2:
Built-in Keycloak RAR type handlers which provide user data (Keycloak as resource server) would probably use an URI as type, e.g. "http://keycloak.org/auth-type/group".
This is suggested at GNAP - 8. Resource Access Rights
https://www.ietf.org/archive/id/draft-ietf-gnap-core-protocol-07.html#section-8

mposolda Oct 1, 2021
Maintainer

This is interesting consideration. I agree that internally will be great to consider scope and authorization_details in some structure like you proposed. However I think that it would be still good if Keycloak consider whether the particular request was sent via the dynamic scope (via scope parameter) or via authorization_details .

There is grant management specification, which considers that client can query the AS about the consent and AS is supposed to return the structure with both scope and authorization_details. See example https://openid.net/specs/fapi-grant-management-01.html#section-6.4 . Note that AS needs to differentiate whether particular request was sent with scope or with authorization_details .
Based on this, it looks better to me if it is defined that specific type (EG. payment) is supposed to be requested by client via authorization_details when other types (EG. group) can be requested by client via scope. Not sure if there is any real benefit of being able to reference for example type group by both scope and authorization_details ?

Overaly I think that scope is supposed to be used for shorter thinks like group:123 when authorization_details is supposed to be used for JSON structure and hence usually RAR will be used together with PAR.

jbman Oct 1, 2021

Thank you for your feedback, the consideration above is mainly about handler implementations, that need to process a rich authorization object only, while originally a (Dynamic) Scope like "group:123" was requested. Keycloak of cause should keep track of the original request format, so that https://openid.net/specs/fapi-grant-management-01.html#section-6.4 could be implemented.

In addition it is about the client being free to decide to request via scope or via RAR, while at Keycloak there would be only one handler registered which can process the type.
Especially for short scopes like group:123 existing clients may prefer scopes. If more details are involved like payment the client could still use a scope according to the transformation pattern outlined above (URL encoded JSON). But probably the client needs to switch to Scope with pushed auth request (PAR) or PAR+RAR, if URL gets to long.

dgozalo Oct 4, 2021
Author

I like this idea. Parsing the dynamic scopes would be a pre-step in the authorization handling pipeline. By "translating" a dynamic scope into an authorization_details representation, the rest of the code can work with that canonical format, and just keep track of the original request format for further presentation and processing.

dteleguin · 2021-09-29T20:38:07Z

dteleguin
Sep 29, 2021

+1 for having dynamic scopes alongside RAR. Also +1 for having a unified core mechanism, with RAR and dynamic scopes being just different ways to use it.

From my personal experience, dynamic scopes have a lot of applications outside FAPI. Moreover, people have been actively using it (in an ad hoc way) until it became restricted in KC 10. One of the examples is pseudo-multi-tenancy using just one realm, where tenant would be indicated as scope=openid email tenant:XXX. One of the pros is that with dynamic scopes, you don't have to upgrade your client code to support the new RAR semantics.

On a related note, it would also be nice to have an API (to be used from within providers) to query for requested scopes and to grant/deny (activate/deactivate) them on the fly.

1 reply

mposolda Sep 30, 2021
Maintainer

On a related note, it would also be nice to have an API (to be used from within providers) to query for requested scopes and to grant/deny (activate/deactivate) them on the fly.

@dteleguin Can you please add some example how this API can be used and how it will look like? I suppose that you mean something different, then the Grant Management API specification, which is supposed to be used by clients to interact with AS as specified here:
https://openid.net/specs/fapi-grant-management-01.html
https://github.com/keycloak/keycloak-community/pull/265/files
?

Dynamic Scopes vs Rich Authorization Requests (RAR) for resource-specific tokens and fine-grained permissions #8488

Uh oh!

Uh oh!

dgozalo Sep 27, 2021

Note: This discussion will be unified in: #8532, please continue any contributions in the new one.

Replies: 4 comments · 7 replies

Uh oh!

Uh oh!

stianst Sep 28, 2021 Maintainer

Uh oh!

dgozalo Sep 28, 2021 Author

Uh oh!

stianst Sep 28, 2021 Maintainer

Uh oh!

stianst Sep 29, 2021 Maintainer

Uh oh!

dgozalo Sep 29, 2021 Author

Uh oh!

Uh oh!

jbman Sep 30, 2021

Uh oh!

mposolda Oct 1, 2021 Maintainer

Uh oh!

Uh oh!

jbman Oct 1, 2021

Uh oh!

dgozalo Oct 4, 2021 Author

Uh oh!

dteleguin Sep 29, 2021

Uh oh!

mposolda Sep 30, 2021 Maintainer

dgozalo
Sep 27, 2021

Replies: 4 comments 7 replies

stianst
Sep 28, 2021
Maintainer

dgozalo Sep 28, 2021
Author

stianst
Sep 28, 2021
Maintainer

stianst
Sep 29, 2021
Maintainer

dgozalo Sep 29, 2021
Author

mposolda Oct 1, 2021
Maintainer

dgozalo Oct 4, 2021
Author

dteleguin
Sep 29, 2021

mposolda Sep 30, 2021
Maintainer