--- 1/draft-ietf-gnap-core-protocol-00.txt 2020-11-02 08:13:56.817201929 -0800 +++ 2/draft-ietf-gnap-core-protocol-01.txt 2020-11-02 08:13:57.017206953 -0800 @@ -1,86 +1,84 @@ GNAP J. Richer, Ed. Internet-Draft Bespoke Engineering -Intended status: Standards Track 17 October 2020 -Expires: 20 April 2021 +Intended status: Standards Track A. Parecki +Expires: 6 May 2021 Okta + F. Imbault + acert.io + 2 November 2020 Grant Negotiation and Authorization Protocol - draft-ietf-gnap-core-protocol-00 + draft-ietf-gnap-core-protocol-01 Abstract This document defines a mechanism for delegating authorization to a piece of software, and conveying that delegation to the software. This delegation can include access to a set of APIs as well as information passed directly to the software. This document has been prepared by the GNAP working group design team of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones, and Justin Richer. This document is intended as a starting point for the working group and includes decision points for discussion and agreement. Many of the features in this proposed protocol can be accomplished in a number of ways. Where possible, the editor has included notes and discussion from the design team regarding the options as understood. - 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 [RFC2119] [RFC8174] when, and only when, they appear in all - capitals, as shown here. - Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on 20 April 2021. + This Internet-Draft will expire on 6 May 2021. Copyright Notice Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents - 1. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 1.2. Elements . . . . . . . . . . . . . . . . . . . . . . . . 6 - 1.3. Sequences . . . . . . . . . . . . . . . . . . . . . . . . 7 - 1.3.1. Redirect-based Interaction . . . . . . . . . . . . . 10 - 1.3.2. User-code Interaction . . . . . . . . . . . . . . . . 12 - 1.3.3. Asynchronous Authorization . . . . . . . . . . . . . 14 - 1.3.4. Software-only Authorization . . . . . . . . . . . . . 15 - 1.3.5. Refreshing an Expired Access Token . . . . . . . . . 16 + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 + 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 + 1.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 1.3. Elements . . . . . . . . . . . . . . . . . . . . . . . . 7 + 1.4. Sequences . . . . . . . . . . . . . . . . . . . . . . . . 7 + 1.4.1. Redirect-based Interaction . . . . . . . . . . . . . 10 + 1.4.2. User-code Interaction . . . . . . . . . . . . . . . . 12 + 1.4.3. Asynchronous Authorization . . . . . . . . . . . . . 14 + 1.4.4. Software-only Authorization . . . . . . . . . . . . . 16 + 1.4.5. Refreshing an Expired Access Token . . . . . . . . . 16 2. Requesting Access . . . . . . . . . . . . . . . . . . . . . . 17 2.1. Requesting Resources . . . . . . . . . . . . . . . . . . 19 - 2.1.1. Requesting a Single Access Token . . . . . . . . . . 19 + 2.1.1. Requesting a Single Access Token . . . . . . . . . . 20 2.1.2. Requesting Resources By Reference . . . . . . . . . . 21 2.1.3. Requesting Multiple Access Tokens . . . . . . . . . . 23 2.1.4. Signaling Token Behavior . . . . . . . . . . . . . . 25 2.2. Requesting User Information . . . . . . . . . . . . . . . 27 2.3. Identifying the RC . . . . . . . . . . . . . . . . . . . 28 2.3.1. Identifying the RC Instance . . . . . . . . . . . . . 30 2.3.2. Identifying the RC Key . . . . . . . . . . . . . . . 31 2.3.3. Providing Displayable RC Information . . . . . . . . 32 2.3.4. Authenticating the RC . . . . . . . . . . . . . . . . 33 2.4. Identifying the User . . . . . . . . . . . . . . . . . . 33 @@ -127,47 +125,47 @@ 5.3. Modifying an Existing Request . . . . . . . . . . . . . . 69 5.4. Getting the Current State of a Grant Request . . . . . . 74 5.5. Canceling a Grant Request . . . . . . . . . . . . . . . . 75 6. Token Management . . . . . . . . . . . . . . . . . . . . . . 75 6.1. Rotating the Access Token . . . . . . . . . . . . . . . . 76 6.2. Revoking the Access Token . . . . . . . . . . . . . . . . 78 7. Using Access Tokens . . . . . . . . . . . . . . . . . . . . . 79 8. Binding Keys . . . . . . . . . . . . . . . . . . . . . . . . 80 8.1. Detached JWS . . . . . . . . . . . . . . . . . . . . . . 81 8.2. Attached JWS . . . . . . . . . . . . . . . . . . . . . . 84 - 8.3. Mutual TLS . . . . . . . . . . . . . . . . . . . . . . . 86 - 8.4. Demonstration of Proof-of-Possession (DPoP) . . . . . . . 88 - 8.5. HTTP Signing . . . . . . . . . . . . . . . . . . . . . . 89 - 8.6. OAuth Proof of Possession (PoP) . . . . . . . . . . . . . 91 - 9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 92 - 10. Resource Servers . . . . . . . . . . . . . . . . . . . . . . 93 - 10.1. Introspecting a Token . . . . . . . . . . . . . . . . . 94 - 10.2. Deriving a downstream token . . . . . . . . . . . . . . 95 - 10.3. Registering a Resource Handle . . . . . . . . . . . . . 97 - 10.4. Requesting a Resources With Insufficient Access . . . . 98 - 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 98 - 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 99 - 13. Security Considerations . . . . . . . . . . . . . . . . . . . 99 - 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 99 - 15. Normative References . . . . . . . . . . . . . . . . . . . . 99 - Appendix A. Document History . . . . . . . . . . . . . . . . . . 101 + 8.3. Mutual TLS . . . . . . . . . . . . . . . . . . . . . . . 89 + 8.4. Demonstration of Proof-of-Possession (DPoP) . . . . . . . 91 + 8.5. HTTP Signing . . . . . . . . . . . . . . . . . . . . . . 92 + 8.6. OAuth Proof of Possession (PoP) . . . . . . . . . . . . . 93 + 9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 95 + 10. Resource Servers . . . . . . . . . . . . . . . . . . . . . . 96 + 10.1. Introspecting a Token . . . . . . . . . . . . . . . . . 97 + 10.2. Deriving a downstream token . . . . . . . . . . . . . . 98 + 10.3. Registering a Resource Handle . . . . . . . . . . . . . 100 + 10.4. Requesting a Resources With Insufficient Access . . . . 101 + 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 101 + 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 102 + 13. Security Considerations . . . . . . . . . . . . . . . . . . . 102 + 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 102 + 15. Normative References . . . . . . . . . . . . . . . . . . . . 102 + Appendix A. Document History . . . . . . . . . . . . . . . . . . 104 Appendix B. Component Data Models . . . . . . . . . . . . . . . 105 Appendix C. Example Protocol Flows . . . . . . . . . . . . . . . 105 - C.1. Redirect-Based User Interaction . . . . . . . . . . . . . 106 - C.2. Secondary Device Interaction . . . . . . . . . . . . . . 110 - Appendix D. No User Involvement . . . . . . . . . . . . . . . . 113 - D.1. Asynchronous Authorization . . . . . . . . . . . . . . . 114 - D.2. Applying OAuth 2 Scopes and Client IDs . . . . . . . . . 117 - Appendix E. JSON Structures and Polymorphism . . . . . . . . . . 118 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 119 + C.1. Redirect-Based User Interaction . . . . . . . . . . . . . 105 + C.2. Secondary Device Interaction . . . . . . . . . . . . . . 109 + Appendix D. No User Involvement . . . . . . . . . . . . . . . . 112 + D.1. Asynchronous Authorization . . . . . . . . . . . . . . . 113 + D.2. Applying OAuth 2 Scopes and Client IDs . . . . . . . . . 116 + Appendix E. JSON Structures and Polymorphism . . . . . . . . . . 117 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 118 -1. Protocol +1. Introduction This protocol allows a piece of software, the resource client, to request delegated authorization to resource servers and direct information. This delegation is facilitated by an authorization server usually on behalf of a resource owner. The requesting party operating the software may interact with the authorization server to authenticate, provide consent, and authorize the request. The process by which the delegation happens is known as a grant, and the GNAP protocol allows for the negotiation of the grant process @@ -177,21 +175,29 @@ [RFC6749], OpenID Connect [OIDC], and the family of protocols that have grown up around that ecosystem. However, GNAP is not an extension of OAuth 2.0 and is not intended to be directly compatible with OAuth 2.0. GNAP seeks to provide functionality and solve use cases that OAuth 2.0 cannot easily or cleanly address. Even so, GNAP and OAuth 2.0 will exist in parallel for many deployments, and considerations have been taken to facilitate the mapping and transition from legacy systems to GNAP. Some examples of these can be found in Appendix D.2. -1.1. Roles +1.1. Terminology + + 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 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + +1.2. Roles The parties in the GNAP protocol perform actions under different roles. Roles are defined by the actions taken and the expectations leveraged on the role by the overall protocol. Authorization Server (AS) Manages the requested delegations for the RO. The AS issues tokens and directly delegated information to the RC. The AS is defined by its grant endpoint, a single URL that accepts a POST request with a JSON payload. The AS could also have other endpoints, including interaction endpoints and @@ -264,53 +270,53 @@ for different roles and components, including: * Grant Server (for Authorization Server) * Grant Client (for Resource Client) * Operator (for Requesting Party) ]] -1.2. Elements +1.3. Elements In addition to the roles above, the protocol also involves several elements that are acted upon by the roles throughout the process. Access Token A credential representing a set of access rights delegated to the RC. The access token is created by the AS, consumed and verified by the RS, and issued to and carried by the RC. The contents and format of the access token are opaque to the RC. - Grant The process by which a the RC requests and is given delegated + Grant The process by which the RC requests and is given delegated access to the RS by the AS through the authority of the RO. - Key A cryptographic element binding a request to the holder of the - key. Access tokens and RC instances can be associated with - specific keys. + Cryptographic Key A cryptographic element binding a request to a + holder of the key. Access tokens and RC instances can be + associated with specific keys. Resource A protected API served by the RS and accessed by the RC. Access to this resource is delegated by the RO as part of the grant process. Subject Information Information about the RO that is returned directly to the RC from the AS without the RC making a separate call to an RS. Access to this information is delegated by the RO as part of the grant process. [[ Editor's note: What other core elements need an introduction here? These aren't roles to be taken on by different parties, nor are they descriptions of the possible configurations of parties, but these are still important moving parts within the protocol. ]] -1.3. Sequences +1.4. Sequences The GNAP protocol can be used in a variety of ways to allow the core delegation process to take place. Many portions of this process are conditionally present depending on the context of the deployments, and not every step in this overview will happen in all circumstances. Note that a connection between roles in this process does not necessarily indicate that a specific protocol message is sent across the wire between the components fulfilling the roles in question, or that a particular step is required every time. For example, for an @@ -412,21 +418,21 @@ * (12) The RS determines if the new token is sufficient for the request by examining the token, potentially calling the AS (Section 10.1). * (13) The RC disposes of the token (Section 6.2) once the RC has completed its access of the RS and no longer needs the token. The following sections and Appendix C contain specific guidance on how to use the GNAP protocol in different situations and deployments. -1.3.1. Redirect-based Interaction +1.4.1. Redirect-based Interaction In this example flow, the RC is a web application that wants access to resources on behalf of the current user, who acts as both the requesting party (RQ) and the resource owner (RO). Since the RC is capable of directing the user to an arbitrary URL and receiving responses from the user's browser, interaction here is handled through front-channel redirects using the user's browser. The RC uses a persistent session with the user to ensure the same user that is starting the interaction is the user that returns from the interaction. @@ -504,21 +510,21 @@ reference ensuring that the reference is associated with the request being continued. 9. If the request has been authorized, the AS grants access to the information in the form of access tokens (Section 3.2) and direct subject information (Section 3.4) to the RC. An example set of protocol messages for this method can be found in Appendix C.1. -1.3.2. User-code Interaction +1.4.2. User-code Interaction In this example flow, the RC is a device that is capable of presenting a short, human-readable code to the user and directing the user to enter that code at a known URL. The RC is not capable of presenting an arbitrary URL to the user, nor is it capable of accepting incoming HTTP requests from the user's browser. The RC polls the AS while it is waiting for the RO to authorize the request. The user's interaction is assumed to occur on a secondary device. In this example it is assumed that the user is both the RQ and RO, though the user is not assumed to be interacting with the RC through @@ -606,21 +612,21 @@ 11. The RC continues to poll the AS (Section 5.2) with the new continuation information in (9). 12. If the request has been authorized, the AS grants access to the information in the form of access tokens (Section 3.2) and direct subject information (Section 3.4) to the RC. An example set of protocol messages for this method can be found in Appendix C.2. -1.3.3. Asynchronous Authorization +1.4.3. Asynchronous Authorization In this example flow, the RQ and RO roles are fulfilled by different parties, and the RO does not interact with the RC. The AS reaches out asynchronously to the RO during the request process to gather the RO's authorization for the RC's request. The RC polls the AS while it is waiting for the RO to authorize the request. +--------+ +--------+ +------+ | RC | | AS | | RO | | |--(1)--- Request Access --------->| | | | @@ -683,21 +689,21 @@ 8. The RC continues to poll the AS (Section 5.2) with the new continuation information from (7). 9. If the request has been authorized, the AS grants access to the information in the form of access tokens (Section 3.2) and direct subject information (Section 3.4) to the RC. An example set of protocol messages for this method can be found in Appendix D.1. -1.3.4. Software-only Authorization +1.4.4. Software-only Authorization In this example flow, the AS policy allows the RC to make a call on its own behalf, without the need for a RO to be involved at runtime to approve the decision. Since there is no explicit RO, the RC does not interact with an RO. +--------+ +--------+ | RC | | AS | | |--(1)--- Request Access --------->| | | | | | @@ -709,21 +715,21 @@ not send any interactions modes to the server. 2. The AS determines that the request is been authorized, the AS grants access to the information in the form of access tokens (Section 3.2) and direct subject information (Section 3.4) to the RC. An example set of protocol messages for this method can be found in Appendix D. -1.3.5. Refreshing an Expired Access Token +1.4.5. Refreshing an Expired Access Token In this example flow, the RC receives an access token to access a resource server through some valid GNAP process. The RC uses that token at the RS for some time, but eventually the access token expires. The RC then gets a new access token by rotating the expired access token at the AS using the token's management URL. +--------+ +--------+ | RC | | AS | | |--(1)--- Request Access ----------------->| | @@ -1103,22 +1108,22 @@ access token (Section 6.1), the AS does not invalidate the previous access token. The old access token continues to remain valid until such time as it expires or is revoked through other means. split_token The RC is capable of receiving multiple access tokens (Section 3.2.2) in response to any single token request (Section 2.1.1), or receiving a different number of tokens than specified in the multiple token request (Section 2.1.3). The labels of the returned additional tokens are chosen by the AS. - The client MUST be able to tell from the token response where and - how it can use the each access tokens. [[ Editor's note: This + The RC MUST be able to tell from the token response where and how + it can use each of the access tokens. [[ Editor's note: This functionality is controversial at best as it requires significantly more complexity on the client in order to solve one class of AS/RS deployment choices. ]] bind_token The RC wants the issued access token to be bound to the key the RC used (Section 2.3.2) to make the request. The resulting access token MUST be bound using the same "proof" mechanism used by the client with a "key" value of "true", indicating the client's presented key is to be used for binding. [[ Editor's note: should there be a different flag and mechanism @@ -1460,30 +1465,30 @@ identified by this key, such as limiting which resources can be requested and which interaction methods can be used. For example, only specific RCs with certain known keys might be trusted with access tokens without the AS interacting directly with the RO as in Appendix D. The presentation of a key allows the AS to strongly associate multiple successive requests from the same RC with each other. This is true when the AS knows the key ahead of time and can use the key to authenticate the RC software, but also if the key is ephemeral and - created just for this request. As such the AS MAY allow for RCs to - make requests with unknown keys. This pattern allows for ephemeral - RCs, such as single-page applications, and RCs with many individual - instances, such as mobile applications, to generate their own key - pairs and use them within the protocol without having to go through a - separate registration step. The AS MAY limit which capabilities are - made available to RCs with unknown keys. For example, the AS could - have a policy saying that only previously-registered RCs can request - particular resources, or that all RCs with unknown keys have to be - interactively approved by an RO. + created just for this series of requests. As such the AS MAY allow + for RCs to make requests with unknown keys. This pattern allows for + ephemeral RCs, such as single-page applications, and RCs with many + individual instances, such as mobile applications, to generate their + own key pairs and use them within the protocol without having to go + through a separate registration step. The AS MAY limit which + capabilities are made available to RCs with unknown keys. For + example, the AS could have a policy saying that only previously- + registered RCs can request particular resources, or that all RCs with + unknown keys have to be interactively approved by an RO. 2.4. Identifying the User If the RC knows the identity of the RQ through one or more identifiers or assertions, the RC MAY send that information to the AS in the "user" field. The RC MAY pass this information by value or by reference. sub_ids An array of subject identifiers for the RQ, as defined by [I-D.ietf-secevent-subject-identifiers]. @@ -1609,21 +1614,21 @@ "interact": { "redirect": true, "callback": { "method": "redirect", "uri": "https://client.example.net/return/123455", "nonce": "LKLTI25DK82FX4T4QFZC" } } In this non-normative example, the RC is indicating that it can - display a use code (Section 2.5.4) and direct the RQ to an arbitrary + display a user code (Section 2.5.4) and direct the RQ to an arbitrary URL of maximum length (Section 2.5.1.1) 255 characters, but it cannot accept a callback. "interact": { "redirect": 255, "user_code": true } If the RC does not provide a suitable interaction mechanism, the AS cannot contact the RO asynchronously, and the AS determines that @@ -1852,21 +1857,21 @@ "uri": "https://client.example.net/return/123455", "nonce": "LKLTI25DK82FX4T4QFZC" } } Requests to the callback URI MUST be processed by the RC as described in Section 4.4.2. Since the incoming request to the callback URL is from the AS and not from the RO's browser, the RC MUST NOT require the RQ to be present - on incoming HTTP the request. + on the incoming HTTP request. [[ Editor's note: This post-interaction method can be used in advanced use cases like asynchronous authorization, or simply to signal the client that it should move to the next part of the protocol, even when there is no user present at the client. As such it can feel a little odd being inside the "interact" block of the protocol, but it does align with the redirect-based "callback" method and it seems they really should be mutually-exclusive. Additionally, should there be a method for simply pushing the updated response directly to the client, instead? ]] @@ -2067,22 +2072,22 @@ } } 3.1. Request Continuation If the AS determines that the request can be continued with additional requests, it responds with the "continue" field. This field contains a JSON object with the following properties. uri REQUIRED. The URI at which the RC can make continuation - requests. This URI MAY vary request, or MAY be stable at the AS - if the AS includes an access token. The RC MUST use this value + requests. This URI MAY vary per request, or MAY be stable at the + AS if the AS includes an access token. The RC MUST use this value exactly as given when making a continuation request (Section 5). wait RECOMMENDED. The amount of time in integer seconds the RC SHOULD wait after receiving this continuation handle and calling the URI. access_token RECOMMENDED. A unique access token for continuing the request, in the format specified in Section 3.2.1. This access token MUST be bound to the RC's key used in the request and MUST NOT be a "bearer" token. This access token MUST NOT be usable at @@ -2152,21 +2157,21 @@ other protocols without requiring additional encoding. manage OPTIONAL. The management URI for this access token. If provided, the RC MAY manage its access token as described in Section 6. This management URI is a function of the AS and is separate from the RS the RC is requesting access to. This URI MUST NOT include the access token value and SHOULD be different for each access token issued in a request. resources RECOMMENDED. A description of the rights associated with - this access token, as defined in Section 3.2.1. If included, this + this access token, as defined in Section 2.1.1. If included, this MUST reflect the rights associated with the issued access token. These rights MAY vary from what was requested by the RC. expires_in OPTIONAL. The number of seconds in which the access will expire. The RC MUST NOT use the access token past this time. An RS MUST NOT accept an access token past this time. Note that the access token MAY be revoked by the AS or RS at any point prior to its expiration. key REQUIRED. The key that the token is bound to. If the boolean @@ -2449,21 +2454,21 @@ sub_ids An array of subject identifiers for the RO, as defined by [I-D.ietf-secevent-subject-identifiers]. [[ Editor's note: privacy considerations are needed around returning identifiers. ]] assertions An object containing assertions as values keyed on the assertion type defined by a registry TBD (Section 12). [[ Editor's note: should this be an array of objects with internal typing like the sub_ids? Do we expect more than one assertion per user anyway? ]] - updated_at Timestamp in integer seconds indicating when the + updated_at Timestamp as an ISO8610 date string, indicating when the identified account was last updated. The RC MAY use this value to determine if it needs to request updated profile information through an identity API. The definition of such an identity API is out of scope for this specification. "subject": { "sub_ids": [ { "subject_type": "email", "email": "user@example.com", } ], @@ -3774,46 +3779,110 @@ into compact form [RFC7515]. The RC presents the JWS as the body of the request along with a content type of "application/jose". The AS MUST extract the payload of the JWS and treat it as the request body for further processing. POST /tx HTTP/1.1 Host: server.example.com Content-Type: application/jose - eyJiNjQiOmZhbHNlLCJhbGciOiJSUzI1NiIsImtpZCI6Inh5ei0xIn0.ewogICAgIm - NsaWVudCI6IHsKICAgICAgICAibmFtZSI6ICJNeSBDbGllbnQgRGlzcGxheSBOYW1l - IiwKICAgICAgICAidXJpIjogImh0dHBzOi8vZXhhbXBsZS5uZXQvY2xpZW50IgogIC - AgfSwKICAgICJyZXNvdXJjZXMiOiBbCiAgICAgICAgImRvbHBoaW4tbWV0YWRhdGEi - CiAgICBdLAogICAgImludGVyYWN0IjogewogICAgICAgICJyZWRpcmVjdCI6IHRydW - UsCiAgICAgICAgImNhbGxiYWNrIjogewogICAgCQkidXJpIjogImh0dHBzOi8vY2xp - ZW50LmZvbyIsCiAgICAJCSJub25jZSI6ICJWSkxPNkE0Q0FZTEJYSFRSMEtSTyIKIC - AgIAl9CiAgICB9LAogICAgImtleXMiOiB7CgkJInByb29mIjogImp3c2QiLAogICAg - ICAgICJqd2tzIjogewogICAgICAgICAgICAia2V5cyI6IFsKICAgICAgICAgICAgIC - AgIHsKICAgICAgICAgICAgICAgICAgICAia3R5IjogIlJTQSIsCiAgICAgICAgICAg - ICAgICAgICAgImUiOiAiQVFBQiIsCiAgICAgICAgICAgICAgICAgICAgImtpZCI6IC - J4eXotMSIsCiAgICAgICAgICAgICAgICAgICAgImFsZyI6ICJSUzI1NiIsCiAgICAg - ICAgICAgICAgICAgICAgIm4iOiAia09CNXJSNEp2MEdNZUxhWTZfSXRfcjNPUndkZj - hjaV9KdGZmWHlhU3g4eFlKQ0NOYU9LTkpuX096MFloZEhiWFRlV081QW95c3BEV0pi - TjV3XzdiZFdEeGdwRC15NmpuRDF1OVloQk9DV09iTlBGdnBrVE04TEM3U2RYR1JLeD - JrOE1lMnJfR3NzWWx5UnBxdnBCbFk1LWVqQ3l3S1JCZmN0UmNuaFRUR056dGJiREJV - eURTV21GTVZDSGU1bVhUNGNMMEJ3clpDNlMtdXUtTEF4MDZhS3dRT1B3WU9HT3NsSz - hXUG0xeUdka2FBMXVGX0ZwUzZMUzYzV1lQSGlfQXAyQjdfOFdidzR0dHpiTVNfZG9K - dnVEYWdXOEExSXAzZlhGQUh0UkFjS3c3cmRJNF9YbG42NmhKeEZla3BkZldkaVBRZG - RRNlkxY0syVTNvYnZVZzd3IgogICAgICAgICAgICAgICAgfQogICAgICAgICAgICBd - CiAgICAgICAgfQogICAgfQp9.Y287HMtaY0EegEjoTd_04a4GC6qV48GgVbGKOhHdJ - nDtD0VuUlVjLfwne8AuUY3U7e89zUWwXLnAYK_BiS84M8EsrFvmv8yDLWzqveeIpcN - 5_ysveQnYt9Dqi32w6IOtAywkNUDZeJEdc3z5s9Ei8qrYFN2fxcu28YS4e8e_cHTK5 - 7003WJu-wFn2TJUmAbHuqvUsyTb-nzYOKxuCKlqQItJF7E-cwSb_xULu-3f77BEU_v - GbNYo5ZBa2B7UHO-kWNMSgbW2yeNNLbLC18Kv80GF22Y7SbZt0e2TwnR2Aa2zksuUb - ntQ5c7a1-gxtnXzuIKa34OekrnyqE1hmVWpeQ + eyJhbGciOiJSUzI1NiIsImtpZCI6IktBZ05wV2JSeXk5T + WYycmlrbDQ5OExUaE1ydmtiWldIVlNRT0JDNFZIVTQiLC + JodG0iOiJwb3N0IiwiaHR1IjoiL3R4IiwidHMiOjE2MDM + 4MDA3ODN9.eyJjYXBhYmlsaXRpZXMiOltdLCJjbGllbnQ + iOnsia2V5Ijp7Imp3ayI6eyJrdHkiOiJSU0EiLCJlIjoi + QVFBQiIsImtpZCI6IktBZ05wV2JSeXk5TWYycmlrbDQ5O + ExUaE1ydmtiWldIVlNRT0JDNFZIVTQiLCJuIjoibGxXbU + hGOFhBMktOTGRteE9QM2t4RDlPWTc2cDBTcjM3amZoejk + 0YTkzeG0yRk5xb1NQY1JaQVBkMGxxRFM4TjNVaWE1M2RC + MjNaNTlPd1k0YnBNX1ZmOEdKdnZwdExXbnhvMVB5aG1Qc + i1lY2RTQ1JRZFRjX1pjTUY0aFJWNDhxcWx2dUQwbXF0Y0 + RiSWtTQkR2Y2NKbVpId2ZUcERIaW5UOHR0dmNWUDhWa0F + NQXE0a1ZhenhPcE1vSVJzb3lFcF9lQ2U1cFN3cUhvMGRh + Q1dOS1ItRXBLbTZOaU90ZWRGNE91bXQ4TkxLVFZqZllnR + khlQkRkQ2JyckVUZDR2Qk13RHRBbmpQcjNDVkN3d3gyYk + FRVDZTbHhGSjNmajJoaHlJcHE3cGM4clppYjVqTnlYS3d + mQnVrVFZZWm96a3NodC1Mb2h5QVNhS3BZVHA4THROWi13 + In0sInByb29mIjoiandzIn0sIm5hbWUiOiJNeSBGaXN0I + ENsaWVudCIsInVyaSI6Imh0dHA6Ly9sb2NhbGhvc3QvY2 + xpZW50L2NsaWVudElEIn0sImludGVyYWN0Ijp7ImNhbGx + iYWNrIjp7Im1ldGhvZCI6InJlZGlyZWN0Iiwibm9uY2Ui + OiJkOTAyMTM4ODRiODQwOTIwNTM4YjVjNTEiLCJ1cmkiO + iJodHRwOi8vbG9jYWxob3N0L2NsaWVudC9yZXF1ZXN0LW + RvbmUifSwicmVkaXJlY3QiOnRydWV9LCJyZXNvdXJjZXM + iOnsiYWN0aW9ucyI6WyJyZWFkIiwicHJpbnQiXSwibG9j + YXRpb25zIjpbImh0dHA6Ly9sb2NhbGhvc3QvcGhvdG9zI + l0sInR5cGUiOiJwaG90by1hcGkifSwic3ViamVjdCI6ey + JzdWJfaWRzIjpbImlzcy1zdWIiLCJlbWFpbCJdfX0.LUy + Z8_fERmxbYARq8kBYMwzcd8GnCAKAlo2ZSYLRRNAYWPrp + 2XGLJOvg97WK1idf_LB08OJmLVsCXxCvn9mgaAkYNL_Zj + HcusBvY1mNo0E1sdTEr31CVKfC-6WrZCscb8YqE4Ayhh0 + Te8kzSng3OkLdy7xN4xeKuHzpF7yGsM52JZ0cBcTo6WrY + EfGdr08AWQJ59ht72n3jTsmYNy9A6I4Wrvfgj3TNxmwYo + jpBAicfjnzA1UVcNm9F_xiSz1_y2tdH7j5rVqBMQife-k + 9Ewk95vr3lurthenliYSNiUinVfoW1ybnaIBcTtP1_YCx + g_h1y-B5uZEvYNGCuoCqa6IQ + + This example's JWS header decodes to: + + { + "alg": "RS256", + "kid": "KAgNpWbRyy9Mf2rikl498LThMrvkbZWHVSQOBC4VHU4", + "htm": "post", + "htu": "/tx", + "ts": 1603800783 + } + + And the JWS body decodes to: + +{ + "capabilities": [], + "client": { + "key": { + "jwk": { + "kty": "RSA", + "e": "AQAB", + "kid": "KAgNpWbRyy9Mf2rikl498LThMrvkbZWHVSQOBC4VHU4", + "n": "llWmHF8XA2KNLdmxOP3kxD9OY76p0Sr37jfhz94a93xm2FNqoSPcRZAPd0lqDS8N3Uia53dB23Z59OwY4bpM_Vf8GJvvptLWnxo1PyhmPr-ecdSCRQdTc_ZcMF4hRV48qqlvuD0mqtcDbIkSBDvccJmZHwfTpDHinT8ttvcVP8VkAMAq4kVazxOpMoIRsoyEp_eCe5pSwqHo0daCWNKR-EpKm6NiOtedF4Oumt8NLKTVjfYgFHeBDdCbrrETd4vBMwDtAnjPr3CVCwwx2bAQT6SlxFJ3fj2hhyIpq7pc8rZib5jNyXKwfBukTVYZozksht-LohyASaKpYTp8LtNZ-w" + }, + "proof": "jws" + }, + "name": "My Fist Client", + "uri": "http://localhost/client/clientID" + }, + "interact": { + "callback": { + "method": "redirect", + "nonce": "d90213884b840920538b5c51", + "uri": "http://localhost/client/request-done" + }, + "redirect": true + }, + "resources": { + "actions": [ + "read", + "print" + ], + "locations": [ + "http://localhost/photos" + ], + "type": "photo-api" + }, + "subject": { + "sub_ids": [ + "iss-sub", + "email" + ] + } +} + If the request being made does not have a message body, such as an HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated over an empty payload and passed in the "Detached-JWS" header as described in Section 8.1. [[ Editor's note: A downside to this method is that it requires the content type to be something other than application/json, and it doesn't work against an RS without additional profiling since it takes over the request body - plus we have to specify different delivery locations for a GET vs. a POST, for example. Additionally @@ -4384,29 +4453,30 @@ instead of a single one. Perhaps we should let this return a list of strings instead? Or use a different syntax than the resource request? Also, this borrows heavily from UMA 2's "distributed authorization" model and, like UMA, might be better suited to an extension than the core protocol. ]] 10.4. Requesting a Resources With Insufficient Access If the RC calls an RS without an access token, or with an invalid access token, the RS MAY respond to the RC with an authentication - header indicating that GNAP. The address of the GNAP endpoint MUST - be sent in the "as_uri" parameter. The RS MAY additionally return a - resource reference that the RC MAY use in its resource request - (Section 2.1). This resource reference handle SHOULD be sufficient - for at least the action the RC was attempting to take at the RS. The - RS MAY use the dynamic resource handle request (Section 10.3) to - register a new resource handle, or use a handle that has been pre- - configured to represent what the AS is protecting. The content of - this handle is opaque to the RS and the RC. + header indicating that GNAP needs to be used to access the resource. + The address of the GNAP endpoint MUST be sent in the "as_uri" + parameter. The RS MAY additionally return a resource reference that + the RC MAY use in its resource request (Section 2.1). This resource + reference handle SHOULD be sufficient for at least the action the RC + was attempting to take at the RS. The RS MAY use the dynamic + resource handle request (Section 10.3) to register a new resource + handle, or use a handle that has been pre-configured to represent + what the AS is protecting. The content of this handle is opaque to + the RS and the RC. WWW-Authenticate: GNAP as_uri=http://server.example/tx,resource=FWWIKYBQ6U56NL1 The RC then makes a call to the "as_uri" as described in Section 2, with the value of "resource" as one of the members of a "resources" array Section 2.1.1. The RC MAY request additional resources and other information, and MAY request multiple access tokens. [[ Editor's note: this borrows heavily from UMA 2's "distributed authorization" model and, like UMA, might be better suited to an @@ -4448,23 +4518,25 @@ [[ TBD: There are a lot of privacy considerations to add. ]] Handles are passed between parties and therefore should not contain any private data. When user information is passed to the RC, the AS needs to make sure that it has the permission to do so. 15. Normative References - [BCP195] "Recommendations for Secure Use of Transport Layer + [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, + "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security - (DTLS)", 2015, . + (DTLS)", May 2015, + . [I-D.ietf-httpbis-message-signatures] Backman, A., Richer, J., and M. Sporny, "Signing HTTP Messages", Work in Progress, Internet-Draft, draft-ietf- httpbis-message-signatures-00, 10 April 2020, . [I-D.ietf-oauth-dpop] Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., @@ -4542,198 +4614,32 @@ . [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens", RFC 8705, DOI 10.17487/RFC8705, February 2020, . Appendix A. Document History - * -14 - - - Editorial clarification from design team meetings. - - - Added "at_hash" to both JWS methods for use with an access - token. - - - Allow attached-JWS method to defer to detached-JWS method for - presentation on a non-body request. - - * -13 - - - Clarified that "subject" request and response aren't for - identity claims, just identifiers. - - - Reworked continuation definition in terms of endpoint actions. - - - Defined concrete methods for updating an ongoing grant request - using PATCH. - - - Defined method for reading current status of grant request - using GET. - - - Expanded editorial comments and strawman examples for - alternatives. - - * -12 - - - Collapsed "key" and "display" fields into "client" field. - - - Changed continuation to use optional access token. - - - Defined flags for special behavior of tokens. - - - Defined "key": true to mean access token is bound to client's - key. - - - Defined "key": false to indicate an access token. - - - Added "Elements" section to list and discuss non-role parts of - the protocol. - - * -11 - - - Updated based on Design Team feedback and reviews. - - - Removed oidc_ prefix from several values and used RFC8693 - assertion types. - - - Changed "client" to "RC" throughout. - - - Changed "user" to "RQ" or "RO" as appropriate. - - - Added expansions for request and response section - introductions. - - - Added refresh examples. - - - Added diagrams to RS examples. - - - Added ui_locales hint to interaction block. - - - Added section on JSON polymorphism. - - - Added numerous editorial notes to describe why elements are in - place. - - - Added discussion on composition of roles. - - - Added requirements for signature methods to cover all aspects - of request and mechanisms to do so. - - * -10 - - - Switched to xml2rfc v3 and markdown source. - - - Updated based on Design Team feedback and reviews. - - - Added acknowledgements list. - - - Added sequence diagrams and explanations. - - - Collapsed "short_redirect" into regular redirect request. - - - Separated pass-by-reference into subsections. - - - Collapsed "callback" and "pushback" into a single mode-switched - method. - - - Add OIDC Claims request object example. - - * -09 - - - Major document refactoring based on request and response - capabilities. - - - Changed from "claims" language to "subject identifier" - language. - - - Added "pushback" interaction capability. - - - Removed DIDCOMM interaction (better left to extensions). - - - Excised "transaction" language in favor of "Grant" where - appropriate. - - - Added token management URLs. - - - Added separate continuation URL to use continuation handle - with. - - - Added RS-focused functionality section. - - - Added notion of extending a grant request based on a previous - grant. - - - Simplified returned handle structures. - - * -08 - - - Added attached JWS signature method. - - - Added discovery methods. - - * -07 - - - Marked sections as being controlled by a future registry TBD. - - * -06 - - - Added multiple resource requests and multiple access token - response. - - * -05 - - - Added "claims" request and response for identity support. - - - Added "capabilities" request for inline discovery support. - - * -04 - - - Added crypto agility for callback return hash. - - - Changed "interaction_handle" to "interaction_ref". - - * -03 - - - Removed "state" in favor of "nonce". - - - Created signed return parameter for front channel return. - - - Changed "client" section to "display" section, as well as - associated handle. - - - Changed "key" to "keys". - - - Separated key proofing from key presentation. - - - Separated interaction methods into booleans instead of "type" - field. - - * -02 - - - Minor editorial cleanups. - * -01 - - Made JSON multimodal for handle requests. + - "updated_at" subject info timestamp now in ISO 8601 string + format. - - Major updates to normative language and references throughout - document. + - Editorial fixes. - - Allowed interaction to split between how the user gets to the - AS and how the user gets back. + - Added Aaron and Fabien as document authors. * -00 - - Initial submission. + - Initial working group draft. Appendix B. Component Data Models While different implementations of this protocol will have different realizations of all the components and artifacts enumerated here, the nature of the protocol implies some common structures and elements for certain components. This appendix seeks to enumerate those common elements. TBD: Client has keys, allowed requested resources, identifier(s), @@ -5280,17 +5186,29 @@ when needed for more complex APIs. Extensions to this specification can use different data types for defined fields, but each extension needs to not only declare what the data type means, but also provide justification for the data type representing the same basic kind of thing it extends. For example, an extension declaring an "array" representation for a field would need to explain how the array represents something akin to the non- array element that it is replacing. -Author's Address +Authors' Addresses Justin Richer (editor) Bespoke Engineering Email: ietf@justin.richer.org URI: https://bspk.io/ + + Aaron Parecki + Okta + + Email: aaron@parecki.com + URI: https://aaronparecki.com + + Fabien Imbault + acert.io + + Email: fabien.imbault@acert.io + URI: https://acert.io/