Skip to content

Commit

Permalink
Merge pull request #88 from SURFnet/changes-since-last-week
Browse files Browse the repository at this point in the history 
Changes since #82
  • Loading branch information
@pmeulen
pmeulen authored Nov 4, 2024
2 parents a49dce2 + 8664e27 commit 3b92935
Showing 1 changed file with 147 additions and 73 deletions.
220 changes: 147 additions & 73 deletions phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@
<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,
Optionally, the Resource Helper may submit the selected access scope to a resource registration endpoint,
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,
Expand Down Expand Up @@ -118,33 +118,97 @@

<section>
<name>Viewing Access Token Scopes</name>
<t>
During the Authorization Code Flow, the Authorization Server can redirect the
user to the Resource Helper to view the access token scope before continuing.
</t>
<artwork type="ascii-art">
<![CDATA[
+-------------+
| Resource |
| Owner |
+-------------+
^ ^
| |
| |
+---|------|-+
| | | | +---------------+
| | .-+----------------------------------->| Resource |
| | | '-------(4)-- User picks scope ----->| Helper |
| | | .------(6)-- Redirect back to AS --<| |
| | | | | +---------------+
| | | | | |
| | | | | (5) Submit
| | | | | | Choice
| | | | | v
| | | | | +---------------+
| | | '---------------------------------->| |
| | | | | |
| | '---------(3)-- Redirect to RH -------<| |
| | | | |
| | | Client Identifier | |
| .-+--------------(1)-- & Redirect URI ------->| |
| | | | | |
| | '--------------(2)-- User authenticates --->| |
| | User- | | Authorization |
| | Agent | | Server |
| | | | |
| | .--------(7)-- Authorization Code ---<| |
+-|-- --|---+ +---------------+
| | ^ v
| | | |
^ v | |
+---------+ | |
| |>---(8)-- Authorization Code ---------' |
| Client | & Redirect URI |
| | |
| |<---(9)----- Access Token -------------------'
+---------+ (w/ Optional Refresh Token)
]]>
</artwork>
<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.
which is specialized in displaying an access token scope for the resource owner to understand,
and recording a user choice in its context.
It SHOULD take 'actions', 'redirect_uri', 'state' and optionally 'scope' 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.
The state parameter here SHOULD be a nonce that is bound to the resource helper.
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:
The view endpoint will allow the resource owner to grant/reject,
and this answer is submitted to the authorization server through the back channel.
</t>
<t>
POST /choice
Content-Type: application/json

{
"action": "grant",
"state": "xyz"
}
</t>
<t>
After this back channel call completes the user will be redirected back in the front channel.
The authorization should check that the state parameter matches the nonce it had included in the initial redirect,
and that an answer was received through the back channel.
</t>
<t>
https://example.org/continue?scope=events:654234:write&amp;action=grant&amp;state=xyz
https://example.org/continue&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,
The authorization server may grant an access token scope which is 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,
Expand All @@ -159,6 +223,12 @@
Here too, each time the functionalities of the resource server change,
the resource browser interface may also need to change.
</t>
<t>
The redirect to the pick endpoint can be embedded in the authorization code flow similarly to the view endpoint.
The Authorization Server can redirect the
user to the Resource Helper to pick the access token scope before continuing.
</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.
Expand All @@ -168,54 +238,87 @@
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:
After allowing the user to pick a fine-grained access scope, the resulting choice submission would include a scope field:
</t>
<t>
https://example.org/continue?scope=/home/john/pictures/4:write&amp;action=grant&amp;state=xyz
POST /choice
Content-Type: application/json

{
"action": "grant",
"state": "xyz",
"scope": "/home/john/pictures/4:write"
}
</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>
<name>Resource registration endpoint and scope templates</name>
<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.
from Resource Helper to the Authorization Server's choice endpoint, and from Authorization Server back to 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
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.
</t>
<t>
When more flexibility is required, the "scope" parameter of the Choice endpoint could also
refer to a dynamically registered resource set,
and in some situations a resource helper may first call the resource registration endpoint,
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 then refer to the freshly minted resource set by using its resource_reference
in the "scope" parameter of its
subsequent call to the Choice endpoint.
</t>
</section>
<section>
<name>Interaction between Resource Helper and Resource Server</name>
<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>Additional information in the call to the Choice endpoint</name>
<t>
The authorization server MAY receive additional types of information from the resource helper through the Choice endpoint.
Here is a non-normative example:
</t>
<t>
POST /choice
Content-Type: application/json

{
"action": "grant",
"state": "xyz",
"scope": "/home/john/pictures/4:write",
"label": {
"en-US": "John's picture number 4 (write access)"
},
"payload": {
"user": "john"
},
"introspect": {
"path": "storage-5:~pictures/4",
"modes": "rwx"
},
}
</t>
<section>
<name>Human-readable label</name>
<t>
Even though the detailed view of an access scope can only be provided by the resource helper,
Expand All @@ -229,32 +332,22 @@
</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>
<name>Introspect and token payload options</name>
<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.
To make it easier for existing resource servers to start accepting access tokens issued by the authorization server,
some custom arrangements may be included in the resource helper's software, that interacts well with the resource server's
existing processes and policies.
To facilitate this, the authorization server MAY allow the resource helper to specify opaque data to be included in the access token payload
and in the token introspect response.
</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>

<section>
Expand Down Expand Up @@ -288,25 +381,6 @@
</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>
Expand Down

0 comments on commit 3b92935

Please sign in to comment.