Skip to content

Commit

Permalink
Merge pull request #87 from SURFnet/choices-endpoint
Browse files Browse the repository at this point in the history 
choice endpoint
  • Loading branch information
@michielbdejong
michielbdejong authored Jul 5, 2024
2 parents 7b5fa22 + 64a05a3 commit 05c6c13
Showing 1 changed file with 106 additions and 118 deletions.
224 changes: 106 additions & 118 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 @@ -80,7 +80,8 @@
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>
</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
Expand Down Expand Up @@ -117,10 +118,13 @@
+---|------|-+
| | | | +---------------+
| | .-+----------------------------------->| Resource |
| | | '-------(4)-- User views scope ----->| Helper |
| | | .------(5)-- Redirect back to AS --<| |
| | | '-------(4)-- User picks scope ----->| Helper |
| | | .------(6)-- Redirect back to AS --<| |
| | | | | +---------------+
| | | | |
| | | | | |
| | | | | (5) Submit
| | | | | | Choice
| | | | | v
| | | | | +---------------+
| | | '---------------------------------->| |
| | | | | |
Expand All @@ -133,44 +137,59 @@
| | User- | | Authorization |
| | Agent | | Server |
| | | | |
| | .--------(6)-- Authorization Code ---<| |
| | .--------(7)-- Authorization Code ---<| |
+-|-- --|---+ +---------------+
| | ^ v
| | | |
^ v | |
+---------+ | |
| |>---(7)-- Authorization Code ---------' |
| |>---(8)-- Authorization Code ---------' |
| Client | & Redirect URI |
| | |
| |<---(8)----- Access Token -------------------'
| |<---(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.
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 revokation interface.
The state parameter here SHOULD be a nonce that is bound to the resource helper.
Example:
</t><t>
</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>
<t>
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&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, especially in the case
Expand All @@ -188,53 +207,7 @@
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.
Note the additional step (5) in which the Resource Helper calls the Resource Registration Endpoint of the Authorization Server.
</t>
<artwork type="ascii-art">
<![CDATA[
+-------------+
| Resource |
| Owner |
+-------------+
^ ^
| |
| |
+---|------|-+
| | | | +---------------+
| | .-+----------------------------------->| Resource |
| | | '-------(4)-- User picks scope ----->| Helper |
| | | .------(6)-- Redirect back to AS --<| |
| | | | | +---------------+
| | | | | |
| | | | | (5) Register
| | | | | | Resource
| | | | | 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 pick endpoint of the resource helper takes the same parameters as the view endpoint,
Expand All @@ -245,48 +218,88 @@
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 registration endpoint and scope templates</name>
<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 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>
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,
</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 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 registration endpoint.
</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 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>
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 @@ -299,32 +312,22 @@
</t>
<t>
This label could be produced programmatically by the resource helper, or hand-picked by the resource owner.
In case a resource registration endpoint is used, it MAY be added
there as a custom field. If no resource registration endpoint 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>
</section>
<section>
<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 into a resource registration,
for inclusion in the introspection response.
Similar mechanisms could be used to allow the resource helper to include data into 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 @@ -353,21 +356,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 05c6c13

Please sign in to comment.