From d3888c62ce822e6efcfa4b3d3b1b574a0f08964f Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 18 Jun 2024 08:46:32 +0200 Subject: [PATCH 01/24] Rebase draft work from dev branch --- ...ft-rfcxml-general-template-standard-00.xml | 252 ++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 phase-3/spec/draft-rfcxml-general-template-standard-00.xml diff --git a/phase-3/spec/draft-rfcxml-general-template-standard-00.xml b/phase-3/spec/draft-rfcxml-general-template-standard-00.xml new file mode 100644 index 0000000..340c0bd --- /dev/null +++ b/phase-3/spec/draft-rfcxml-general-template-standard-00.xml @@ -0,0 +1,252 @@ + + + + + + + + + + + +]> + + + + + + + Title [REPLACE] + + + + + + + + + + Organization [REPLACE/DELETE] +
+ + + Street [REPLACE/DELETE] + City [REPLACE/DELETE] + Region [REPLACE/DELETE] + Postal code [REPLACE/DELETE] + Country [REPLACE/DELETE] + + + Phone [REPLACE/DELETE] + Email [REPLACE/DELETE] + + URI [REPLACE/DELETE] +
+ + + + + + General + Internet Engineering Task Force + + + keyword + + + + Abstract [REPLACE] + + + + + + +
+ Introduction + Introductory text [REPLACE] + +
+ Requirements Language + 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 + when, and only when, they appear in + all capitals, as shown here. +
+ + +
+ +
+ Body [REPLACE] + Body text [REPLACE] + +
    +
  1. Ordered list item [REPLACE/DELETE]
    2. +
+ +
    +
  • Bulleted list item [REPLACE/DELETE]
    • +
+ +
+ +
First term: [REPLACE/DELETE]
+
Definition of the first term [REPLACE/DELETE]
+
Second term: [REPLACE/DELETE]
+
Definition of the second term [REPLACE/DELETE]
+
+ + + + + + + + + +
Column 1 [REPLACE]
Cell [REPLACE]
+ +
+ Source [REPLACE] + + + + +
+ +
+ Diagram [REPLACE] + + + + + + + + + +
+
+ +
+ + IANA Considerations + This memo includes no request to IANA. [CHECK] +
+ +
+ + Security Considerations + This document should not affect the security of the Internet. [CHECK] +
+ + + + + + + References + + Normative References + + + + + + + + + Informative References + + + + + Title [REPLACE] + + + + + + + + + + + + Title [REPLACE] + + Organization [REPLACE] + + + + + + + + + +
+ Appendix 1 [REPLACE/DELETE] + This becomes an Appendix [REPLACE] +
+ +
+ + Acknowledgements + This template uses extracts from templates written by Pekka Savola, Elwyn Davies and + Henrik Levkowetz. [REPLACE] +
+ +
+ + Contributors + Thanks to all of the contributors. [REPLACE] + +
+ + + From a8e5c2ff4c6d6f6ab7fc8da69cc241e9a01d46e8 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 18 Jun 2024 08:53:19 +0200 Subject: [PATCH 02/24] IETF-ID name, ref https://authors.ietf.org/en/naming-your-internet-draft --- ...ard-00.xml => draft-vandermeulen-oauth-resource-helper-00.xml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename phase-3/spec/{draft-rfcxml-general-template-standard-00.xml => draft-vandermeulen-oauth-resource-helper-00.xml} (100%) diff --git a/phase-3/spec/draft-rfcxml-general-template-standard-00.xml b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml similarity index 100% rename from phase-3/spec/draft-rfcxml-general-template-standard-00.xml rename to phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml From fa82e48718b726a0be8a1278ae51a2656b88e18c Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 18 Jun 2024 10:37:52 +0200 Subject: [PATCH 03/24] draft a bit of text --- ...-vandermeulen-oauth-resource-helper-00.xml | 181 +++++++----------- 1 file changed, 66 insertions(+), 115 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 340c0bd..653764e 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -1,18 +1,6 @@ - - - - - + + @@ -20,79 +8,60 @@ ]> - - - Title [REPLACE] - + OAuth Resource Helper - - - - - - - - Organization [REPLACE/DELETE] + + + + SURF
- - Street [REPLACE/DELETE] - City [REPLACE/DELETE] - Region [REPLACE/DELETE] - Postal code [REPLACE/DELETE] - Country [REPLACE/DELETE] - + Moreelsepark 48 + 3511 EP + Utrecht + NL - Phone [REPLACE/DELETE] - Email [REPLACE/DELETE] - - URI [REPLACE/DELETE] + pieter.vandermeulen@surf.nl +
+ + + + Ponder Source +
+ michiel@unhosted.org
- - + General Internet Engineering Task Force - - keyword - + OAuth + Resource Helper - Abstract [REPLACE] + + 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 evolve. Only the Resource Helper needs to adapt in lock-step with API changes, + and the rest of the Authorization Server can be managed on a more stable software deployment cycle. + The Resource Helper provides two endpoints: a "pick" endpoint for the selection of access scopes, and a "view" endpoint + for viewing them. + @@ -101,7 +70,40 @@
Introduction - Introductory text [REPLACE] + In Research and education (R&E), we see new standards evolving (e.g. in AARC https://aarc-project.eu) that address the use-cases that + are particularly relevant in that environment, and that are not addressed by existing OAuth standards. This is linked to a move away from + authentication mechanisms like passwords, SSH keys and X.509 certificates towards token based authentication. In R&E, we see that the + organisations in control of the various resource servers and clients work together in communities. These communities run an authorization + server and manage trust and authorization policies. In this context we see that the authorization server does not have detailed knowledge + of the resources and access modes that a resource server can offer, and thus is not well-placed to present a scope selection GUI that goes + beyond using a generic description of the scope. This is a problem for use-cases where more fine-grained control over the level of access + is required. E.g. granting access to a specific folder on a storage server, or granting access to a specific computing resource and that + cannot be solved by establishing a list of generic scopes. Another usecase that we want to address is where there are several resource servers + that offer a similar service using the same protocol, e.g. storage servers that offer WebDAV access to files. In this case, the user should be + able to choose the resource server that they want to access, and the client should not have to know about the resource servers in advance. We + aim for a solution that does not require changes to existing resources servers, and that will work with existing OAuth clients. We expect that + our solution will be of interest to other communities that have similar requirements, where the authorization server and resource server are + developed by different entities. + + We considered using the Lodging Intent Pattern, a "pre-dance" where the client first obtains a structured scope before initiating the main OAuth dance, + but we rejected this approach because it creates an undesirable many-to-many relationship between clients and the specific resource servers. Instead, + we want to hide the resource server behind the authorization server which acts as a trusted broker between the various clients of various the organisations + and the various resource servers of various (other) organisations. + + We therefore want to propose an OAuth extension which adds a "scope picker" service close to each resource server, to which the authorization server + redirects the user in a "sub-dance", leaving the GUI of the authorization server generic and easy to maintain. This works as follows: using the standard + authorization code flow, the client redirects the user to the authorization server. The client can request a specific resource server by including an + audience, or it can use a scope to request a specific type of service (e.g. WebDAV). The authorization server then redirects the user to a well-known + endpoint on the resource server's scope picker service based on the client's and user's preferences and applies any restrictions based on the communities' + policy. The scope picker shows a GUI in which the user can select e.g. a folder and set the level from the ones they have access to and set the level of + access (read, write) and builds a structured scope from this information. This structured scope is given a human-readable name, either suggested by the + scope picker or chosen by the user. The scope picker then redirects the user back to the authorization server including all the scope information, which + is then able to display the human-readable description in its GUI, even though the authorization server doesn't understand what it stands for. Optionally + protocol specific information (e.g. the WebDAV URL to use) is returned to the authorization server, this is required because the client may not have + knowledge about the resource server that the user selected. When the user then 'grants access' on the authorization server, the OAuth authorization code + flow is continued back to the client as normal. The client can then use its access token to request the protocol specific information from the authorization + server using a well-known endpoint on the authorization server and use it to access the resource server. +
Requirements Language @@ -117,59 +119,8 @@
- Body [REPLACE] + Pick endpoint Body text [REPLACE] - -
    -
  1. Ordered list item [REPLACE/DELETE]
    2. -
- -
    -
  • Bulleted list item [REPLACE/DELETE]
    • -
- -
- -
First term: [REPLACE/DELETE]
-
Definition of the first term [REPLACE/DELETE]
-
Second term: [REPLACE/DELETE]
-
Definition of the second term [REPLACE/DELETE]
-
- - - - - - - - - -
Column 1 [REPLACE]
Cell [REPLACE]
- -
- Source [REPLACE] - - - - -
- -
- Diagram [REPLACE] - - - - - - - - - -
From 42f11b6615bcdfc0aa97a7b6ee6ad38c7d1f7d77 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 18 Jun 2024 10:39:25 +0200 Subject: [PATCH 04/24] & --- phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 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 653764e..268477c 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -70,9 +70,9 @@
Introduction - In Research and education (R&E), we see new standards evolving (e.g. in AARC https://aarc-project.eu) that address the use-cases that + In Research and education (R&E), we see new standards evolving (e.g. in AARC https://aarc-project.eu) that address the use-cases that are particularly relevant in that environment, and that are not addressed by existing OAuth standards. This is linked to a move away from - authentication mechanisms like passwords, SSH keys and X.509 certificates towards token based authentication. In R&E, we see that the + authentication mechanisms like passwords, SSH keys and X.509 certificates towards token based authentication. In R&E, we see that the organisations in control of the various resource servers and clients work together in communities. These communities run an authorization server and manage trust and authorization policies. In this context we see that the authorization server does not have detailed knowledge of the resources and access modes that a resource server can offer, and thus is not well-placed to present a scope selection GUI that goes From 10073fcfd2862a22ec35b4a0482a8027c71104a6 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 18 Jun 2024 12:20:02 +0200 Subject: [PATCH 05/24] drafting most of the sections --- ...-vandermeulen-oauth-resource-helper-00.xml | 138 ++++++++++-------- 1 file changed, 79 insertions(+), 59 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 268477c..3abcdd9 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -57,7 +57,7 @@ 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 evolve. Only the Resource Helper needs to adapt in lock-step with API changes, + when the API of a Resource Server evolves. Only the Resource Helper needs to adapt in lock-step with API changes, and the rest of the Authorization Server can be managed on a more stable software deployment cycle. The Resource Helper provides two endpoints: a "pick" endpoint for the selection of access scopes, and a "view" endpoint for viewing them. @@ -118,24 +118,94 @@
+
+ Requirements for Viewing Access Token Scopes + 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 + grants or denies 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. And 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'" may need to change 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. + + Requirements for Picking Access Token Scopes + 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. + + 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. + +
+ +
+ View endpoint + 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 takes a 'scope' parameter, an 'actions' parameter and optional 'redirect_uri' and 'state' parameters. + The 'action' parameter should list valid actions, for instance 'grant reject' for use from an authorization endpoint, or 'revoke cancel' for use in a revokation interface. + Example: + https://view.example.org/?scope=events:654234:write&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fauthorize&state=xyz + + The view endpoint will allow the resource owner to grant/reject, or revoke/cancel, 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: + https://example.org/authorize?scope=events:654234:write&action=grant&state=xyz + +
+
Pick endpoint - Body text [REPLACE] + The pick endpoint of the resource helper takes the same parameters as the view endpoint, but allows the user to influence the details of the scope. + Example: + https://pick.example.org/?scope=webdav-folder&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fauthorize&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: + https://example.org/authorize?scope=/home/john/pictures/4:write&action=grant&state=xyz + +
+ +
+ Resource registry and scope templates + + 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 "<file_path>:<read | write>". + Alternatively, the resource helper could register a resource set as described in , or as described in
- + +
+ Decoupled authentication + + Before redirecting to the resource helper, the authorization server may already have taken some measures to authenticate the user of 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. + + 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 person from the one authenticated to the main authorization server. + + 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. + + 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, to the client. + +
+
- IANA Considerations - This memo includes no request to IANA. [CHECK] + This memo includes no request to IANA.
- Security Considerations - This document should not affect the security of the Internet. [CHECK] + 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. + + This model differs from the Lodging Intent pattern used in , where the intent is only a description of some intended transaction, directly between client and resource server. +
- - @@ -143,61 +213,11 @@ References Normative References - - - - - Informative References - - - - - Title [REPLACE] - - - - - - - - - - - - Title [REPLACE] - - Organization [REPLACE] - - - - - - - -
- Appendix 1 [REPLACE/DELETE] - This becomes an Appendix [REPLACE] -
- -
- - Acknowledgements - This template uses extracts from templates written by Pekka Savola, Elwyn Davies and - Henrik Levkowetz. [REPLACE] -
- -
- - Contributors - Thanks to all of the contributors. [REPLACE] - -
- From a288846dc1448751c411a28a8bd14cdcd6edcd15 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 18 Jun 2024 12:40:28 +0200 Subject: [PATCH 06/24] rewrite introduction, add WAYG, merge some sections --- ...-vandermeulen-oauth-resource-helper-00.xml | 84 +++++++------------ 1 file changed, 30 insertions(+), 54 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 3abcdd9..c63f014 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -70,39 +70,11 @@
Introduction - In Research and education (R&E), we see new standards evolving (e.g. in AARC https://aarc-project.eu) that address the use-cases that - are particularly relevant in that environment, and that are not addressed by existing OAuth standards. This is linked to a move away from - authentication mechanisms like passwords, SSH keys and X.509 certificates towards token based authentication. In R&E, we see that the - organisations in control of the various resource servers and clients work together in communities. These communities run an authorization - server and manage trust and authorization policies. In this context we see that the authorization server does not have detailed knowledge - of the resources and access modes that a resource server can offer, and thus is not well-placed to present a scope selection GUI that goes - beyond using a generic description of the scope. This is a problem for use-cases where more fine-grained control over the level of access - is required. E.g. granting access to a specific folder on a storage server, or granting access to a specific computing resource and that - cannot be solved by establishing a list of generic scopes. Another usecase that we want to address is where there are several resource servers - that offer a similar service using the same protocol, e.g. storage servers that offer WebDAV access to files. In this case, the user should be - able to choose the resource server that they want to access, and the client should not have to know about the resource servers in advance. We - aim for a solution that does not require changes to existing resources servers, and that will work with existing OAuth clients. We expect that - our solution will be of interest to other communities that have similar requirements, where the authorization server and resource server are - developed by different entities. - - We considered using the Lodging Intent Pattern, a "pre-dance" where the client first obtains a structured scope before initiating the main OAuth dance, - but we rejected this approach because it creates an undesirable many-to-many relationship between clients and the specific resource servers. Instead, - we want to hide the resource server behind the authorization server which acts as a trusted broker between the various clients of various the organisations - and the various resource servers of various (other) organisations. - - We therefore want to propose an OAuth extension which adds a "scope picker" service close to each resource server, to which the authorization server - redirects the user in a "sub-dance", leaving the GUI of the authorization server generic and easy to maintain. This works as follows: using the standard - authorization code flow, the client redirects the user to the authorization server. The client can request a specific resource server by including an - audience, or it can use a scope to request a specific type of service (e.g. WebDAV). The authorization server then redirects the user to a well-known - endpoint on the resource server's scope picker service based on the client's and user's preferences and applies any restrictions based on the communities' - policy. The scope picker shows a GUI in which the user can select e.g. a folder and set the level from the ones they have access to and set the level of - access (read, write) and builds a structured scope from this information. This structured scope is given a human-readable name, either suggested by the - scope picker or chosen by the user. The scope picker then redirects the user back to the authorization server including all the scope information, which - is then able to display the human-readable description in its GUI, even though the authorization server doesn't understand what it stands for. Optionally - protocol specific information (e.g. the WebDAV URL to use) is returned to the authorization server, this is required because the client may not have - knowledge about the resource server that the user selected. When the user then 'grants access' on the authorization server, the OAuth authorization code - flow is continued back to the client as normal. The client can then use its access token to request the protocol specific information from the authorization - server using a well-known endpoint on the authorization server and use it to access the resource server. + + The Authorization Server may redirect the Resource Owner to the Resource Helper's View or Pick endpoint, as part of the authorization request. + Optionally, the Pick endpoint 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 Revokation 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 it should be revoked or not.
@@ -119,7 +91,7 @@
- Requirements for Viewing Access Token Scopes + Viewing Access Token Scopes 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 grants or denies 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. @@ -130,20 +102,7 @@ "edit the date and title of 'Birthday Bash'" may need to change 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. - Requirements for Picking Access Token Scopes - 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. - - 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. - -
- -
- View endpoint - 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. + 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 takes a 'scope' parameter, an 'actions' parameter and optional 'redirect_uri' and 'state' parameters. The 'action' parameter should list valid actions, for instance 'grant reject' for use from an authorization endpoint, or 'revoke cancel' for use in a revokation interface. Example: @@ -153,11 +112,17 @@ will be replaced by the applicable choice, for instance: https://example.org/authorize?scope=events:654234:write&action=grant&state=xyz -
-
- Pick endpoint - The pick endpoint of the resource helper takes the same parameters as the view endpoint, but allows the user to influence the details of the scope. + Picking Access Token Scopes + 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. + + 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. + + The pick endpoint of the resource helper takes the same parameters as the view endpoint, but allows the user to influence the details of the scope. Example: https://pick.example.org/?scope=webdav-folder&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fauthorize&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: @@ -192,7 +157,17 @@ 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, to the client.
- + +
+ Where Are You Going? + + In R&E 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. + +
+
IANA Considerations This memo includes no request to IANA. @@ -203,7 +178,8 @@ 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. - This model differs from the Lodging Intent pattern used in , where the intent is only a description of some intended transaction, directly between client and resource server. + This model differs from the Lodging Intent pattern used in , 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.
From ae0a9792cde42ac17d7fb0a2ebcd5917468fc200 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 18 Jun 2024 12:45:31 +0200 Subject: [PATCH 07/24] remove trailing whitespace --- ...-vandermeulen-oauth-resource-helper-00.xml | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 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 c63f014..2484362 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -33,18 +33,18 @@ 3511 EP Utrecht NL - + pieter.vandermeulen@surf.nl - + Ponder Source
michiel@unhosted.org
- + General @@ -63,11 +63,11 @@ for viewing them. - + - +
Introduction @@ -76,7 +76,7 @@ From the Revokation 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 it should be revoked or not. - +
Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", @@ -89,7 +89,7 @@
- +
Viewing Access Token Scopes During the Authorization Code Flow as described in , the authorization server authenticates the resource owner (via the user agent) @@ -138,7 +138,7 @@ Similarly, the scope parameter in the URI of the view and pick endpoint may already take the form of an identifier, to be dereferenced with a query to a resource registry of some sort. -
+
Decoupled authentication @@ -156,7 +156,7 @@ 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, to the client. -
+
Where Are You Going? @@ -166,18 +166,18 @@ 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. -
+
IANA Considerations This memo includes no request to IANA.
- +
Security Considerations 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. - + This model differs from the Lodging Intent pattern used in , 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. @@ -190,7 +190,7 @@ Normative References - + Informative References From b3d7983cdc0c86a711b268f3e642af60d26cc8c5 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 18 Jun 2024 13:01:42 +0200 Subject: [PATCH 08/24] https://author-tools.ietf.org/api/export/6fdd99d8-feee-4e69-90b0-679e91123655/draft-vandermeulen-oauth-resource-helper-00.html --- ...-vandermeulen-oauth-resource-helper-00.xml | 32 ++++++++++++++++--- 1 file changed, 28 insertions(+), 4 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 2484362..a8fd0b1 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -86,13 +86,11 @@ when, and only when, they appear in all capitals, as shown here.
- -
Viewing Access Token Scopes - During the Authorization Code Flow as described in , the authorization server authenticates the resource owner (via the user agent) + 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 grants or denies 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. @@ -112,7 +110,9 @@ will be replaced by the applicable choice, for instance: https://example.org/authorize?scope=events:654234:write&action=grant&state=xyz +
+
Picking Access Token Scopes 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 @@ -134,7 +134,7 @@ Resource registry and scope templates 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 "<file_path>:<read | write>". - Alternatively, the resource helper could register a resource set as described in , or as described in , or as described in and respond with just the identifier. Similarly, the scope parameter in the URI of the view and pick endpoint may already take the form of an identifier, to be dereferenced with a query to a resource registry of some sort. @@ -189,10 +189,34 @@ References Normative References + + + Informative References + + + + UMA Federated Authorization + + + + + + + + + UMA Federated Authorization + + + + + + + + From 2e523b91a9a1b93ff04cd1d4b96a1f1049c44d54 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 18 Jun 2024 13:26:57 +0200 Subject: [PATCH 09/24] https://author-tools.ietf.org/api/export/f289457e-f2a5-4a93-8f8c-2b3d6efe24ec/draft-vandermeulen-oauth-resource-helper-00.html --- ...-vandermeulen-oauth-resource-helper-00.xml | 49 +++++++++++-------- 1 file changed, 28 insertions(+), 21 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 a8fd0b1..c26f70c 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -57,10 +57,10 @@ 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. Only the Resource Helper needs to adapt in lock-step with API changes, - and the rest of the Authorization Server can be managed on a more stable software deployment cycle. - The Resource Helper provides two endpoints: a "pick" endpoint for the selection of access scopes, and a "view" endpoint - for viewing them. + 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 for that can display access scopes in detail, and a "pick" endpoint + for selecting them. @@ -93,20 +93,20 @@ 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 grants or denies 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. And 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 + 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'" may need to change to "upload photos and edit details of 'Birthday Bash'", and it may make sense to display the event's primary photo, + "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. - + 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 takes a 'scope' parameter, an 'actions' parameter and optional 'redirect_uri' and 'state' parameters. - The 'action' parameter should list valid actions, for instance 'grant reject' for use from an authorization endpoint, or 'revoke cancel' for use in a revokation interface. + The 'action' parameter should be a space-delimited list of valid actions, for instance 'grant reject' for use from an authorization endpoint, or 'revoke cancel' for use in a revokation interface. Example: https://view.example.org/?scope=events:654234:write&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fauthorize&state=xyz - - The view endpoint will allow the resource owner to grant/reject, or revoke/cancel, after which they will be redirected back. The scope and state parameters will be copied, and the 'action' parameter + + 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: https://example.org/authorize?scope=events:654234:write&action=grant&state=xyz @@ -118,14 +118,17 @@ 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. - + 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. - + The pick endpoint of the resource helper takes the same parameters as the view endpoint, but allows the user to influence the details of the scope. Example: + https://pick.example.org/?scope=webdav-folder&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fauthorize&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: + https://example.org/authorize?scope=/home/john/pictures/4:write&action=grant&state=xyz
@@ -134,9 +137,12 @@ Resource registry and scope templates 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 "<file_path>:<read | write>". - Alternatively, the resource helper could register a resource set as described in , or as described in and respond with just the identifier. - - Similarly, the scope parameter in the URI of the view and pick endpoint may already take the form of an identifier, to be dereferenced with a query to a resource registry of some sort. + 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 , or as described in 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 registry. @@ -145,14 +151,14 @@ Before redirecting to the resource helper, the authorization server may already have taken some measures to authenticate the user of 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. - + 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 person from the one authenticated to the main authorization server. - + 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. - + 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, to the client. @@ -161,8 +167,8 @@
Where Are You Going? - In R&E 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. - + In Research and Education (R&E) 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. @@ -177,6 +183,7 @@ Security Considerations 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. + This model differs from the Lodging Intent pattern used in , 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. From 8f2239326a7bc854564369ae823e51330cbf5e35 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 18 Jun 2024 13:38:02 +0200 Subject: [PATCH 10/24] Some more security considerations off the top of my head --- .../spec/draft-vandermeulen-oauth-resource-helper-00.xml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) 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 c26f70c..2706280 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -104,10 +104,12 @@ It takes a 'scope' parameter, an 'actions' parameter and optional 'redirect_uri' and 'state' parameters. The 'action' parameter should be a space-delimited list of valid actions, for instance 'grant reject' for use from an authorization endpoint, or 'revoke cancel' for use in a revokation interface. Example: + https://view.example.org/?scope=events:654234:write&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fauthorize&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: + https://example.org/authorize?scope=events:654234:write&action=grant&state=xyz
@@ -184,9 +186,12 @@ 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. - This model differs from the Lodging Intent pattern used in , 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. + + It's up to the Authorization Server and the Resource Helper to share their understanding of the various values of 'action'. + + 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. From e2e0fbc35186ae17675b7d3e467eed2e62fd3b0b Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 18 Jun 2024 13:43:14 +0200 Subject: [PATCH 11/24] careful: only show things the currently logged-in user is authorised to view, ref #72 --- phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml | 3 +++ 1 file changed, 3 insertions(+) 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 2706280..ada51e9 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -193,6 +193,9 @@ 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. + + The Resource Helper should not display any information that the currently authenticated user is allowed to see, even if it is instructed to display them through the scope parameter that comes from the Authorization Server. + From 65f9399f19884de37108463bf22e507758354fa5 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 18 Jun 2024 13:46:00 +0200 Subject: [PATCH 12/24] don't give access to 'my billing', ref #72 --- phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml | 4 ++++ 1 file changed, 4 insertions(+) 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 ada51e9..45216d9 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -196,6 +196,10 @@ The Resource Helper should not display any information that the currently authenticated user is allowed to see, even if it is instructed to display them through the scope parameter that comes from the Authorization Server. + + 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, use a globally unambiguous scope identifier, such as 'user-123:billing-detals:read'. + From db2aad6436c199f8b213a2e1abee55f2562fa7c6 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Fri, 21 Jun 2024 16:33:56 +0200 Subject: [PATCH 13/24] Mention #76 but leave it out of scope --- phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml | 2 ++ 1 file changed, 2 insertions(+) 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 45216d9..c86eabe 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -173,6 +173,8 @@ 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 authorization server was picked, but the mechanism for this is not in scope for this document. From f15f30d7c0d2db20102d013ebf6aaca6fed86c2b Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Fri, 21 Jun 2024 16:34:28 +0200 Subject: [PATCH 14/24] oops --- phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 c86eabe..bfd4599 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -174,7 +174,7 @@ 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 authorization server was picked, but the mechanism for this is not in scope for this document. + 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. From e0d1c1244ad13e7a52905b2e5ed1758c3be52b45 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Fri, 21 Jun 2024 16:37:21 +0200 Subject: [PATCH 15/24] Resolve #77 --- phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml | 3 +++ 1 file changed, 3 insertions(+) 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 bfd4599..4604d23 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -145,6 +145,9 @@ 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. + + With a Resource Helper in play, there are four places where a scope parameter might be specified: from client to AS, from AS to RH, from RH back to AS, and from AS back to client. + The scopes that exist between client and AS may (partially) match those that exist between AS and RH, but they don't have to. From 873918f621afd0d8bebbb3ca9005b57d1383c014 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Fri, 21 Jun 2024 17:05:42 +0200 Subject: [PATCH 16/24] Fix #79 --- ...-vandermeulen-oauth-resource-helper-00.xml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) 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 4604d23..357733e 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -148,6 +148,25 @@ With a Resource Helper in play, there are four places where a scope parameter might be specified: from client to AS, from AS to RH, from RH back to AS, and from AS back to client. The scopes that exist between client and AS may (partially) match those that exist between AS and RH, but they don't have to. + + 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. 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. + + + +
+ Access Decision + + A resource server needs to take an access decision based on the full details of the scope that was selected at the resource helper. This information needs to reach it + somehow, either through access token payload or through token introspection. + + + Note that already defines such a mechanism, where the resource helper could provide some custom data to be included + into the introspection response. Similar mechanisms could be used to allow the resource helper to include data into the token payload. + + + The resource helper might also share state with the resource server that helps the resource server to understand the access tokens issued by the authorisation server.
From f32c7f67adec142a9abbdafcffb33b152895e507 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Fri, 21 Jun 2024 17:13:08 +0200 Subject: [PATCH 17/24] Fix #78 --- ...draft-vandermeulen-oauth-resource-helper-00.xml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) 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 357733e..cfea0a4 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -155,6 +155,20 @@ +
+ Human-readable label + + 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 the client label there. Also, when displaying a list of currently valid tokens, with 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. + + + 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 could be added + there as a custom field. If no resource registry is used, it could also be added as an additional response parameter in the front channel. [TODO: is that secure?] + +
+
Access Decision From 0165101d619b34e4aee29c7d2ed18729e30b424d Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Mon, 24 Jun 2024 08:56:20 +0200 Subject: [PATCH 18/24] small edits in introduction --- .../draft-vandermeulen-oauth-resource-helper-00.xml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 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 cfea0a4..f85fb97 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -60,7 +60,7 @@ 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 for that can display access scopes in detail, and a "pick" endpoint - for selecting them. + for selecting them. Some optional additional interactions are also discussed. @@ -71,10 +71,10 @@
Introduction - The Authorization Server may redirect the Resource Owner to the Resource Helper's View or Pick endpoint, as part of the authorization request. - Optionally, the Pick endpoint may submit the selected access scope to a resource registry, and refer to it by an identifier rather than by a self-contained description. + 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 Revokation 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 it should be revoked or not. + of previously granted access, and help the Resource Owner decide whether a given token should be revoked or not.
@@ -91,8 +91,8 @@
Viewing Access Token Scopes 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 - grants or denies 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. + 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 From ec01333237069e53e6cbc86c031ace6be13b54f2 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Mon, 24 Jun 2024 09:12:29 +0200 Subject: [PATCH 19/24] small edits and adding linebreaks --- ...-vandermeulen-oauth-resource-helper-00.xml | 156 ++++++++++++------ 1 file changed, 101 insertions(+), 55 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 f85fb97..cf8a147 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -75,6 +75,17 @@ 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 Revokation 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. + + + 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 + "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.
@@ -90,67 +101,78 @@
Viewing Access Token Scopes - 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 - "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. - - 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 takes a 'scope' parameter, an 'actions' parameter and optional 'redirect_uri' and 'state' parameters. - The 'action' parameter should be a space-delimited list of valid actions, for instance 'grant reject' for use from an authorization endpoint, or 'revoke cancel' for use in a revokation interface. + + 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 takes '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 revokation interface. Example: - https://view.example.org/?scope=events:654234:write&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fauthorize&state=xyz + 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 + 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: - https://example.org/authorize?scope=events:654234:write&action=grant&state=xyz + https://example.org/continue?scope=events:654234:write&action=grant&state=xyz
Picking Access Token Scopes - 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 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. - 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. + 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. - The pick endpoint of the resource helper takes the same parameters as the view endpoint, but allows the user to influence the details of the scope. + The pick endpoint of the resource helper takes the same parameters as the view endpoint, + but allows the user to influence the details of the scope. Example: - https://pick.example.org/?scope=webdav-folder&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fauthorize&state=xyz + 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: - https://example.org/authorize?scope=/home/john/pictures/4:write&action=grant&state=xyz + https://example.org/continue?scope=/home/john/pictures/4:write&action=grant&state=xyz
Resource registry and scope templates - 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 "<file_path>:<read | write>". - In simple cases the scope may come from a finite list which both the Authorization Server and the Resource Helper are configured with. + 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 "<file_path>:<read | write>". + 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 , or as described in and respond with just an identifier for it. + Alternatively, the resource helper could register a resource set dynamically, + as described in , + or as described in 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, + 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. - With a Resource Helper in play, there are four places where a scope parameter might be specified: from client to AS, from AS to RH, from RH back to AS, and from AS back to client. + With a Resource Helper in play, there are four places where a scope parameter might be specified: + from client to AS, from AS to RH, from RH back to AS, and from AS back to client. The scopes that exist between client and AS may (partially) match those that exist between AS and RH, but they don't have to. - 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. 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 + 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. 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.
@@ -158,59 +180,78 @@
Human-readable label - 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 the client label there. Also, when displaying a list of currently valid tokens, with option to revoke, it would be + 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 the client label there. + Also, when displaying a list of currently valid tokens, with 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. - 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 could be added - there as a custom field. If no resource registry is used, it could also be added as an additional response parameter in the front channel. [TODO: is that secure?] + 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 could be added + there as a custom field. If no resource registry is used, it could also be added as an additional + response parameter in the front channel. [TODO: is that secure?]
Access Decision - A resource server needs to take an access decision based on the full details of the scope that was selected at the resource helper. This information needs to reach it + A resource server needs to take an access decision based on the full details of the scope that was + selected at the resource helper. This information needs to reach it somehow, either through access token payload or through token introspection. - Note that already defines such a mechanism, where the resource helper could provide some custom data to be included + Note that already defines such a mechanism, + where the resource helper could provide some custom data to be included into the introspection response. Similar mechanisms could be used to allow the resource helper to include data into the token payload. - The resource helper might also share state with the resource server that helps the resource server to understand the access tokens issued by the authorisation server. + The resource helper might also share state with the resource server that helps the resource + server to understand the access tokens issued by the authorisation server.
Decoupled authentication - Before redirecting to the resource helper, the authorization server may already have taken some measures to authenticate the user of 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. + Before redirecting to the resource helper, the authorization server may already have taken some + measures to authenticate the user of 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. - 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 person from the one authenticated to the main authorization server. + 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 + person from the one authenticated to the main authorization server. - 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 + 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. - 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, to the client. + 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, to the client.
Where Are You Going? - In Research and Education (R&E) 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. + In Research and Education (R&E) 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 + 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. + 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.
@@ -221,21 +262,26 @@
Security Considerations - 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 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. - This model differs from the Lodging Intent pattern used in , where the intent is only a description of some intended transaction, directly between client and resource server, which does not imply that + This model differs from the Lodging Intent pattern used in , 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. It's up to the Authorization Server and the Resource Helper to share their understanding of the various values of 'action'. - 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. + 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. - The Resource Helper should not display any information that the currently authenticated user is allowed to see, even if it is instructed to display them through the scope parameter that comes from the Authorization Server. + The Resource Helper should not display any information that the currently authenticated user is allowed to see, + even if it is instructed to display them through the scope parameter that comes from the Authorization Server. - 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 + 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, use a globally unambiguous scope identifier, such as 'user-123:billing-detals:read'.
From 55dac0a749a68d8c0f0b4ffcc90475ce0526216f Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Mon, 24 Jun 2024 09:22:28 +0200 Subject: [PATCH 20/24] small edits --- ...t-vandermeulen-oauth-resource-helper-00.xml | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 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 cf8a147..2f46319 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -157,8 +157,8 @@ 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 , - or as described in and respond with just an identifier for it. + 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 @@ -166,13 +166,17 @@ to be dereferenced with a query to some form of resource registry. With a Resource Helper in play, there are four places where a scope parameter might be specified: - from client to AS, from AS to RH, from RH back to AS, and from AS back to client. - The scopes that exist between client and AS may (partially) match those that exist between AS and RH, but they don't have to. + 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. 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. 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 + 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.
@@ -184,7 +188,7 @@ 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 the client label there. + 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 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. From 442ec624eeaa96fc94ec5a17fd34d852c415329b Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Mon, 24 Jun 2024 09:43:43 +0200 Subject: [PATCH 21/24] security considerations --- ...-vandermeulen-oauth-resource-helper-00.xml | 33 ++++++++++++------- 1 file changed, 21 insertions(+), 12 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 2f46319..f80bc36 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -201,20 +201,24 @@
- Access Decision + Resource Server Access - A resource server needs to take an access decision based on the full details of the scope that was + 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. - Note that already defines such a mechanism, - where the resource helper could provide some custom data to be included - into the introspection response. Similar mechanisms could be used to allow the resource helper to include data into the token payload. + 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. The resource helper might also share state with the resource server that helps the resource - server to understand the access tokens issued by the authorisation server. + server to understand the scope of the access tokens issued by the authorisation server.
@@ -222,14 +226,14 @@ Decoupled authentication Before redirecting to the resource helper, the authorization server may already have taken some - measures to authenticate the user of the current user agent session. + 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. 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 - person from the one authenticated to the main authorization server. + from the one authenticated to the main authorization server. 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 @@ -240,14 +244,14 @@ 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, to the client. + server is delegating, or forwarding this grant, binding it to a particular client.
Where Are You Going? - In Research and Education (R&E) it is common for authentication flows to involve a "Where Are You From?" page, + 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 @@ -280,13 +284,18 @@ parameter and check that when accepting the callback redirect, and to always use https. - The Resource Helper should not display any information that the currently authenticated user is allowed to see, + 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. + 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. + + 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, use a globally unambiguous scope identifier, such as 'user-123:billing-detals:read'. + confusion, especially in the light of decoupled authentication (see above), use a globally unambiguous scope + identifier such as 'user-123:billing-detals:read'.
From b774330f8b3a03d9ef6ab8e37a85230b520ff653 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Mon, 24 Jun 2024 09:48:32 +0200 Subject: [PATCH 22/24] nits --- ...t-vandermeulen-oauth-resource-helper-00.xml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 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 f80bc36..f669393 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -75,8 +75,8 @@ 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 Revokation 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. - + 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. @@ -101,11 +101,11 @@
Viewing Access Token Scopes - + 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 takes '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, + 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 revokation interface. Example: @@ -136,7 +136,7 @@ functionalities of the resource server change, the resource browser interface may also need to change. The pick endpoint of the resource helper takes the same parameters as the view endpoint, - but allows the user to influence the details of the scope. + but SHOULD allow the user to influence the details of the scope. Example: https://pick.example.org/?scope=webdav-folder&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fcontinue&state=xyz @@ -153,14 +153,14 @@ 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 "<file_path>:<read | write>". - In simple cases the scope may come from a finite list which both the Authorization Server + 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 , 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 + 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. @@ -194,8 +194,8 @@ 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 could be added - there as a custom field. If no resource registry is used, it could also be added as an additional + 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?]
From 2824b4a417d1f0eb642f46c5273a70a0a87ed68f Mon Sep 17 00:00:00 2001 From: Pieter van der Meulen Date: Mon, 24 Jun 2024 16:48:23 +0200 Subject: [PATCH 23/24] Quick spellcheck --- .../draft-vandermeulen-oauth-resource-helper-00.xml | 10 +++++----- 1 file changed, 5 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 f669393..89c146d 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -25,7 +25,7 @@ - + SURF
@@ -59,7 +59,7 @@ 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 for that can display access scopes in detail, and a "pick" endpoint + 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. @@ -73,7 +73,7 @@ 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 Revokation interface, the Authorization Server may also redirect the Resource Owner to the Resource Helper's View endpoint, to allow them to view the details + 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. @@ -189,7 +189,7 @@ 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 option to revoke, it would be + 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. @@ -212,7 +212,7 @@ Note that already defines a mechanism - where some custom data could be included into a resource registration, + 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 into the token payload. From 2fc2b3f8f92ff58ad447e044da6086b772cdc4ed Mon Sep 17 00:00:00 2001 From: Pieter van der Meulen Date: Mon, 24 Jun 2024 17:32:00 +0200 Subject: [PATCH 24/24] Reformat for easier commenting --- ...-vandermeulen-oauth-resource-helper-00.xml | 398 ++++++++++-------- 1 file changed, 225 insertions(+), 173 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 89c146d..9a9d0f5 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -3,22 +3,22 @@ - - - -]> + + + + + ]> + 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"> OAuth Resource Helper @@ -55,15 +55,17 @@ - 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. + 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. - + @@ -71,21 +73,33 @@
Introduction - 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. + 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. + + + 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. - 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 - "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. + 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.
@@ -93,91 +107,111 @@ 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 - when, and only when, they appear in - all capitals, as shown here. + interpreted as described in BCP 14 + + + when, and only when, they appear in + all capitals, as shown here. +
Viewing Access Token Scopes - 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 revokation interface. - 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: - - https://example.org/continue?scope=events:654234:write&action=grant&state=xyz + 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: + + + 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: + + + https://example.org/continue?scope=events:654234:write&action=grant&state=xyz
Picking Access Token Scopes - 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. - - 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. - - 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: - - 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: - - https://example.org/continue?scope=/home/john/pictures/4:write&action=grant&state=xyz + + 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. + + + 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. + + + 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: + + + 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: + + + https://example.org/continue?scope=/home/john/pictures/4:write&action=grant&state=xyz
Resource registry and scope templates - 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 "<file_path>:<read | write>". - 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 , - 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 registry. - - 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. - - 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. + 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 "<file_path>:<read | write>". + 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, + 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 registry. + + + 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. + + + 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.
@@ -185,18 +219,19 @@ Human-readable label 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. + 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. 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?] + 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?]
@@ -206,60 +241,69 @@ 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. + 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. - Note that already defines a mechanism - where some custom data could be included in a resource registration, + Note that + + 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 into the token payload. + Similar mechanisms could be used to allow the resource helper to include data in the token payload. - 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. + 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.
Decoupled authentication - 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. - - 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. - - 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. - - 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. + 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. + + + 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. + + + 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. + + + 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.
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. + 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.
@@ -270,32 +314,39 @@
Security Considerations - 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. - - This model differs from the Lodging Intent pattern used in , 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. - - It's up to the Authorization Server and the Resource Helper to share their understanding of the various values of 'action'. - - 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. + + 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. + + + This model differs from the Lodging Intent pattern used in, + 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. - 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. + It's up to the Authorization Server and the Resource Helper + to share their understanding of the various values of 'action'. - 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. + 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. - 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'. + 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. + + + 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. + + + 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'.
@@ -313,7 +364,8 @@ Informative References - + UMA Federated Authorization @@ -322,7 +374,9 @@ - + + UMA Federated Authorization @@ -331,9 +385,7 @@ - - - +