diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index b943dbc..0000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "deno.enable": true -} \ No newline at end of file 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 cbe8d62..f692aab 100644 --- a/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml +++ b/phase-3/spec/draft-vandermeulen-oauth-resource-helper-00.xml @@ -55,14 +55,14 @@ - A Resource Helper can replace the scope-picking and scope-displaying capabilities of an OAuth Authorization Server. + A Resource Helper can replace the scope-picking 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. + The Resource Helper provides one front channel endpoint: a "pick" endpoint for selecting access scopes in detail. + The Authorization exposes a "choice" endpoint where the Resource Helper can submit the Resource Owner's choice, + an optional "subject_info" endpoint and a redirect end point for the front channel. @@ -73,33 +73,22 @@
Introduction - The Authorization Server may redirect the Resource Owner to the Resource Helper's View or Pick endpoint, + The Authorization Server may redirect the Resource Owner to the Resource Helper's Pick endpoint, as part of the authorization flow. - Optionally, the Resource Helper may submit the selected access scope to a resource registration endpoint, - and refer to it by an identifier rather than by a self-contained description. - From the Revocation interface, - the Authorization Server may also redirect the Resource Owner to the Resource Helper's View endpoint, - 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, + 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. + and establishes whether the resource owner (partially) 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. + in a human-viewable, probably locale-dependent, and possibly even persona-dependent way, possibly using a combination + of text, images, and layout. The Resource Helper can specialise in this task, leaving the Authorization Server more + generic and stable.
@@ -117,125 +106,127 @@
- Viewing Access Token Scopes + Generic Flow - During the Authorization Code Flow, the Authorization Server can redirect the - user to the Resource Helper to view the access token scope before continuing. + [sequence diagram etc] - + | Resource | - | | | '-------(4)-- User picks scope ----->| Helper | - | | | .------(6)-- Redirect back to AS --<| | - | | | | | +---------------+ - | | | | | | - | | | | | (5) Submit - | | | | | | Choice - | | | | | v - | | | | | +---------------+ - | | | '---------------------------------->| | - | | | | | | - | | '---------(3)-- Redirect to RH -------<| | - | | | | | - | | | Client Identifier | | - | .-+--------------(1)-- & Redirect URI ------->| | - | | | | | | - | | '--------------(2)-- User authenticates --->| | - | | User- | | Authorization | - | | Agent | | Server | - | | | | | - | | .--------(7)-- Authorization Code ---<| | - +-|-- --|---+ +---------------+ - | | ^ v - | | | | - ^ v | | - +---------+ | | - | |>---(8)-- Authorization Code ---------' | - | Client | & Redirect URI | - | | | - | |<---(9)----- Access Token -------------------' - +---------+ (w/ Optional Refresh Token) - + ┌──────┐ ┌─────────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ + │Client│ │Authorization Server (AS)│ │Resource Helper (RH)│ │Resource Server (RS)│ + └───┬──┘ └────────────┬────────────┘ └──────────┬─────────┘ └──────────┬─────────┘ + │1. Start OAuth 2.0 authorization code flow │ │ │ + │──────────────────────────────────────────>│ │ │ + │ │ │ │ + │ │ 2. [Nonce] Start Resource helper Sub-flow │ │ + │ │──────────────────────────────────────────────────────────────────────────────────────>│ │ + │ │ │ │ + │ │ 3. [Nonce] Get user information (optional) │ │ + │ │<──────────────────────────────────────────────────────────────────────────────────────│ │ + │ │ │ │ + │ │ 4. [Nonce] Return user information (optional) │ │ + │ │──────────────────────────────────────────────────────────────────────────────────────>│ │ + │ │ │ │ + │ │ ┌─────────────────────────────────────────────────────┐ │ + │ │ │User select scopes and RS access token custom info │ │ + │ │ └─────────────────────────────────────────────────────┘ │ + │ │5. [Nonce, token info] Send scope, RS constom JSON for in access token and token label │ │ + │ │<──────────────────────────────────────────────────────────────────────────────────────│ │ + │ │ │ │ + │ │ 6. [Nonce, Result] Redirect to AS │ │ + │ │<──────────────────────────────────────────────────────────────────────────────────────│ │ + │ │ │ │ + │7. OAuth 2.0 Redirect to client with code │ │ │ + │<──────────────────────────────────────────│ │ │ + │ │ │ │ + │ 7. OAuth 2.0 Token request │ │ │ + │──────────────────────────────────────────>│ │ │ + │ │ │ │ + │ 8. Token response │ │ │ + │<──────────────────────────────────────────│ │ │ + │ │ │ │ + │ │ 9. Resource access request │ │ + │───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────>│ + │ │ │ │ + │ │ 10. OAuth 2.0 Token introspection request │ │ + │ │<───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────│ + │ │ │ │ + │ │ 11. OAuth 2.0 Token introspection response │ │ + │ │───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────>│ + │ │ │ │ + │ │ 12. Resource access response │ │ + │<───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────│ + ┌───┴──┐ ┌────────────┴────────────┐ ┌──────────┴─────────┐ ┌──────────┴─────────┐ + │Client│ │Authorization Server (AS)│ │Resource Helper (RH)│ │Resource Server (RS)│ + └──────┘ └─────────────────────────┘ └────────────────────┘ └────────────────────┘ ]]> - - 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, - and recording a user choice in its context. - It SHOULD take 'actions', 'redirect_uri', 'state' and optionally 'scope' as its parameters. - The 'action' parameter SHOULD be a space-delimited list of valid actions, - as agreed between Authorization Server and Resource Helper, - for instance 'grant reject' for use from an authorization endpoint, - or 'revoke cancel' for use in a revocation interface. - The state parameter here SHOULD be a nonce that is bound to the resource helper. - Example: - - - https://view.example.org/?scope=events:654234:write&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fcontinue&state=xyz - - - The view endpoint will allow the resource owner to grant/reject, - and this answer is submitted to the authorization server through the back channel. - - - POST /choice - Content-Type: application/json +
- { - "action": "grant", - "state": "xyz" - } - - - After this back channel call completes the user will be redirected back in the front channel. - The authorization should check that the state parameter matches the nonce it had included in the initial redirect, - and that an answer was received through the back channel. - +
+ Resource Helper Registry - https://example.org/continue&state=xyz + The Authorization Server SHOULD maintain a registry of Resource Helpers it trusts, + with for each Resource Helper: + * a fully qualified domain name (for `/.well-known/resource-helper` lookup, see below) + * client credentials
- Picking Access Token Scopes - - The authorization server may grant an access token scope which is different from the one requested by the client, - based on the authorization server policy or the resource owner's instructions. - To allow the resource owner to instruct the authorization server to grant a smaller, larger, - or different access token scope than what the client requested, - especially in the case 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. - + Resource Helper Well-Known Endpoint - The redirect to the pick endpoint can be embedded in the authorization code flow similarly to the view endpoint. - The Authorization Server can redirect the - user to the Resource Helper to pick the access token scope before continuing. - + At the `/.well-known/resource-helper` end point, the Resource Helper lists the URI for + the `pick` endpoint (front channel). + +
+
+ Resource Helper Configuration + + The Resource Helper needs to store: + * its client credentials + * the `choice` endpoint URL of the Auhtorization Server (back channel) + * the `redirect_uri` endpoint URL of the Authorization Server (front channel) + * (optional) the `subject_info` endpoint URL of the Authorization Server (back channel) + +
+ +
+ Resource Helper Pick endpoint + + The Authorization can redirect the end user to the Resource Helper's Pick endpoint, with in the query paramaters: + + + + Example: https://resource-helper.example.com/pick?nonce=12345678&scope=read. + +
+ +
+ Subject Info Lookup - 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: + The Resource Helper can optionally make a HTTP call to the Subject Info endpoint of the Authorization Server, + with the nonce from the pick request in the query parameter to obtain more information about the end user. + Alternatively, the Resource Helper could skip this step and instead take its own end user authentication measures. + Example: +GET https://authorization-server.example.com/subject-info?nonce=12345678 + +{ + "username": "polly123@surf.nl" +} + +
+ +
+ Picking Access Token Scopes - https://pick.example.org/?scope=webdav-folder&action=grant%20reject&redirect_uri=https%3A%2F%2Fexample.org%2Fcontinue&state=xyz + The authorization server may grant an access token scope which may be different from the one requested by the client, + based on the authorization server policy and the resource owner's instructions. After allowing the user to pick a fine-grained access scope, the resulting choice submission would include a scope field: @@ -245,55 +236,17 @@ Content-Type: application/json { - "action": "grant", - "state": "xyz", - "scope": "/home/john/pictures/4:write" + "nonce": "12345678", + "scope": "/home/john/pictures/4:write", + "payload": (opaque), + "introspect": (opaque), + "label": "Write access to John's picture 4" }
- Resource registration endpoint and scope templates - - With a Resource Helper in play, there are four places where a scope parameter might be specified: - from client to Authorization Server, from Authorization Server to Resource Helper, - from Resource Helper to the Authorization Server's choice endpoint, and from Authorization Server back to client. - The scopes that exist between client and Authorization Server may (partially) - match those that exist between Authorization Server and Resource Helper, but they don't have to. - After all, the scopes used between client and Authorization Server may be hard-coded into the software, - and cumbersome to evolve. - - - In the previous section the scope '/home/john/pictures/4:write' was used as an example - of a scope that may be picked. This scope may fit into a template, - 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. - - - When more flexibility is required, the "scope" parameter of the Choice endpoint could also - refer to a dynamically registered resource set, - and in some situations a resource helper may first call the resource registration endpoint, - as described in section 3.4 of , - or as described in section 3.2 of , - and then refer to the freshly minted resource set by using its resource_reference - in the "scope" parameter of its - subsequent call to the Choice endpoint. - -
-
- Interaction between Resource Helper and Resource Server - - When a scope is approved or minted in the resource helper, some interaction may be necessary to - later make the resource server correctly understand the access scope of the - access token, at the time of API access. For instance, the resource helper may insert an entry in - 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. - -
-
- Additional information in the call to the Choice endpoint + The Choice endpoint The authorization server MAY receive additional types of information from the resource helper through the Choice endpoint. Here is a non-normative example: @@ -351,34 +304,13 @@
- Decoupled authentication + Redirect back to the Authorization Server - 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. - + [...] + + + Example: https://authorization-server.example.com/callback?nonce=12345678&scope=read&result=ok. +