Skip to content

Commit

Permalink
Merge pull request #82 from SURFnet/review-rfc-phase3
Browse files Browse the repository at this point in the history 
Review rfc phase3
  • Loading branch information
@michielbdejong
michielbdejong authored Jul 5, 2024
2 parents 45ef23c + 2fc2b3f commit a49dce2
Showing 1 changed file with 391 additions and 0 deletions.
391 changes: 391 additions & 0 deletions phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,391 @@
<?xml version="1.0" encoding="utf-8"?>
<?xml-model href="rfc7991bis.rnc"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>

<!DOCTYPE rfc [
<!ENTITY nbsp "&#160;">
<!ENTITY zwsp "&#8203;">
<!ENTITY nbhy "&#8209;">
<!ENTITY wj "&#8288;">
]>

<rfc
xmlns:xi="http://www.w3.org/2001/XInclude"
category="info"
docName="draft-vandermeulen-oauth-resource-helper-00"
ipr="trust200902"
obsoletes=""
updates=""
submissionType="IETF"
xml:lang="en"
version="3">

<front>
<title abbrev="OAuth Resource Helper">OAuth Resource Helper</title>

<seriesInfo name="Internet-Draft" value="draft-vandermeulen-oauth-resource-helper-00"/>

<author fullname="Pieter van der Meulen" initials="P.G.M." surname="van der Meulen">
<organization>SURF</organization>
<address>
<postal>
<street>Moreelsepark 48</street>
<code>3511 EP</code>
<city>Utrecht</city>
<country>NL</country>
</postal>
<email>[email protected]</email>
</address>
</author>

<author fullname="Michiel de Jong" initials="M.B." surname="de Jong">
<organization>Ponder Source</organization>
<address>
<email>[email protected]</email>
</address>
</author>

<date year="2024"/>

<area>General</area>
<workgroup>Internet Engineering Task Force</workgroup>

<keyword>OAuth</keyword>
<keyword>Resource Helper</keyword>

<abstract>
<t>
A Resource Helper can replace the scope-picking and scope-displaying capabilities of an OAuth Authorization Server.
This makes the software architecture of the Authorization Server more modular,
and can alleviate organisational challenges when the API of a Resource Server evolves.
The Resource Helper still needs to adapt in lock-step with API changes,
but the rest of the Authorization Server can be managed on a more stable software deployment cycle.
The Resource Helper provides two endpoints: a "view" endpoint that can display access scopes in detail,
and a "pick" endpoint for selecting them.
Some optional additional interactions are also discussed.
</t>
</abstract>

</front>

<middle>

<section>
<name>Introduction</name>
<t>
The Authorization Server may redirect the Resource Owner to the Resource Helper's View or Pick endpoint,
as part of the authorization flow.
Optionally, the Resource Helper may submit the selected access scope to a resource registry,
and refer to it by an identifier rather than by a self-contained description.
From the Revocation interface,
the Authorization Server may also redirect the Resource Owner to the Resource Helper's View endpoint,
to allow them to view the details of previously granted access,
and help the Resource Owner decide whether a given token should be revoked or not.
</t>
<t>
During the Authorization Code Flow as described in<xref target="I-D.ietf-oauth-v2-1"/>,
the authorization server authenticates the resource owner (via the user agent)
and establishes whether the resource owner grants or denies the client's access request.
For the authorization server to meaningfully measure if the resource owner wants to grant or deny the request,
it needs to display, presumably via the user agent,
the details of the access token scope in a way that the resource owner will understand.
</t>
<t>
Displaying access token scope details via the user agent may involve describing specific resources and actions,
in a human-readable, probably locale-dependent, and possibly even persona-dependent way.
When the API of the Resource Server changes, the method of displaying access token scope details may also need to change.
For instance, if a feature is added that allows the end user to add a photo to an event in a calendar,
then the description of an "events:654234:write" access token scope may need to change from
"edit the date and title of 'Birthday Bash'" to "upload photos and edit details of 'Birthday Bash'",
and it may make sense to display the event's primary photo,
so the resource owner can better understand the access token scope they are granting,
leading to a more informed decision and thus better security.
</t>

<section>
<name>Requirements Language</name>
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT
RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in BCP 14
<xref target="RFC2119"/>
<xref target="RFC8174"/>
when, and only when, they appear in
all capitals, as shown here.
</t>
</section>
</section>

<section>
<name>Viewing Access Token Scopes</name>
<t>
The view endpoint of the resource helper is a web page the authorization server can link to,
which is specialized in displaying an access token scope for the resource owner to understand.
It SHOULD take 'scope', 'actions', 'redirect_uri', and optionally 'state' as its parameters.
The 'action' parameter SHOULD be a space-delimited list of valid actions,
as agreed between Authorization Server and Resource Helper,
for instance 'grant reject' for use from an authorization endpoint,
or 'revoke cancel' for use in a revocation interface.
Example:
</t>
<t>
https://view.example.org/?scope=events:654234:write&amp;action=grant%20reject&amp;redirect_uri=https%3A%2F%2Fexample.org%2Fcontinue&amp;state=xyz
</t>
<t>
The view endpoint will allow the resource owner to grant/reject, after which they will be redirected back.
The scope and state parameters will be copied, and the 'action' parameter will be replaced by the applicable choice,
for instance:
</t>
<t>
https://example.org/continue?scope=events:654234:write&amp;action=grant&amp;state=xyz
</t>
</section>

<section>
<name>Picking Access Token Scopes</name>
<t>
The issued access token scope may be different from the one requested by the client,
based on the authorization server policy or the resource owner's instructions.
To allow the resource owner to instruct the authorization server to grant a smaller, larger,
or different access token scope than what the client requested,
especially in the case where the client only specified the requested scope in generic terms, or not at all,
the requirements for viewing access token scopes need to be augmented with a requirement to allow the user to select,
deselect, and browse specific aspects of it.
</t>
<t>
In some use cases, a client may generically ask for access to "a photo" or "a folder",
without specifying a specific one,
and the resource owner may have a chance to browse through a photo collection or a folder tree to select a specific one.
Here too, each time the functionalities of the resource server change,
the resource browser interface may also need to change.
</t>
<t>
The pick endpoint of the resource helper takes the same parameters as the view endpoint,
but SHOULD allow the user to influence the details of the scope.
Example:
</t>
<t>
https://pick.example.org/?scope=webdav-folder&amp;action=grant%20reject&amp;redirect_uri=https%3A%2F%2Fexample.org%2Fcontinue&amp;state=xyz
</t>
<t>
After allowing the user to pick a fine-grained access scope, they might be redirected back to the main
authorization server with for instance:
</t>
<t>
https://example.org/continue?scope=/home/john/pictures/4:write&amp;action=grant&amp;state=xyz
</t>
</section>

<section>
<name>Resource registry and scope templates</name>
<t>
In the previous section the scope '/home/john/pictures/4:write' was used as an example of a scope that may be picked.
This scope may fit into a template,
for instance "&lt;file_path&gt;:&lt;read | write&gt;".
In simple cases,
the scope MAY come from a finite list which both the Authorization Server and the Resource Helper are configured with.
The string could also be parseable as JSON or some other syntax.
Alternatively, the resource helper could register a resource set dynamically,
as described in section 3.4 of<xref target="I-D.ietf-gnap-resource-servers"/>,
or as described in section 3.2 of
<xref target="UMA-Fed-Authz"/>
and respond with just an identifier for it.
</t>
<t>
Similarly, the scope parameter in the URI of the view and pick endpoint MAY be an element from a finite list,
a string that fits a template or some other semantics, or take the form of an identifier,
to be dereferenced with a query to some form of resource registry.
</t>
<t>
With a Resource Helper in play, there are four places where a scope parameter might be specified:
from client to Authorization Server, from Authorization Server to Resource Helper,
from Resource Helper back to Authorization Server, and from Authorization Server back to the client.
The scopes that exist between client and Authorization Server may (partially)
match those that exist between Authorization Server and Resource Helper, but they don't have to.
After all, the scopes used between client and Authorization Server may be hard-coded into the software,
and cumbersome to evolve.
</t>
<t>
When a scope is approved or minted in the resource helper,
some interaction may be necessary to later make the resource server correctly understand the access scope of the access token,
at the time of API access.
For instance, the resource helper may insert an entry in the policy registry of the resource server,
and ask the authorization server to insert a reference to
that into the token, or into the introspect response.
</t>
</section>

<section>
<name>Human-readable label</name>
<t>
Even though the detailed view of an access scope can only be provided by the resource helper,
it is still useful if the authorisation server can at least display a string label.
In particular, when the authorisation server displays the final confirmation dialog,
to grant the viewed or picked scope to the client in question,
it could display this label in much the same way as it will likely display some label for the client's identity there.
Also, when displaying a list of currently valid tokens, with the option to revoke,
it would be cumbersome for the user to click 'view' on each of them,
and displaying a list of one-line labels would be more convenient there.
</t>
<t>
This label could be produced programmatically by the resource helper, or hand-picked by the resource owner.
In case a resource registry is used, it MAY be added there as a custom field.
If no resource registry is used, it MAY also be added as an additional response parameter in the front channel.
[TODO: is that secure?]
</t>
</section>

<section>
<name>Resource Server Access</name>
<t>
When the client attempts to access a given resource using a given access token,
the resource server needs to take a decision.
It needs to accept or reject the resource request,
based on the full details of the access token scope that was selected at the resource helper.
This information needs to reach it somehow, either through access token payload or through token introspection.
</t>
<t>
Note that
<xref target="I-D.ietf-gnap-resource-servers"/>
already defines a mechanism where some custom data could be included in a resource registration,
for inclusion in the introspection response.
Similar mechanisms could be used to allow the resource helper to include data in the token payload.
</t>
<t>
The resource helper might also share state with the resource server
that helps the resource server to understand the scope of the access tokens issued by the authorisation server.
</t>
</section>

<section>
<name>Decoupled authentication</name>
<t>
Before redirecting to the resource helper,
the authorization server may already have taken some measures to authenticate the user in the current user agent session.
The resource helper is, however, responsible for its own authentication measures.
In many cases this can however rely on the same sign-in mechanisms,
and not require any additional clicks from the user.
</t>
<t>
The resource helper is responsible for making sure the authenticated user
is allowed to delegate the scope they select.
The response coming back from the resource helper should thus be interpreted as a
decision made by the resource owner as identified by the resource helper,
which may be different from the one authenticated to the main authorization server.
</t>
<t>
This decoupling is by design, and will allow for scenarios where the resource helper refers to a
different set of user identifiers than the authorization server.
For instance, the resource server may be self-hosted by the resource owner,
with the resource owner authenticating as 'admin', whereas the authorization server may be hosted by a university,
with the resource owner authenticating with their student number.
</t>
<t>
The authorization server is trusting the resource helper to select the access token scope to be granted,
and the resource helper is subsequently trusting the authorization server to select the client that will receive this access.
In a way, the resource helper is granting access to the resource, and the authorization server is delegating,
or forwarding this grant, binding it to a particular client.
</t>
</section>

<section>
<name>Where Are You Going?</name>
<t>
In Research and Education it is common for authentication flows to involve a "Where Are You From?" page,
where the end user can select their identity provider from for instance a list of thousands of universities,
grouped per country.
</t>
<t>
Similarly, if a client is able to interact with multiple resource servers,
the authorization server might display a "Where Are You Going?" page
before redirecting the end user to the view or pick endpoint of the resource helper
that corresponds to the resource server of their choice.
</t>
<t>
The Authorization Server should then somehow let the client know which resource server was picked,
but the mechanism for this is not in scope for this document.
</t>
</section>

<section anchor="IANA">
<name>IANA Considerations</name>
<t>This memo includes no request to IANA.</t>
</section>

<section anchor="Security">
<name>Security Considerations</name>
<t>
It is important to understand the value of the redirect back from resource helper to authorization server.
It already contains an access grant as a half-product,
for the authorization server to finalize by actually issuing it to a client.
</t>
<t>
This model differs from the Lodging Intent pattern used in<xref target="FAPI-CIBA"/>,
where the intent is only a description of some intended transaction,
directly between client and resource server,
which does not imply that it was composed by an authenticated resource owner.
</t>
<t>
It's up to the Authorization Server and the Resource Helper
to share their understanding of the various values of 'action'.
</t>
<t>
The Authorization Server should be careful not to redirect the user to the wrong URL,
put a nonce in the state parameter and check that when accepting the callback redirect,
and to always use https.
</t>
<t>
The Resource Helper should not display any information that the currently authenticated user is not allowed to see,
even if it is instructed to display them through the scope parameter that comes from the Authorization Server.
</t>
<t>
The Resource Helper should only grant access to resources for which the currently authenticated user is a resource owner.
The resulting access token scope should always be a subset (attenuation) of the Resource Owner's own access scope.
</t>
<t>
The scope coming back from the Resource Helper should not need to be interpreted in the context of a specific user.
For instance, a scope 'my-billing-details:read' means different things for different resource owners.
To avoid confusion, especially in the light of decoupled authentication (see above),
use a globally unambiguous scope identifier such as 'user-123:billing-detals:read'.
</t>
</section>
</middle>

<back>
<references>
<name>References</name>
<references>
<name>Normative References</name>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/>
<xi:include href="https://datatracker.ietf.org/doc/bibxml3/draft-ietf-oauth-v2-1-11.xml"/>
</references>

<references>
<name>Informative References</name>
<xi:include href="https://datatracker.ietf.org/doc/bibxml3/draft-ietf-gnap-resource-servers-05.xml"/>
<reference anchor="UMA-Fed-Authz"
target="https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-federated-authz-2.0.html">
<front>
<title>UMA Federated Authorization</title>
<author initials="E." surname="Maler">
<organization/>
</author>
<date year="2018"/>
</front>
</reference>

<reference anchor="FAPI-CIBA"
target="https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html">
<front>
<title>UMA Federated Authorization</title>
<author initials="G." surname="Fernandez">
<organization/>
</author>
<date year="2021"/>
</front>
</reference>
</references>
</references>
</back>
</rfc>

0 comments on commit a49dce2

Please sign in to comment.