From 16af5ed607533915049aea00ecb1ddcbc9bc820f Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 27 Jun 2024 11:19:52 +0200 Subject: [PATCH 1/3] choices endpoint --- ...-vandermeulen-oauth-resource-helper-00.xml | 195 +++++++++--------- 1 file changed, 96 insertions(+), 99 deletions(-) diff --git a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml index 361980c..6ec01c6 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -117,10 +117,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 | | | | | +---------------+ | | | '---------------------------------->| | | | | | | | @@ -133,44 +136,54 @@ | | 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) ]]> - 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: https://view.example.org/?scope=events:654234:write&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fcontinue&state=xyz - 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. + + POST /choice + Content-Type: application/json + + { + "action": "grant", + "state": "xyz" + } + + 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. - https://example.org/continue?scope=events:654234:write&action=grant&state=xyz + https://example.org/continue&state=xyz
Picking Access Token Scopes - 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 @@ -188,53 +201,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. - - | 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) - - ]]> - The pick endpoint of the resource helper takes the same parameters as the view endpoint, @@ -245,15 +212,31 @@ https://pick.example.org/?scope=webdav-folder&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fcontinue&state=xyz - 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: - https://example.org/continue?scope=/home/john/pictures/4:write&action=grant&state=xyz + POST /choice + Content-Type: application/json + + { + "action": "grant", + "state": "xyz", + "scope": "/home/john/pictures/4:write" + }
- resource registration endpoint and scope templates + Resource registration endpoint and scope templates + + 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. + 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, @@ -261,23 +244,21 @@ 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, + + + 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 , - or as described in section 3.2 of and respond with just an identifier for it. - - 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. - - 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. - + or as described in section 3.2 of , + 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. + +
+
+ Interaction between Resource Helper and Resource Server + 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 @@ -285,8 +266,34 @@ that into the token, or into the introspect response.
-
+ Additional information in the call to the Choice endpoint + + The authorization server MAY receive additional types of information from the resource helper through the Choice endpoint. + Here is a non-normative example: + + + 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" + }, + + } + +
Human-readable label Even though the detailed view of an access scope can only be provided by the resource helper, @@ -299,32 +306,22 @@ 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?] - -
- -
- Resource Server Access - - 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. +
+
+ Introspect and token payload options - Note that 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. 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. +
From ab555dc2b409d4418d70c4ec5af40fab62cd392d Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Fri, 28 Jun 2024 11:24:32 +0200 Subject: [PATCH 2/3] Remove WAYG section --- ...raft-vandermeulen-oauth-resource-helper-00.xml | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml index 6ec01c6..5d2a589 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -350,21 +350,6 @@
-
- Where Are You Going? - - 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. - - 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. - - 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. - -
-
IANA Considerations This memo includes no request to IANA. From 64a05a3fc6d1a4302384aaf83dde42a4179782b9 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Fri, 28 Jun 2024 11:27:51 +0200 Subject: [PATCH 3/3] Fix missing XML tag --- ...aft-vandermeulen-oauth-resource-helper-00.xml | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml index 5d2a589..5b62aef 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -80,7 +80,8 @@ During the Authorization Code Flow as described in , 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. - + + 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 @@ -159,11 +160,14 @@ 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: - + + https://view.example.org/?scope=events:654234:write&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fcontinue&state=xyz - + + The view endpoint will allow the resource owner to grant/reject, and this answer is submitted to the authorization server through the back channel. - + + POST /choice Content-Type: application/json @@ -172,10 +176,12 @@ "state": "xyz" } + 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. - + + https://example.org/continue&state=xyz