Subject: [OAUTH-WG] Rich Authorization Requests feedbacks on implementation

From: Nicolas Mora <[email-masked]>
Date: Sun, 10 Jan 2021 20:36:36 -0500

Hello,

I've implemented Rich Authorization Requests defined in 
draft-ietf-oauth-rar-03 for Glewlwyd soon-to-be-released 2.5 [1], and I 
humbly wanted to write my feedback about this implementation to share my 
experience.

For starters, this implementation and my following feedbacks are based 
on the prism of Glewlwyd's implementation and philosophy, and my limited 
experience on OAuth2, so I appologize in advance if I write non-sense or 
big mistakes.

1 - Design

The way I saw it, there are 2 different approaches to implement oauth2 
rar: either to get a token with a more detailed scope, or to get a 
one-time token with extra grants.

Both are not exclusive, but a big difference I see between those 2 
approaches is the grant access from the user part. The second approach 
would require the user to know what extra grant is asked by the client 
every time the client asks for it, i.e. when the client redirects the 
user to the /authorization endpoint.

To be more consistent with Glewlwyd's philosophy, I chose the first 
approach, with those rules.
The AS administrator declares what rar types are allowed [2]
   - a rar type has a defined set of locations, actions, datatypes and 
enriched authorization details that the client can ask for
   - the client must be explicitly allowed to add a rar type in the 
authorization request
   - a rar type can be linked to one or more scope. In that case, the 
authorization request must include at least one of the linked scope, and 
the scope must be available for the user and the scope must be granted 
to the client
   - the client can add as many properties as required in the rar type, 
those extra properties are not verified by the AS, on access granted, 
the extra properties will be present in the "authorization_details" result.

On first use of a rar type by a client for a user, the user must grant 
to the client the rar access [3]. That's why the grant message will show 
to the user ALL access possible via this rar type
Once this access is granted or not, the user will not be asked again on 
another authorization request by the client (but is can be changed at 
any time, as a scope grant).

2 - Limitations

In this design, the AS has a limited control over the 
authorization_details content, and the trust between the AS and the 
client must be high enough so if a rar type can gain access to sensitive 
actions or information, the user should know about it.

Also, in the draft specification, the only mandatory element type in a 
rar is the "type" element. In my point of view, this means that the 
business logic is mostly defined by the RS, rather than the AS.

Therefore, for a client implementation to be compliant with the specs, 
there's not much to do: add as a parameter a JSON array with objects 
containing at least one "type" string property in it.

3 - Extensions

I believe one way to mitigate these limitations is to allow extensions 
to be defined on top of the rar specifications. An extension can be 
declared like this:

"RAR Extension XYZ:
A rar whose type is XXX
- Actions available: YYY, ZZZ or AAA
- datatypes possibles: BBB, CCC, DDD or EEE
- additional elements mandatory: an array of FFF and an object of GGG to 
represent access to some"

Like this, if the AS, the RS and the client agree on using a rar 
extension, they can have at least a detailed pattern on what to expect 
in the rar type.

Any thoughts?

/Nicolas

[1] https://github.com/babelouest/glewlwyd
[2] 
https://raw.githubusercontent.com/babelouest/glewlwyd/master/docs/screenshots/plugin-oidc-rar.png
[3] 
https://raw.githubusercontent.com/babelouest/glewlwyd/master/docs/screenshots/login-rar-grant.png

---

From: Justin Richer <[email-masked]>
Date: Wed, 13 Jan 2021 16:51:59 -0500

Hi Nicolas,

> On Jan 10, 2021, at 8:36 PM, Nicolas Mora <nicolas=[email-masked]> wrote:
> 
> Hello,
> 
> I've implemented Rich Authorization Requests defined in draft-ietf-oauth-rar-03 for Glewlwyd soon-to-be-released 2.5 [1], and I humbly wanted to write my feedback about this implementation to share my experience.
> 

> For starters, this implementation and my following feedbacks are based on the prism of Glewlwyd's implementation and philosophy, and my limited experience on OAuth2, so I appologize in advance if I write non-sense or big mistakes.
> 

Thanks for reaching out! Implementation experience is incredibly valued here in the IETF, especially when someone’s coming to the spec from “outside” the community. :)

> 1 - Design
> 
> The way I saw it, there are 2 different approaches to implement oauth2 rar: either to get a token with a more detailed scope, or to get a one-time token with extra grants.
> 
> Both are not exclusive, but a big difference I see between those 2 approaches is the grant access from the user part. The second approach would require the user to know what extra grant is asked by the client every time the client asks for it, i.e. when the client redirects the user to the /authorization endpoint.
> 
> To be more consistent with Glewlwyd's philosophy, I chose the first approach, with those rules.
>  - a rar type has a defined set of locations, actions, datatypes and enriched authorization details that the client can ask for
>  - the client must be explicitly allowed to add a rar type in the authorization request
>  - a rar type can be linked to one or more scope. In that case, the authorization request must include at least one of the linked scope, and the scope must be available for the user and the scope must be granted to the client
>  - the client can add as many properties as required in the rar type, those extra properties are not verified by the AS, on access granted, the extra properties will be present in the "authorization_details" result.
> 

I think this is an interesting approach, but I’m not sure about a few things:

- What’s the utility of linking to a scope. Why require both structures to be interpreted together like that?
- There will absolutely be implementations that do not limit which RAR types (or even values) the client is allowed to send, much like there are implementations today that don’t restrict scopes on a per-client basis.
- I don’t think that we can say the AS doesn’t verify “extra required properties”, since the AS can (and arguably should) know about the details of the “type” being used, and enforce internal consistency and structure.

> On first use of a rar type by a client for a user, the user must grant to the client the rar access [3]. That's why the grant message will show to the user ALL access possible via this rar type
> Once this access is granted or not, the user will not be asked again on another authorization request by the client (but is can be changed at any time, as a scope grant).
> 

It’s always up to the AS to determine what the granted access is, whether it’s for a new token, a limitation of existing grant (via refresh token), or a client asking for something “additional” for whatever purpose. 

> 2 - Limitations
> 
> In this design, the AS has a limited control over the authorization_details content, and the trust between the AS and the client must be high enough so if a rar type can gain access to sensitive actions or information, the user should know about it.

The AS has full control to interpret the authorization_details content, and apply it to access token granting policies, which include whether to ask the user to grant anything. 

> 
> Also, in the draft specification, the only mandatory element type in a rar is the "type" element. In my point of view, this means that the business logic is mostly defined by the RS, rather than the AS.

Just like “scope” in OAuth, it’s ultimately enforced by the RS, but the AS works in the process to interpret and potentially modify the meaning of the scope. 

> 
> Therefore, for a client implementation to be compliant with the specs, there's not much to do: add as a parameter a JSON array with objects containing at least one "type" string property in it.
> 

Yup — and even more, most clients will be sending in static or templated values that the developers get from documentation, much like they do with scopes in APIs today. Keeping it simple for clients is definitely a goal!

> 3 - Extensions
> 
> I believe one way to mitigate these limitations is to allow extensions to be defined on top of the rar specifications. An extension can be declared like this:
> 
> "RAR Extension XYZ:
> A rar whose type is XXX
> - additional elements mandatory: an array of FFF and an object of GGG to represent access to some"
> 
> Like this, if the AS, the RS and the client agree on using a rar extension, they can have at least a detailed pattern on what to expect in the rar type.

I like that structure, but not for “extensions” exactly; more properly, I think this can be some guidance on how to create a RAR “type” definition. This fits with the philosophy of “type” defining what’s allowed to go in the object, but it would allow for a more formal definition of what that connection is. Should this be normative, or just informative, though? I’m not sure yet — I will try to come up with some proposed text on that and propose a PR.

 — Justin

> [2] https://raw.githubusercontent.com/babelouest/glewlwyd/master/docs/screenshots/plugin-oidc-rar.png
> [3] https://raw.githubusercontent.com/babelouest/glewlwyd/master/docs/screenshots/login-rar-grant.png
> 
> _______________________________________________
> OAuth mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/oauth

---

From: Nicolas Mora <[email-masked]>
Date: Wed, 13 Jan 2021 21:50:26 -0500

Hello,

Thank you for your feedback, I'll add some precision then

> - What’s the utility of linking to a scope. Why require both structures to be interpreted together like that?

Linking a rar to a scope is not mandatory, i.e. if a rar type has no 
scope, then the type will be available for every request and every user.

That said, in Glewlwyd, the access level is the scopes. A user "has" a 
set of scopes which can be granted or not during authorization requests.
Therefore if the client requests scopes and some are not available for 
the user, the grant will be limited to the ones available.

The rar types are another type of access levels, therefore I assume that 
a rar type can be unavailable for a user, so I allow to bind a rar type 
to the scopes for that purpose. But that's a design choice.

> - I don’t think that we can say the AS doesn’t verify “extra required properties”, since the AS can (and arguably should) know about the details of the “type” being used, and enforce internal consi…

I agree, but the specs doesn't mandate, allow, nor forbid anything about 
the extra properties.
Assuming that, I didn't want the admin to have to use a hardcoded rar 
structure, and because this implementation is a first shot, I didn't 
want to complicate the rar type configuration, which could be dangerous 
to implement.
Other part of the application are very customizable and were painful to 
implement.

> It’s always up to the AS to determine what the granted access is, whether it’s for a new token, a limitation of existing grant (via refresh token), or a client asking for something “additional” for…
I don't allow a client to upgrade the grant access via the refresh 
token, only the same grant access. Therefore to be consistent, the 
client can't change the rar request during a refresh, and the new access 
token will have the same rar content as the one granted during the 
authorization.

> Just like “scope” in OAuth, it’s ultimately enforced by the RS, but the AS works in the process to interpret and potentially modify the meaning of the scope.
Yes, if we use a rar reduced only to what's required in the specs, then 
a rar type has no more information than a scope, so the advantage of rar 
lies beyond the mandatory parts of the specs.

But to have a usable rar, the triad client-AS-RS must previously agree 
to use rar types defined outside of the specs.

This is not necessary a disadvantage though.

> Yup — and even more, most clients will be sending in static or templated values that the developers get from documentation, much like they do with scopes in APIs today. Keeping it simple for client…
Ack

> I like that structure, but not for “extensions” exactly; more properly, I think this can be some guidance on how to create a RAR “type” definition. This fits with the philosophy of “type” defining…
I used the name extension because the first example I had in mind is the 
extensions and protocols describe in the websocket specs, but I don't 
mind the name that should be used.

Describing the rar types normalization structure is what I think could 
be improved, at least specifying how it should be normalized and for 
what purpose.

/Nicolas