draft-ietf-gnap-core-protocol-00.txt   draft-ietf-gnap-core-protocol-01.txt 
GNAP J. Richer, Ed. GNAP J. Richer, Ed.
Internet-Draft Bespoke Engineering Internet-Draft Bespoke Engineering
Intended status: Standards Track 17 October 2020 Intended status: Standards Track A. Parecki
Expires: 20 April 2021 Expires: 6 May 2021 Okta
F. Imbault
acert.io
2 November 2020
Grant Negotiation and Authorization Protocol Grant Negotiation and Authorization Protocol
draft-ietf-gnap-core-protocol-00 draft-ietf-gnap-core-protocol-01
Abstract Abstract
This document defines a mechanism for delegating authorization to a This document defines a mechanism for delegating authorization to a
piece of software, and conveying that delegation to the software. piece of software, and conveying that delegation to the software.
This delegation can include access to a set of APIs as well as This delegation can include access to a set of APIs as well as
information passed directly to the software. information passed directly to the software.
This document has been prepared by the GNAP working group design team This document has been prepared by the GNAP working group design team
of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones, and of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones, and
Justin Richer. This document is intended as a starting point for the Justin Richer. This document is intended as a starting point for the
working group and includes decision points for discussion and working group and includes decision points for discussion and
agreement. Many of the features in this proposed protocol can be agreement. Many of the features in this proposed protocol can be
accomplished in a number of ways. Where possible, the editor has accomplished in a number of ways. Where possible, the editor has
included notes and discussion from the design team regarding the included notes and discussion from the design team regarding the
options as understood. 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 Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." 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 Notice
Copyright (c) 2020 IETF Trust and the persons identified as the Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components and restrictions with respect to this document. Code Components
extracted from this document must include Simplified BSD License text extracted from this document must include Simplified BSD License text
as described in Section 4.e of the Trust Legal Provisions and are as described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Simplified BSD License. provided without warranty as described in the Simplified BSD License.
Table of Contents Table of Contents
1. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
1.2. Elements . . . . . . . . . . . . . . . . . . . . . . . . 6 1.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3. Sequences . . . . . . . . . . . . . . . . . . . . . . . . 7 1.3. Elements . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.1. Redirect-based Interaction . . . . . . . . . . . . . 10 1.4. Sequences . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.2. User-code Interaction . . . . . . . . . . . . . . . . 12 1.4.1. Redirect-based Interaction . . . . . . . . . . . . . 10
1.3.3. Asynchronous Authorization . . . . . . . . . . . . . 14 1.4.2. User-code Interaction . . . . . . . . . . . . . . . . 12
1.3.4. Software-only Authorization . . . . . . . . . . . . . 15 1.4.3. Asynchronous Authorization . . . . . . . . . . . . . 14
1.3.5. Refreshing an Expired Access Token . . . . . . . . . 16 1.4.4. Software-only Authorization . . . . . . . . . . . . . 16
1.4.5. Refreshing an Expired Access Token . . . . . . . . . 16
2. Requesting Access . . . . . . . . . . . . . . . . . . . . . . 17 2. Requesting Access . . . . . . . . . . . . . . . . . . . . . . 17
2.1. Requesting Resources . . . . . . . . . . . . . . . . . . 19 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.2. Requesting Resources By Reference . . . . . . . . . . 21
2.1.3. Requesting Multiple Access Tokens . . . . . . . . . . 23 2.1.3. Requesting Multiple Access Tokens . . . . . . . . . . 23
2.1.4. Signaling Token Behavior . . . . . . . . . . . . . . 25 2.1.4. Signaling Token Behavior . . . . . . . . . . . . . . 25
2.2. Requesting User Information . . . . . . . . . . . . . . . 27 2.2. Requesting User Information . . . . . . . . . . . . . . . 27
2.3. Identifying the RC . . . . . . . . . . . . . . . . . . . 28 2.3. Identifying the RC . . . . . . . . . . . . . . . . . . . 28
2.3.1. Identifying the RC Instance . . . . . . . . . . . . . 30 2.3.1. Identifying the RC Instance . . . . . . . . . . . . . 30
2.3.2. Identifying the RC Key . . . . . . . . . . . . . . . 31 2.3.2. Identifying the RC Key . . . . . . . . . . . . . . . 31
2.3.3. Providing Displayable RC Information . . . . . . . . 32 2.3.3. Providing Displayable RC Information . . . . . . . . 32
2.3.4. Authenticating the RC . . . . . . . . . . . . . . . . 33 2.3.4. Authenticating the RC . . . . . . . . . . . . . . . . 33
2.4. Identifying the User . . . . . . . . . . . . . . . . . . 33 2.4. Identifying the User . . . . . . . . . . . . . . . . . . 33
skipping to change at page 3, line 44 skipping to change at page 3, line 45
5.3. Modifying an Existing Request . . . . . . . . . . . . . . 69 5.3. Modifying an Existing Request . . . . . . . . . . . . . . 69
5.4. Getting the Current State of a Grant Request . . . . . . 74 5.4. Getting the Current State of a Grant Request . . . . . . 74
5.5. Canceling a Grant Request . . . . . . . . . . . . . . . . 75 5.5. Canceling a Grant Request . . . . . . . . . . . . . . . . 75
6. Token Management . . . . . . . . . . . . . . . . . . . . . . 75 6. Token Management . . . . . . . . . . . . . . . . . . . . . . 75
6.1. Rotating the Access Token . . . . . . . . . . . . . . . . 76 6.1. Rotating the Access Token . . . . . . . . . . . . . . . . 76
6.2. Revoking the Access Token . . . . . . . . . . . . . . . . 78 6.2. Revoking the Access Token . . . . . . . . . . . . . . . . 78
7. Using Access Tokens . . . . . . . . . . . . . . . . . . . . . 79 7. Using Access Tokens . . . . . . . . . . . . . . . . . . . . . 79
8. Binding Keys . . . . . . . . . . . . . . . . . . . . . . . . 80 8. Binding Keys . . . . . . . . . . . . . . . . . . . . . . . . 80
8.1. Detached JWS . . . . . . . . . . . . . . . . . . . . . . 81 8.1. Detached JWS . . . . . . . . . . . . . . . . . . . . . . 81
8.2. Attached JWS . . . . . . . . . . . . . . . . . . . . . . 84 8.2. Attached JWS . . . . . . . . . . . . . . . . . . . . . . 84
8.3. Mutual TLS . . . . . . . . . . . . . . . . . . . . . . . 86 8.3. Mutual TLS . . . . . . . . . . . . . . . . . . . . . . . 89
8.4. Demonstration of Proof-of-Possession (DPoP) . . . . . . . 88 8.4. Demonstration of Proof-of-Possession (DPoP) . . . . . . . 91
8.5. HTTP Signing . . . . . . . . . . . . . . . . . . . . . . 89 8.5. HTTP Signing . . . . . . . . . . . . . . . . . . . . . . 92
8.6. OAuth Proof of Possession (PoP) . . . . . . . . . . . . . 91 8.6. OAuth Proof of Possession (PoP) . . . . . . . . . . . . . 93
9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 92 9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 95
10. Resource Servers . . . . . . . . . . . . . . . . . . . . . . 93 10. Resource Servers . . . . . . . . . . . . . . . . . . . . . . 96
10.1. Introspecting a Token . . . . . . . . . . . . . . . . . 94 10.1. Introspecting a Token . . . . . . . . . . . . . . . . . 97
10.2. Deriving a downstream token . . . . . . . . . . . . . . 95 10.2. Deriving a downstream token . . . . . . . . . . . . . . 98
10.3. Registering a Resource Handle . . . . . . . . . . . . . 97 10.3. Registering a Resource Handle . . . . . . . . . . . . . 100
10.4. Requesting a Resources With Insufficient Access . . . . 98 10.4. Requesting a Resources With Insufficient Access . . . . 101
11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 98 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 101
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 99 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 102
13. Security Considerations . . . . . . . . . . . . . . . . . . . 99 13. Security Considerations . . . . . . . . . . . . . . . . . . . 102
14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 99 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 102
15. Normative References . . . . . . . . . . . . . . . . . . . . 99 15. Normative References . . . . . . . . . . . . . . . . . . . . 102
Appendix A. Document History . . . . . . . . . . . . . . . . . . 101 Appendix A. Document History . . . . . . . . . . . . . . . . . . 104
Appendix B. Component Data Models . . . . . . . . . . . . . . . 105 Appendix B. Component Data Models . . . . . . . . . . . . . . . 105
Appendix C. Example Protocol Flows . . . . . . . . . . . . . . . 105 Appendix C. Example Protocol Flows . . . . . . . . . . . . . . . 105
C.1. Redirect-Based User Interaction . . . . . . . . . . . . . 106 C.1. Redirect-Based User Interaction . . . . . . . . . . . . . 105
C.2. Secondary Device Interaction . . . . . . . . . . . . . . 110 C.2. Secondary Device Interaction . . . . . . . . . . . . . . 109
Appendix D. No User Involvement . . . . . . . . . . . . . . . . 113 Appendix D. No User Involvement . . . . . . . . . . . . . . . . 112
D.1. Asynchronous Authorization . . . . . . . . . . . . . . . 114 D.1. Asynchronous Authorization . . . . . . . . . . . . . . . 113
D.2. Applying OAuth 2 Scopes and Client IDs . . . . . . . . . 117 D.2. Applying OAuth 2 Scopes and Client IDs . . . . . . . . . 116
Appendix E. JSON Structures and Polymorphism . . . . . . . . . . 118 Appendix E. JSON Structures and Polymorphism . . . . . . . . . . 117
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 119 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 118
1. Protocol 1. Introduction
This protocol allows a piece of software, the resource client, to This protocol allows a piece of software, the resource client, to
request delegated authorization to resource servers and direct request delegated authorization to resource servers and direct
information. This delegation is facilitated by an authorization information. This delegation is facilitated by an authorization
server usually on behalf of a resource owner. The requesting party server usually on behalf of a resource owner. The requesting party
operating the software may interact with the authorization server to operating the software may interact with the authorization server to
authenticate, provide consent, and authorize the request. authenticate, provide consent, and authorize the request.
The process by which the delegation happens is known as a grant, and The process by which the delegation happens is known as a grant, and
the GNAP protocol allows for the negotiation of the grant process the GNAP protocol allows for the negotiation of the grant process
skipping to change at page 4, line 46 skipping to change at page 5, line 5
[RFC6749], OpenID Connect [OIDC], and the family of protocols that [RFC6749], OpenID Connect [OIDC], and the family of protocols that
have grown up around that ecosystem. However, GNAP is not an have grown up around that ecosystem. However, GNAP is not an
extension of OAuth 2.0 and is not intended to be directly compatible 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 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 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 and OAuth 2.0 will exist in parallel for many deployments, and
considerations have been taken to facilitate the mapping and considerations have been taken to facilitate the mapping and
transition from legacy systems to GNAP. Some examples of these can transition from legacy systems to GNAP. Some examples of these can
be found in Appendix D.2. 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 The parties in the GNAP protocol perform actions under different
roles. Roles are defined by the actions taken and the expectations roles. Roles are defined by the actions taken and the expectations
leveraged on the role by the overall protocol. leveraged on the role by the overall protocol.
Authorization Server (AS) Manages the requested delegations for the Authorization Server (AS) Manages the requested delegations for the
RO. The AS issues tokens and directly delegated information to RO. The AS issues tokens and directly delegated information to
the RC. The AS is defined by its grant endpoint, a single URL 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 that accepts a POST request with a JSON payload. The AS could
also have other endpoints, including interaction endpoints and also have other endpoints, including interaction endpoints and
skipping to change at page 6, line 39 skipping to change at page 7, line 5
for different roles and components, including: for different roles and components, including:
* Grant Server (for Authorization Server) * Grant Server (for Authorization Server)
* Grant Client (for Resource Client) * Grant Client (for Resource Client)
* Operator (for Requesting Party) * Operator (for Requesting Party)
]] ]]
1.2. Elements 1.3. Elements
In addition to the roles above, the protocol also involves several In addition to the roles above, the protocol also involves several
elements that are acted upon by the roles throughout the process. elements that are acted upon by the roles throughout the process.
Access Token A credential representing a set of access rights Access Token A credential representing a set of access rights
delegated to the RC. The access token is created by the AS, 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 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. The contents and format of the access token are opaque to the
RC. 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. 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 Cryptographic Key A cryptographic element binding a request to a
key. Access tokens and RC instances can be associated with holder of the key. Access tokens and RC instances can be
specific keys. associated with specific keys.
Resource A protected API served by the RS and accessed by the RC. 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 Access to this resource is delegated by the RO as part of the
grant process. grant process.
Subject Information Information about the RO that is returned Subject Information Information about the RO that is returned
directly to the RC from the AS without the RC making a separate 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 call to an RS. Access to this information is delegated by the RO
as part of the grant process. as part of the grant process.
[[ Editor's note: What other core elements need an introduction here? [[ 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 These aren't roles to be taken on by different parties, nor are they
descriptions of the possible configurations of parties, but these are descriptions of the possible configurations of parties, but these are
still important moving parts within the protocol. ]] 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 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 delegation process to take place. Many portions of this process are
conditionally present depending on the context of the deployments, conditionally present depending on the context of the deployments,
and not every step in this overview will happen in all circumstances. and not every step in this overview will happen in all circumstances.
Note that a connection between roles in this process does not Note that a connection between roles in this process does not
necessarily indicate that a specific protocol message is sent across necessarily indicate that a specific protocol message is sent across
the wire between the components fulfilling the roles in question, or the wire between the components fulfilling the roles in question, or
that a particular step is required every time. For example, for an that a particular step is required every time. For example, for an
skipping to change at page 10, line 5 skipping to change at page 10, line 15
* (12) The RS determines if the new token is sufficient for the * (12) The RS determines if the new token is sufficient for the
request by examining the token, potentially calling the AS request by examining the token, potentially calling the AS
(Section 10.1). (Section 10.1).
* (13) The RC disposes of the token (Section 6.2) once the RC has * (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. completed its access of the RS and no longer needs the token.
The following sections and Appendix C contain specific guidance on The following sections and Appendix C contain specific guidance on
how to use the GNAP protocol in different situations and deployments. 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 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 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 requesting party (RQ) and the resource owner (RO). Since the RC is
capable of directing the user to an arbitrary URL and receiving capable of directing the user to an arbitrary URL and receiving
responses from the user's browser, interaction here is handled responses from the user's browser, interaction here is handled
through front-channel redirects using the user's browser. The RC through front-channel redirects using the user's browser. The RC
uses a persistent session with the user to ensure the same user that uses a persistent session with the user to ensure the same user that
is starting the interaction is the user that returns from the is starting the interaction is the user that returns from the
interaction. interaction.
skipping to change at page 12, line 5 skipping to change at page 12, line 12
reference ensuring that the reference is associated with the reference ensuring that the reference is associated with the
request being continued. request being continued.
9. If the request has been authorized, the AS grants access to the 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 information in the form of access tokens (Section 3.2) and direct
subject information (Section 3.4) to the RC. subject information (Section 3.4) to the RC.
An example set of protocol messages for this method can be found in An example set of protocol messages for this method can be found in
Appendix C.1. 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 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 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 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 presenting an arbitrary URL to the user, nor is it capable of
accepting incoming HTTP requests from the user's browser. The RC 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. 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 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, 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 though the user is not assumed to be interacting with the RC through
skipping to change at page 14, line 12 skipping to change at page 14, line 26
11. The RC continues to poll the AS (Section 5.2) with the new 11. The RC continues to poll the AS (Section 5.2) with the new
continuation information in (9). continuation information in (9).
12. If the request has been authorized, the AS grants access to the 12. If the request has been authorized, the AS grants access to the
information in the form of access tokens (Section 3.2) and information in the form of access tokens (Section 3.2) and
direct subject information (Section 3.4) to the RC. direct subject information (Section 3.4) to the RC.
An example set of protocol messages for this method can be found in An example set of protocol messages for this method can be found in
Appendix C.2. 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 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 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 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 RO's authorization for the RC's request. The RC polls the AS while
it is waiting for the RO to authorize the request. it is waiting for the RO to authorize the request.
+--------+ +--------+ +------+ +--------+ +--------+ +------+
| RC | | AS | | RO | | RC | | AS | | RO |
| |--(1)--- Request Access --------->| | | | | |--(1)--- Request Access --------->| | | |
skipping to change at page 15, line 40 skipping to change at page 16, line 5
8. The RC continues to poll the AS (Section 5.2) with the new 8. The RC continues to poll the AS (Section 5.2) with the new
continuation information from (7). continuation information from (7).
9. If the request has been authorized, the AS grants access to the 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 information in the form of access tokens (Section 3.2) and direct
subject information (Section 3.4) to the RC. subject information (Section 3.4) to the RC.
An example set of protocol messages for this method can be found in An example set of protocol messages for this method can be found in
Appendix D.1. 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 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 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 to approve the decision. Since there is no explicit RO, the RC does
not interact with an RO. not interact with an RO.
+--------+ +--------+ +--------+ +--------+
| RC | | AS | | RC | | AS |
| |--(1)--- Request Access --------->| | | |--(1)--- Request Access --------->| |
| | | | | | | |
skipping to change at page 16, line 24 skipping to change at page 16, line 31
not send any interactions modes to the server. not send any interactions modes to the server.
2. The AS determines that the request is been authorized, the AS 2. The AS determines that the request is been authorized, the AS
grants access to the information in the form of access tokens grants access to the information in the form of access tokens
(Section 3.2) and direct subject information (Section 3.4) to the (Section 3.2) and direct subject information (Section 3.4) to the
RC. RC.
An example set of protocol messages for this method can be found in An example set of protocol messages for this method can be found in
Appendix D. 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 In this example flow, the RC receives an access token to access a
resource server through some valid GNAP process. The RC uses that resource server through some valid GNAP process. The RC uses that
token at the RS for some time, but eventually the access token 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 expires. The RC then gets a new access token by rotating the expired
access token at the AS using the token's management URL. access token at the AS using the token's management URL.
+--------+ +--------+ +--------+ +--------+
| RC | | AS | | RC | | AS |
| |--(1)--- Request Access ----------------->| | | |--(1)--- Request Access ----------------->| |
skipping to change at page 25, line 31 skipping to change at page 25, line 31
access token (Section 6.1), the AS does not invalidate the access token (Section 6.1), the AS does not invalidate the
previous access token. The old access token continues to remain previous access token. The old access token continues to remain
valid until such time as it expires or is revoked through other valid until such time as it expires or is revoked through other
means. means.
split_token The RC is capable of receiving multiple access tokens split_token The RC is capable of receiving multiple access tokens
(Section 3.2.2) in response to any single token request (Section 3.2.2) in response to any single token request
(Section 2.1.1), or receiving a different number of tokens than (Section 2.1.1), or receiving a different number of tokens than
specified in the multiple token request (Section 2.1.3). The specified in the multiple token request (Section 2.1.3). The
labels of the returned additional tokens are chosen by the AS. labels of the returned additional tokens are chosen by the AS.
The client MUST be able to tell from the token response where and The RC MUST be able to tell from the token response where and how
how it can use the each access tokens. [[ Editor's note: This it can use each of the access tokens. [[ Editor's note: This
functionality is controversial at best as it requires functionality is controversial at best as it requires
significantly more complexity on the client in order to solve one significantly more complexity on the client in order to solve one
class of AS/RS deployment choices. ]] class of AS/RS deployment choices. ]]
bind_token The RC wants the issued access token to be bound to the 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 key the RC used (Section 2.3.2) to make the request. The
resulting access token MUST be bound using the same "proof" resulting access token MUST be bound using the same "proof"
mechanism used by the client with a "key" value of "true", mechanism used by the client with a "key" value of "true",
indicating the client's presented key is to be used for binding. indicating the client's presented key is to be used for binding.
[[ Editor's note: should there be a different flag and mechanism [[ Editor's note: should there be a different flag and mechanism
skipping to change at page 33, line 21 skipping to change at page 33, line 21
identified by this key, such as limiting which resources can be identified by this key, such as limiting which resources can be
requested and which interaction methods can be used. For example, requested and which interaction methods can be used. For example,
only specific RCs with certain known keys might be trusted with only specific RCs with certain known keys might be trusted with
access tokens without the AS interacting directly with the RO as in access tokens without the AS interacting directly with the RO as in
Appendix D. Appendix D.
The presentation of a key allows the AS to strongly associate The presentation of a key allows the AS to strongly associate
multiple successive requests from the same RC with each other. This 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 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 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 created just for this series of requests. As such the AS MAY allow
make requests with unknown keys. This pattern allows for ephemeral for RCs to make requests with unknown keys. This pattern allows for
RCs, such as single-page applications, and RCs with many individual ephemeral RCs, such as single-page applications, and RCs with many
instances, such as mobile applications, to generate their own key individual instances, such as mobile applications, to generate their
pairs and use them within the protocol without having to go through a own key pairs and use them within the protocol without having to go
separate registration step. The AS MAY limit which capabilities are through a separate registration step. The AS MAY limit which
made available to RCs with unknown keys. For example, the AS could capabilities are made available to RCs with unknown keys. For
have a policy saying that only previously-registered RCs can request example, the AS could have a policy saying that only previously-
particular resources, or that all RCs with unknown keys have to be registered RCs can request particular resources, or that all RCs with
interactively approved by an RO. unknown keys have to be interactively approved by an RO.
2.4. Identifying the User 2.4. Identifying the User
If the RC knows the identity of the RQ through one or more 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 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 in the "user" field. The RC MAY pass this information by value or by
reference. reference.
sub_ids An array of subject identifiers for the RQ, as defined by sub_ids An array of subject identifiers for the RQ, as defined by
[I-D.ietf-secevent-subject-identifiers]. [I-D.ietf-secevent-subject-identifiers].
skipping to change at page 36, line 28 skipping to change at page 36, line 28
"interact": { "interact": {
"redirect": true, "redirect": true,
"callback": { "callback": {
"method": "redirect", "method": "redirect",
"uri": "https://client.example.net/return/123455", "uri": "https://client.example.net/return/123455",
"nonce": "LKLTI25DK82FX4T4QFZC" "nonce": "LKLTI25DK82FX4T4QFZC"
} }
} }
In this non-normative example, the RC is indicating that it can 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 URL of maximum length (Section 2.5.1.1) 255 characters, but it cannot
accept a callback. accept a callback.
"interact": { "interact": {
"redirect": 255, "redirect": 255,
"user_code": true "user_code": true
} }
If the RC does not provide a suitable interaction mechanism, the AS If the RC does not provide a suitable interaction mechanism, the AS
cannot contact the RO asynchronously, and the AS determines that cannot contact the RO asynchronously, and the AS determines that
skipping to change at page 41, line 46 skipping to change at page 41, line 46
"uri": "https://client.example.net/return/123455", "uri": "https://client.example.net/return/123455",
"nonce": "LKLTI25DK82FX4T4QFZC" "nonce": "LKLTI25DK82FX4T4QFZC"
} }
} }
Requests to the callback URI MUST be processed by the RC as described Requests to the callback URI MUST be processed by the RC as described
in Section 4.4.2. in Section 4.4.2.
Since the incoming request to the callback URL is from the AS and not 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 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 [[ Editor's note: This post-interaction method can be used in
advanced use cases like asynchronous authorization, or simply to advanced use cases like asynchronous authorization, or simply to
signal the client that it should move to the next part of the 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 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 it can feel a little odd being inside the "interact" block of the
protocol, but it does align with the redirect-based "callback" method protocol, but it does align with the redirect-based "callback" method
and it seems they really should be mutually-exclusive. Additionally, and it seems they really should be mutually-exclusive. Additionally,
should there be a method for simply pushing the updated response should there be a method for simply pushing the updated response
directly to the client, instead? ]] directly to the client, instead? ]]
skipping to change at page 46, line 29 skipping to change at page 46, line 29
} }
} }
3.1. Request Continuation 3.1. Request Continuation
If the AS determines that the request can be continued with If the AS determines that the request can be continued with
additional requests, it responds with the "continue" field. This additional requests, it responds with the "continue" field. This
field contains a JSON object with the following properties. field contains a JSON object with the following properties.
uri REQUIRED. The URI at which the RC can make continuation uri REQUIRED. The URI at which the RC can make continuation
requests. This URI MAY vary request, or MAY be stable at the AS requests. This URI MAY vary per request, or MAY be stable at the
if the AS includes an access token. The RC MUST use this value AS if the AS includes an access token. The RC MUST use this value
exactly as given when making a continuation request (Section 5). exactly as given when making a continuation request (Section 5).
wait RECOMMENDED. The amount of time in integer seconds the RC wait RECOMMENDED. The amount of time in integer seconds the RC
SHOULD wait after receiving this continuation handle and calling SHOULD wait after receiving this continuation handle and calling
the URI. the URI.
access_token RECOMMENDED. A unique access token for continuing the access_token RECOMMENDED. A unique access token for continuing the
request, in the format specified in Section 3.2.1. This access 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 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 NOT be a "bearer" token. This access token MUST NOT be usable at
skipping to change at page 48, line 24 skipping to change at page 48, line 24
other protocols without requiring additional encoding. other protocols without requiring additional encoding.
manage OPTIONAL. The management URI for this access token. If manage OPTIONAL. The management URI for this access token. If
provided, the RC MAY manage its access token as described in provided, the RC MAY manage its access token as described in
Section 6. This management URI is a function of the AS and is 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 separate from the RS the RC is requesting access to. This URI
MUST NOT include the access token value and SHOULD be different MUST NOT include the access token value and SHOULD be different
for each access token issued in a request. for each access token issued in a request.
resources RECOMMENDED. A description of the rights associated with 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. MUST reflect the rights associated with the issued access token.
These rights MAY vary from what was requested by the RC. These rights MAY vary from what was requested by the RC.
expires_in OPTIONAL. The number of seconds in which the access will 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 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 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 access token MAY be revoked by the AS or RS at any point prior to
its expiration. its expiration.
key REQUIRED. The key that the token is bound to. If the boolean key REQUIRED. The key that the token is bound to. If the boolean
skipping to change at page 54, line 43 skipping to change at page 54, line 43
sub_ids An array of subject identifiers for the RO, as defined by sub_ids An array of subject identifiers for the RO, as defined by
[I-D.ietf-secevent-subject-identifiers]. [[ Editor's note: privacy [I-D.ietf-secevent-subject-identifiers]. [[ Editor's note: privacy
considerations are needed around returning identifiers. ]] considerations are needed around returning identifiers. ]]
assertions An object containing assertions as values keyed on the assertions An object containing assertions as values keyed on the
assertion type defined by a registry TBD (Section 12). [[ assertion type defined by a registry TBD (Section 12). [[
Editor's note: should this be an array of objects with internal 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 typing like the sub_ids? Do we expect more than one assertion per
user anyway? ]] 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 identified account was last updated. The RC MAY use this value to
determine if it needs to request updated profile information determine if it needs to request updated profile information
through an identity API. The definition of such an identity API through an identity API. The definition of such an identity API
is out of scope for this specification. is out of scope for this specification.
"subject": { "subject": {
"sub_ids": [ { "sub_ids": [ {
"subject_type": "email", "subject_type": "email",
"email": "user@example.com", "email": "user@example.com",
} ], } ],
skipping to change at page 85, line 23 skipping to change at page 86, line 9
into compact form [RFC7515]. into compact form [RFC7515].
The RC presents the JWS as the body of the request along with a 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 content type of "application/jose". The AS MUST extract the payload
of the JWS and treat it as the request body for further processing. of the JWS and treat it as the request body for further processing.
POST /tx HTTP/1.1 POST /tx HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/jose Content-Type: application/jose
eyJiNjQiOmZhbHNlLCJhbGciOiJSUzI1NiIsImtpZCI6Inh5ei0xIn0.ewogICAgIm eyJhbGciOiJSUzI1NiIsImtpZCI6IktBZ05wV2JSeXk5T
NsaWVudCI6IHsKICAgICAgICAibmFtZSI6ICJNeSBDbGllbnQgRGlzcGxheSBOYW1l WYycmlrbDQ5OExUaE1ydmtiWldIVlNRT0JDNFZIVTQiLC
IiwKICAgICAgICAidXJpIjogImh0dHBzOi8vZXhhbXBsZS5uZXQvY2xpZW50IgogIC JodG0iOiJwb3N0IiwiaHR1IjoiL3R4IiwidHMiOjE2MDM
AgfSwKICAgICJyZXNvdXJjZXMiOiBbCiAgICAgICAgImRvbHBoaW4tbWV0YWRhdGEi 4MDA3ODN9.eyJjYXBhYmlsaXRpZXMiOltdLCJjbGllbnQ
CiAgICBdLAogICAgImludGVyYWN0IjogewogICAgICAgICJyZWRpcmVjdCI6IHRydW iOnsia2V5Ijp7Imp3ayI6eyJrdHkiOiJSU0EiLCJlIjoi
UsCiAgICAgICAgImNhbGxiYWNrIjogewogICAgCQkidXJpIjogImh0dHBzOi8vY2xp QVFBQiIsImtpZCI6IktBZ05wV2JSeXk5TWYycmlrbDQ5O
ZW50LmZvbyIsCiAgICAJCSJub25jZSI6ICJWSkxPNkE0Q0FZTEJYSFRSMEtSTyIKIC ExUaE1ydmtiWldIVlNRT0JDNFZIVTQiLCJuIjoibGxXbU
AgIAl9CiAgICB9LAogICAgImtleXMiOiB7CgkJInByb29mIjogImp3c2QiLAogICAg hGOFhBMktOTGRteE9QM2t4RDlPWTc2cDBTcjM3amZoejk
ICAgICJqd2tzIjogewogICAgICAgICAgICAia2V5cyI6IFsKICAgICAgICAgICAgIC 0YTkzeG0yRk5xb1NQY1JaQVBkMGxxRFM4TjNVaWE1M2RC
AgIHsKICAgICAgICAgICAgICAgICAgICAia3R5IjogIlJTQSIsCiAgICAgICAgICAg MjNaNTlPd1k0YnBNX1ZmOEdKdnZwdExXbnhvMVB5aG1Qc
ICAgICAgICAgImUiOiAiQVFBQiIsCiAgICAgICAgICAgICAgICAgICAgImtpZCI6IC i1lY2RTQ1JRZFRjX1pjTUY0aFJWNDhxcWx2dUQwbXF0Y0
J4eXotMSIsCiAgICAgICAgICAgICAgICAgICAgImFsZyI6ICJSUzI1NiIsCiAgICAg RiSWtTQkR2Y2NKbVpId2ZUcERIaW5UOHR0dmNWUDhWa0F
ICAgICAgICAgICAgICAgIm4iOiAia09CNXJSNEp2MEdNZUxhWTZfSXRfcjNPUndkZj NQXE0a1ZhenhPcE1vSVJzb3lFcF9lQ2U1cFN3cUhvMGRh
hjaV9KdGZmWHlhU3g4eFlKQ0NOYU9LTkpuX096MFloZEhiWFRlV081QW95c3BEV0pi Q1dOS1ItRXBLbTZOaU90ZWRGNE91bXQ4TkxLVFZqZllnR
TjV3XzdiZFdEeGdwRC15NmpuRDF1OVloQk9DV09iTlBGdnBrVE04TEM3U2RYR1JLeD khlQkRkQ2JyckVUZDR2Qk13RHRBbmpQcjNDVkN3d3gyYk
JrOE1lMnJfR3NzWWx5UnBxdnBCbFk1LWVqQ3l3S1JCZmN0UmNuaFRUR056dGJiREJV FRVDZTbHhGSjNmajJoaHlJcHE3cGM4clppYjVqTnlYS3d
eURTV21GTVZDSGU1bVhUNGNMMEJ3clpDNlMtdXUtTEF4MDZhS3dRT1B3WU9HT3NsSz mQnVrVFZZWm96a3NodC1Mb2h5QVNhS3BZVHA4THROWi13
hXUG0xeUdka2FBMXVGX0ZwUzZMUzYzV1lQSGlfQXAyQjdfOFdidzR0dHpiTVNfZG9K In0sInByb29mIjoiandzIn0sIm5hbWUiOiJNeSBGaXN0I
dnVEYWdXOEExSXAzZlhGQUh0UkFjS3c3cmRJNF9YbG42NmhKeEZla3BkZldkaVBRZG ENsaWVudCIsInVyaSI6Imh0dHA6Ly9sb2NhbGhvc3QvY2
RRNlkxY0syVTNvYnZVZzd3IgogICAgICAgICAgICAgICAgfQogICAgICAgICAgICBd xpZW50L2NsaWVudElEIn0sImludGVyYWN0Ijp7ImNhbGx
CiAgICAgICAgfQogICAgfQp9.Y287HMtaY0EegEjoTd_04a4GC6qV48GgVbGKOhHdJ iYWNrIjp7Im1ldGhvZCI6InJlZGlyZWN0Iiwibm9uY2Ui
nDtD0VuUlVjLfwne8AuUY3U7e89zUWwXLnAYK_BiS84M8EsrFvmv8yDLWzqveeIpcN OiJkOTAyMTM4ODRiODQwOTIwNTM4YjVjNTEiLCJ1cmkiO
5_ysveQnYt9Dqi32w6IOtAywkNUDZeJEdc3z5s9Ei8qrYFN2fxcu28YS4e8e_cHTK5 iJodHRwOi8vbG9jYWxob3N0L2NsaWVudC9yZXF1ZXN0LW
7003WJu-wFn2TJUmAbHuqvUsyTb-nzYOKxuCKlqQItJF7E-cwSb_xULu-3f77BEU_v RvbmUifSwicmVkaXJlY3QiOnRydWV9LCJyZXNvdXJjZXM
GbNYo5ZBa2B7UHO-kWNMSgbW2yeNNLbLC18Kv80GF22Y7SbZt0e2TwnR2Aa2zksuUb iOnsiYWN0aW9ucyI6WyJyZWFkIiwicHJpbnQiXSwibG9j
ntQ5c7a1-gxtnXzuIKa34OekrnyqE1hmVWpeQ 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 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 HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated
over an empty payload and passed in the "Detached-JWS" header as over an empty payload and passed in the "Detached-JWS" header as
described in Section 8.1. described in Section 8.1.
[[ Editor's note: A downside to this method is that it requires the [[ Editor's note: A downside to this method is that it requires the
content type to be something other than application/json, and it content type to be something other than application/json, and it
doesn't work against an RS without additional profiling since it doesn't work against an RS without additional profiling since it
takes over the request body - plus we have to specify different takes over the request body - plus we have to specify different
delivery locations for a GET vs. a POST, for example. Additionally delivery locations for a GET vs. a POST, for example. Additionally
skipping to change at page 98, line 17 skipping to change at page 101, line 17
instead of a single one. Perhaps we should let this return a list of instead of a single one. Perhaps we should let this return a list of
strings instead? Or use a different syntax than the resource strings instead? Or use a different syntax than the resource
request? Also, this borrows heavily from UMA 2's "distributed request? Also, this borrows heavily from UMA 2's "distributed
authorization" model and, like UMA, might be better suited to an authorization" model and, like UMA, might be better suited to an
extension than the core protocol. ]] extension than the core protocol. ]]
10.4. Requesting a Resources With Insufficient Access 10.4. Requesting a Resources With Insufficient Access
If the RC calls an RS without an access token, or with an invalid 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 access token, the RS MAY respond to the RC with an authentication
header indicating that GNAP. The address of the GNAP endpoint MUST header indicating that GNAP needs to be used to access the resource.
be sent in the "as_uri" parameter. The RS MAY additionally return a The address of the GNAP endpoint MUST be sent in the "as_uri"
resource reference that the RC MAY use in its resource request parameter. The RS MAY additionally return a resource reference that
(Section 2.1). This resource reference handle SHOULD be sufficient the RC MAY use in its resource request (Section 2.1). This resource
for at least the action the RC was attempting to take at the RS. The reference handle SHOULD be sufficient for at least the action the RC
RS MAY use the dynamic resource handle request (Section 10.3) to was attempting to take at the RS. The RS MAY use the dynamic
register a new resource handle, or use a handle that has been pre- resource handle request (Section 10.3) to register a new resource
configured to represent what the AS is protecting. The content of handle, or use a handle that has been pre-configured to represent
this handle is opaque to the RS and the RC. 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 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, 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" 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 array Section 2.1.1. The RC MAY request additional resources and
other information, and MAY request multiple access tokens. other information, and MAY request multiple access tokens.
[[ Editor's note: this borrows heavily from UMA 2's "distributed [[ Editor's note: this borrows heavily from UMA 2's "distributed
authorization" model and, like UMA, might be better suited to an authorization" model and, like UMA, might be better suited to an
skipping to change at page 99, line 38 skipping to change at page 102, line 33
[[ TBD: There are a lot of privacy considerations to add. ]] [[ TBD: There are a lot of privacy considerations to add. ]]
Handles are passed between parties and therefore should not contain Handles are passed between parties and therefore should not contain
any private data. any private data.
When user information is passed to the RC, the AS needs to make sure When user information is passed to the RC, the AS needs to make sure
that it has the permission to do so. that it has the permission to do so.
15. Normative References 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 Security (TLS) and Datagram Transport Layer Security
(DTLS)", 2015, <http://www.rfc-editor.org/info/bcp195>. (DTLS)", May 2015,
<http://www.rfc-editor.org/info/bcp195>.
[I-D.ietf-httpbis-message-signatures] [I-D.ietf-httpbis-message-signatures]
Backman, A., Richer, J., and M. Sporny, "Signing HTTP Backman, A., Richer, J., and M. Sporny, "Signing HTTP
Messages", Work in Progress, Internet-Draft, draft-ietf- Messages", Work in Progress, Internet-Draft, draft-ietf-
httpbis-message-signatures-00, 10 April 2020, httpbis-message-signatures-00, 10 April 2020,
<http://www.ietf.org/internet-drafts/draft-ietf-httpbis- <http://www.ietf.org/internet-drafts/draft-ietf-httpbis-
message-signatures-00.txt>. message-signatures-00.txt>.
[I-D.ietf-oauth-dpop] [I-D.ietf-oauth-dpop]
Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., Fett, D., Campbell, B., Bradley, J., Lodderstedt, T.,
skipping to change at page 101, line 35 skipping to change at page 104, line 40
<https://www.rfc-editor.org/info/rfc8693>. <https://www.rfc-editor.org/info/rfc8693>.
[RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T.
Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication
and Certificate-Bound Access Tokens", RFC 8705, and Certificate-Bound Access Tokens", RFC 8705,
DOI 10.17487/RFC8705, February 2020, DOI 10.17487/RFC8705, February 2020,
<https://www.rfc-editor.org/info/rfc8705>. <https://www.rfc-editor.org/info/rfc8705>.
Appendix A. Document History 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 * -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 - Editorial fixes.
document.
- Allowed interaction to split between how the user gets to the - Added Aaron and Fabien as document authors.
AS and how the user gets back.
* -00 * -00
- Initial submission. - Initial working group draft.
Appendix B. Component Data Models Appendix B. Component Data Models
While different implementations of this protocol will have different While different implementations of this protocol will have different
realizations of all the components and artifacts enumerated here, the realizations of all the components and artifacts enumerated here, the
nature of the protocol implies some common structures and elements nature of the protocol implies some common structures and elements
for certain components. This appendix seeks to enumerate those for certain components. This appendix seeks to enumerate those
common elements. common elements.
TBD: Client has keys, allowed requested resources, identifier(s), TBD: Client has keys, allowed requested resources, identifier(s),
skipping to change at page 119, line 39 skipping to change at page 118, line 39
when needed for more complex APIs. when needed for more complex APIs.
Extensions to this specification can use different data types for Extensions to this specification can use different data types for
defined fields, but each extension needs to not only declare what the defined fields, but each extension needs to not only declare what the
data type means, but also provide justification for the data type data type means, but also provide justification for the data type
representing the same basic kind of thing it extends. For example, representing the same basic kind of thing it extends. For example,
an extension declaring an "array" representation for a field would an extension declaring an "array" representation for a field would
need to explain how the array represents something akin to the non- need to explain how the array represents something akin to the non-
array element that it is replacing. array element that it is replacing.
Author's Address Authors' Addresses
Justin Richer (editor) Justin Richer (editor)
Bespoke Engineering Bespoke Engineering
Email: ietf@justin.richer.org Email: ietf@justin.richer.org
URI: https://bspk.io/ 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/
 End of changes. 37 change blocks. 
283 lines changed or deleted 190 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/