draft-ietf-gnap-core-protocol-08.txt   draft-ietf-gnap-core-protocol-09.txt 
GNAP J. Richer, Ed. GNAP J. Richer, Ed.
Internet-Draft Bespoke Engineering Internet-Draft Bespoke Engineering
Intended status: Standards Track A. Parecki Intended status: Standards Track A. Parecki
Expires: 28 April 2022 Okta Expires: 7 September 2022 Okta
F. Imbault F. Imbault
acert.io acert.io
25 October 2021 6 March 2022
Grant Negotiation and Authorization Protocol Grant Negotiation and Authorization Protocol
draft-ietf-gnap-core-protocol-08 draft-ietf-gnap-core-protocol-09
Abstract Abstract
GNAP defines a mechanism for delegating authorization to a piece of GNAP defines a mechanism for delegating authorization to a piece of
software, and conveying that delegation to the software. This software, and conveying that delegation to the software. This
delegation can include access to a set of APIs as well as information delegation can include access to a set of APIs as well as information
passed directly to the software. passed directly to the software.
Status of This Memo Status of This Memo
skipping to change at page 1, line 36 skipping to change at page 1, line 36
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 28 April 2022. This Internet-Draft will expire on 7 September 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2022 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 Revised BSD License text as
as described in Section 4.e of the Trust Legal Provisions and are 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 Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
1.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3. Elements . . . . . . . . . . . . . . . . . . . . . . . . 9 1.3. Elements . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4. Trust relationships . . . . . . . . . . . . . . . . . . . 10 1.4. Trust relationships . . . . . . . . . . . . . . . . . . . 10
1.5. Sequences . . . . . . . . . . . . . . . . . . . . . . . . 12 1.5. Sequences . . . . . . . . . . . . . . . . . . . . . . . . 12
1.5.1. Redirect-based Interaction . . . . . . . . . . . . . 15 1.5.1. Overall Protocol Sequence . . . . . . . . . . . . . . 12
1.5.2. User-code Interaction . . . . . . . . . . . . . . . . 18 1.5.2. Redirect-based Interaction . . . . . . . . . . . . . 15
1.5.3. Asynchronous Authorization . . . . . . . . . . . . . 20 1.5.3. User-code Interaction . . . . . . . . . . . . . . . . 18
1.5.4. Software-only Authorization . . . . . . . . . . . . . 22 1.5.4. Asynchronous Authorization . . . . . . . . . . . . . 20
1.5.5. Refreshing an Expired Access Token . . . . . . . . . 23 1.5.5. Software-only Authorization . . . . . . . . . . . . . 22
1.5.6. Requesting User Information . . . . . . . . . . . . . 25 1.5.6. Refreshing an Expired Access Token . . . . . . . . . 23
1.5.7. Requesting User Information . . . . . . . . . . . . . 25
2. Requesting Access . . . . . . . . . . . . . . . . . . . . . . 26 2. Requesting Access . . . . . . . . . . . . . . . . . . . . . . 26
2.1. Requesting Access to Resources . . . . . . . . . . . . . 28 2.1. Requesting Access to Resources . . . . . . . . . . . . . 28
2.1.1. Requesting a Single Access Token . . . . . . . . . . 28 2.1.1. Requesting a Single Access Token . . . . . . . . . . 28
2.1.2. Requesting Multiple Access Tokens . . . . . . . . . . 31 2.1.2. Requesting Multiple Access Tokens . . . . . . . . . . 31
2.2. Requesting Subject Information . . . . . . . . . . . . . 33 2.2. Requesting Subject Information . . . . . . . . . . . . . 33
2.3. Identifying the Client Instance . . . . . . . . . . . . . 34 2.3. Identifying the Client Instance . . . . . . . . . . . . . 34
2.3.1. Identifying the Client Instance by Reference . . . . 35 2.3.1. Identifying the Client Instance by Reference . . . . 35
2.3.2. Providing Displayable Client Instance Information . . 36 2.3.2. Providing Displayable Client Instance Information . . 36
2.3.3. Authenticating the Client Instance . . . . . . . . . 36 2.3.3. Authenticating the Client Instance . . . . . . . . . 37
2.4. Identifying the User . . . . . . . . . . . . . . . . . . 37 2.4. Identifying the User . . . . . . . . . . . . . . . . . . 37
2.4.1. Identifying the User by Reference . . . . . . . . . . 38 2.4.1. Identifying the User by Reference . . . . . . . . . . 38
2.5. Interacting with the User . . . . . . . . . . . . . . . . 39 2.5. Interacting with the User . . . . . . . . . . . . . . . . 39
2.5.1. Start Mode Definitions . . . . . . . . . . . . . . . 40 2.5.1. Start Mode Definitions . . . . . . . . . . . . . . . 40
2.5.2. Finish Interaction Modes . . . . . . . . . . . . . . 42 2.5.2. Finish Interaction Methods . . . . . . . . . . . . . 42
2.5.3. Hints . . . . . . . . . . . . . . . . . . . . . . . . 44 2.5.3. Hints . . . . . . . . . . . . . . . . . . . . . . . . 45
2.5.4. Extending Interaction Modes . . . . . . . . . . . . . 45 2.5.4. Extending Interaction Modes . . . . . . . . . . . . . 45
2.6. Extending The Grant Request . . . . . . . . . . . . . . . 45 2.6. Extending The Grant Request . . . . . . . . . . . . . . . 46
3. Grant Response . . . . . . . . . . . . . . . . . . . . . . . 45 3. Grant Response . . . . . . . . . . . . . . . . . . . . . . . 46
3.1. Request Continuation . . . . . . . . . . . . . . . . . . 47 3.1. Request Continuation . . . . . . . . . . . . . . . . . . 48
3.2. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 48 3.2. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 49
3.2.1. Single Access Token . . . . . . . . . . . . . . . . . 48 3.2.1. Single Access Token . . . . . . . . . . . . . . . . . 49
3.2.2. Multiple Access Tokens . . . . . . . . . . . . . . . 52 3.2.2. Multiple Access Tokens . . . . . . . . . . . . . . . 53
3.3. Interaction Modes . . . . . . . . . . . . . . . . . . . . 53 3.3. Interaction Modes . . . . . . . . . . . . . . . . . . . . 54
3.3.1. Redirection to an arbitrary URL . . . . . . . . . . . 54 3.3.1. Redirection to an arbitrary URI . . . . . . . . . . . 55
3.3.2. Launch of an application URL . . . . . . . . . . . . 55 3.3.2. Launch of an application URI . . . . . . . . . . . . 56
3.3.3. Display of a Short User Code . . . . . . . . . . . . 55 3.3.3. Display of a Short User Code . . . . . . . . . . . . 56
3.3.4. Interaction Finish . . . . . . . . . . . . . . . . . 56 3.3.4. Display of a Short User Code and URI . . . . . . . . 57
3.3.5. Extending Interaction Mode Responses . . . . . . . . 57 3.3.5. Interaction Finish . . . . . . . . . . . . . . . . . 58
3.4. Returning Subject Information . . . . . . . . . . . . . . 57 3.3.6. Extending Interaction Mode Responses . . . . . . . . 59
3.4. Returning Subject Information . . . . . . . . . . . . . . 59
3.5. Returning a Dynamically-bound Client Instance 3.5. Returning a Dynamically-bound Client Instance
Identifier . . . . . . . . . . . . . . . . . . . . . . . 58 Identifier . . . . . . . . . . . . . . . . . . . . . . . 60
3.6. Error Response . . . . . . . . . . . . . . . . . . . . . 59 3.6. Error Response . . . . . . . . . . . . . . . . . . . . . 61
3.7. Extending the Response . . . . . . . . . . . . . . . . . 60 3.7. Extending the Response . . . . . . . . . . . . . . . . . 62
4. Determining Authorization and Consent . . . . . . . . . . . . 60 4. Determining Authorization and Consent . . . . . . . . . . . . 62
4.1. Interaction Start Methods . . . . . . . . . . . . . . . . 63 4.1. Interaction Start Methods . . . . . . . . . . . . . . . . 65
4.1.1. Interaction at a Redirected URI . . . . . . . . . . . 63 4.1.1. Interaction at a Redirected URI . . . . . . . . . . . 66
4.1.2. Interaction at the User Code URI . . . . . . . . . . 64 4.1.2. Interaction at the Static User Code URI . . . . . . . 66
4.1.3. Interaction through an Application URI . . . . . . . 65 4.1.3. Interaction at a Dynamic User Code URI . . . . . . . 67
4.2. Post-Interaction Completion . . . . . . . . . . . . . . . 65 4.1.4. Interaction through an Application URI . . . . . . . 68
4.2. Post-Interaction Completion . . . . . . . . . . . . . . . 68
4.2.1. Completing Interaction with a Browser Redirect to the 4.2.1. Completing Interaction with a Browser Redirect to the
Callback URI . . . . . . . . . . . . . . . . . . . . 66 Callback URI . . . . . . . . . . . . . . . . . . . . 69
4.2.2. Completing Interaction with a Direct HTTP Request 4.2.2. Completing Interaction with a Direct HTTP Request
Callback . . . . . . . . . . . . . . . . . . . . . . 67 Callback . . . . . . . . . . . . . . . . . . . . . . 70
4.2.3. Calculating the interaction hash . . . . . . . . . . 68 4.2.3. Calculating the interaction hash . . . . . . . . . . 71
5. Continuing a Grant Request . . . . . . . . . . . . . . . . . 69 5. Continuing a Grant Request . . . . . . . . . . . . . . . . . 72
5.1. Continuing After a Completed Interaction . . . . . . . . 71 5.1. Continuing After a Completed Interaction . . . . . . . . 74
5.2. Continuing During Pending Interaction . . . . . . . . . . 72 5.2. Continuing During Pending Interaction . . . . . . . . . . 75
5.3. Modifying an Existing Request . . . . . . . . . . . . . . 74 5.3. Modifying an Existing Request . . . . . . . . . . . . . . 77
5.4. Canceling a Grant Request . . . . . . . . . . . . . . . . 80 5.4. Canceling a Grant Request . . . . . . . . . . . . . . . . 83
6. Token Management . . . . . . . . . . . . . . . . . . . . . . 80 6. Token Management . . . . . . . . . . . . . . . . . . . . . . 83
6.1. Rotating the Access Token . . . . . . . . . . . . . . . . 80 6.1. Rotating the Access Token . . . . . . . . . . . . . . . . 83
6.2. Revoking the Access Token . . . . . . . . . . . . . . . . 82 6.2. Revoking the Access Token . . . . . . . . . . . . . . . . 85
7. Securing Requests from the Client Instance . . . . . . . . . 83 7. Securing Requests from the Client Instance . . . . . . . . . 86
7.1. Key Formats . . . . . . . . . . . . . . . . . . . . . . . 84 7.1. Key Formats . . . . . . . . . . . . . . . . . . . . . . . 87
7.1.1. Key References . . . . . . . . . . . . . . . . . . . 85 7.1.1. Key References . . . . . . . . . . . . . . . . . . . 88
7.2. Presenting Access Tokens . . . . . . . . . . . . . . . . 85 7.1.2. Key Protection . . . . . . . . . . . . . . . . . . . 88
7.3. Proving Possession of a Key with a Request . . . . . . . 86 7.2. Presenting Access Tokens . . . . . . . . . . . . . . . . 89
7.3.1. HTTP Message Signing . . . . . . . . . . . . . . . . 88 7.3. Proving Possession of a Key with a Request . . . . . . . 90
7.3.2. Mutual TLS . . . . . . . . . . . . . . . . . . . . . 92 7.3.1. HTTP Message Signing . . . . . . . . . . . . . . . . 92
7.3.3. Detached JWS . . . . . . . . . . . . . . . . . . . . 94 7.3.2. Mutual TLS . . . . . . . . . . . . . . . . . . . . . 96
7.3.4. Attached JWS . . . . . . . . . . . . . . . . . . . . 98 7.3.3. Detached JWS . . . . . . . . . . . . . . . . . . . . 98
8. Resource Access Rights . . . . . . . . . . . . . . . . . . . 102 7.3.4. Attached JWS . . . . . . . . . . . . . . . . . . . . 102
8.1. Requesting Resources By Reference . . . . . . . . . . . . 105 8. Resource Access Rights . . . . . . . . . . . . . . . . . . . 106
9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 107 8.1. Requesting Resources By Reference . . . . . . . . . . . . 109
9.1. RS-first Method of AS Discovery . . . . . . . . . . . . . 108 9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 111
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 110 9.1. RS-first Method of AS Discovery . . . . . . . . . . . . . 113
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 110 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 114
12. Security Considerations . . . . . . . . . . . . . . . . . . . 110 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 115
12.1. TLS Protection in Transit . . . . . . . . . . . . . . . 110 12. Security Considerations . . . . . . . . . . . . . . . . . . . 115
12.2. Signing Requests from the Client Software . . . . . . . 111 12.1. TLS Protection in Transit . . . . . . . . . . . . . . . 115
12.3. Protection of Client Instance Key Material . . . . . . . 112 12.2. Signing Requests from the Client Software . . . . . . . 116
12.4. Protection of Authorization Server . . . . . . . . . . . 114 12.3. Protection of Client Instance Key Material . . . . . . . 117
12.5. Symmetric and Asymmetric Client Instance Keys . . . . . 114 12.4. Protection of Authorization Server . . . . . . . . . . . 118
12.6. Generation of Access Tokens . . . . . . . . . . . . . . 115 12.5. Symmetric and Asymmetric Client Instance Keys . . . . . 119
12.7. Bearer Access Tokens . . . . . . . . . . . . . . . . . . 116 12.6. Generation of Access Tokens . . . . . . . . . . . . . . 120
12.8. Key-Bound Token Access Tokens . . . . . . . . . . . . . 116 12.7. Bearer Access Tokens . . . . . . . . . . . . . . . . . . 121
12.9. Exposure of End-user Credentials to Client Instance . . 117 12.8. Key-Bound Access Tokens . . . . . . . . . . . . . . . . 121
12.10. Mixing Up Authorization Servers . . . . . . . . . . . . 118 12.9. Exposure of End-user Credentials to Client Instance . . 122
12.11. Processing of Client-Presented User Information . . . . 119 12.10. Mixing Up Authorization Servers . . . . . . . . . . . . 123
12.12. Client Instance Pre-registration . . . . . . . . . . . . 120 12.11. Processing of Client-Presented User Information . . . . 123
12.13. Client Instance Impersonation . . . . . . . . . . . . . 121 12.12. Client Instance Pre-registration . . . . . . . . . . . . 124
12.14. Interception of Information in the Browser . . . . . . . 122 12.13. Client Instance Impersonation . . . . . . . . . . . . . 125
12.15. Callback URL Manipulation . . . . . . . . . . . . . . . 122 12.14. Interception of Information in the Browser . . . . . . . 126
12.16. MTLS Message Integrity . . . . . . . . . . . . . . . . . 123 12.15. Callback URI Manipulation . . . . . . . . . . . . . . . 127
12.17. MTLS Deployment Patterns . . . . . . . . . . . . . . . . 124 12.16. Redirection Status Codes . . . . . . . . . . . . . . . . 127
12.18. Interception of Responses from the AS . . . . . . . . . 124 12.17. MTLS Message Integrity . . . . . . . . . . . . . . . . . 128
12.19. Key Distribution . . . . . . . . . . . . . . . . . . . . 125 12.18. MTLS Deployment Patterns . . . . . . . . . . . . . . . . 129
12.20. Interaction Finish Modes and Polling . . . . . . . . . . 125 12.19. Interception of Responses from the AS . . . . . . . . . 130
12.21. Storage of Information During Interaction and 12.20. Key Distribution . . . . . . . . . . . . . . . . . . . . 130
Continuation . . . . . . . . . . . . . . . . . . . . . 126 12.21. Interaction Finish Modes and Polling . . . . . . . . . . 130
12.22. Denial of Service (DoS) through Grant Continuation . . . 126 12.22. Session Management for Interaction Finish Methods . . . 131
12.23. Exhaustion of Random Value Space . . . . . . . . . . . . 127 12.23. Storage of Information During Interaction and
12.24. Front-channel URLs . . . . . . . . . . . . . . . . . . . 128 Continuation . . . . . . . . . . . . . . . . . . . . . 133
12.25. Processing Assertions . . . . . . . . . . . . . . . . . 129 12.24. Denial of Service (DoS) through Grant Continuation . . . 133
13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 129 12.25. Exhaustion of Random Value Space . . . . . . . . . . . . 134
13.1. Surveillance . . . . . . . . . . . . . . . . . . . . . . 129 12.26. Front-channel URIs . . . . . . . . . . . . . . . . . . . 135
13.1.1. Surveillance by the Client . . . . . . . . . . . . . 130 12.27. Processing Assertions . . . . . . . . . . . . . . . . . 136
13.1.2. Surveillance by the Authorization Server . . . . . . 130 12.28. Stolen Token Replay . . . . . . . . . . . . . . . . . . 136
13.2. Stored Data . . . . . . . . . . . . . . . . . . . . . . 130 12.29. Self-contained Stateless Access Tokens . . . . . . . . . 137
13.3. Intrusion . . . . . . . . . . . . . . . . . . . . . . . 131 12.30. Network Problems and Token and Grant Management . . . . 138
13.4. Correlation . . . . . . . . . . . . . . . . . . . . . . 131 12.31. Server-side Request Forgery (SSRF) . . . . . . . . . . . 139
13.4.1. Correlation by Clients . . . . . . . . . . . . . . . 132 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 140
13.4.2. Correlation by Resource Servers . . . . . . . . . . 132 13.1. Surveillance . . . . . . . . . . . . . . . . . . . . . . 140
13.4.3. Correlation by Authorization Servers . . . . . . . . 133 13.1.1. Surveillance by the Client . . . . . . . . . . . . . 140
13.5. Disclosure in Shared References . . . . . . . . . . . . 133 13.1.2. Surveillance by the Authorization Server . . . . . . 141
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 133 13.2. Stored Data . . . . . . . . . . . . . . . . . . . . . . 141
14.1. Normative References . . . . . . . . . . . . . . . . . . 133 13.3. Intrusion . . . . . . . . . . . . . . . . . . . . . . . 142
14.2. Informative References . . . . . . . . . . . . . . . . . 135 13.4. Correlation . . . . . . . . . . . . . . . . . . . . . . 142
Appendix A. Document History . . . . . . . . . . . . . . . . . . 136 13.4.1. Correlation by Clients . . . . . . . . . . . . . . . 142
Appendix B. Compared to OAuth 2.0 . . . . . . . . . . . . . . . 139 13.4.2. Correlation by Resource Servers . . . . . . . . . . 143
Appendix C. Component Data Models . . . . . . . . . . . . . . . 141 13.4.3. Correlation by Authorization Servers . . . . . . . . 143
Appendix D. Example Protocol Flows . . . . . . . . . . . . . . . 142 13.5. Disclosure in Shared References . . . . . . . . . . . . 143
D.1. Redirect-Based User Interaction . . . . . . . . . . . . . 142 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 143
D.2. Secondary Device Interaction . . . . . . . . . . . . . . 146 14.1. Normative References . . . . . . . . . . . . . . . . . . 144
D.3. No User Involvement . . . . . . . . . . . . . . . . . . . 149 14.2. Informative References . . . . . . . . . . . . . . . . . 146
D.4. Asynchronous Authorization . . . . . . . . . . . . . . . 150 Appendix A. Document History . . . . . . . . . . . . . . . . . . 147
D.5. Applying OAuth 2.0 Scopes and Client IDs . . . . . . . . 154 Appendix B. Compared to OAuth 2.0 . . . . . . . . . . . . . . . 150
Appendix E. JSON Structures and Polymorphism . . . . . . . . . . 155 Appendix C. Component Data Models . . . . . . . . . . . . . . . 153
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 156 Appendix D. Example Protocol Flows . . . . . . . . . . . . . . . 153
D.1. Redirect-Based User Interaction . . . . . . . . . . . . . 154
D.2. Secondary Device Interaction . . . . . . . . . . . . . . 157
D.3. No User Involvement . . . . . . . . . . . . . . . . . . . 160
D.4. Asynchronous Authorization . . . . . . . . . . . . . . . 161
D.5. Applying OAuth 2.0 Scopes and Client IDs . . . . . . . . 165
Appendix E. JSON Structures and Polymorphism . . . . . . . . . . 166
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 167
1. Introduction 1. Introduction
This protocol allows a piece of software, the client instance, to This protocol allows a piece of software, the client instance, to
request delegated authorization to resource servers and to request request delegated authorization to resource servers and to request
direct information. This delegation is facilitated by an direct information. This delegation is facilitated by an
authorization server usually on behalf of a resource owner. The end- authorization server usually on behalf of a resource owner. The end
user operating the software may interact with the authorization user operating the software may interact with the authorization
server to authenticate, provide consent, and authorize the request. server to 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
GNAP allows for the negotiation of the grant process over time by GNAP allows for the negotiation of the grant process over time by
multiple parties acting in distinct roles. multiple parties acting in distinct roles.
This specification focuses on the portions of the delegation process This specification focuses on the portions of the delegation process
facing the client instance. In particular, this specification facing the client instance. In particular, this specification
defines interoperable methods for a client instance to request, defines interoperable methods for a client instance to request,
skipping to change at page 6, line 14 skipping to change at page 6, line 26
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
This document contains non-normative examples of partial and complete This document contains non-normative examples of partial and complete
HTTP messages, JSON structures, URLs, query components, keys, and HTTP messages, JSON structures, URIs, query components, keys, and
other elements. Some examples use a single trailing backslash \ to other elements. Whenever possible, the document uses URI as a
indicate line wrapping for long values, as per [RFC8792]. The \ generic term, since it aligns with [RFC3986] recommendations and
character and leading spaces on wrapped lines are not part of the matches better with the intent that the identifier may be reachable
value. through various/generic means (compared to URLs). Some examples use
a single trailing backslash \ to indicate line wrapping for long
values, as per [RFC8792]. The \ character and leading spaces on
wrapped lines are not part of the value.
1.2. Roles 1.2. Roles
The parties in GNAP perform actions under different roles. Roles are The parties in GNAP perform actions under different roles. Roles are
defined by the actions taken and the expectations leveraged on the defined by the actions taken and the expectations leveraged on the
role by the overall protocol. role by the overall protocol.
+-------------+ +------------+ +-------------+ +------------+
| | | | | | | |
|Authorization| | Resource | |Authorization| | Resource |
| Server | | Server | | Server | | Server |
| |<-+ +---->| | | |<--+ +--->| |
+-------------+ | | +------------+ +-------------+ | | +------------+
+ | | + | |
+ | | + | |
+ | | + | |
+ | | + | |
+ | | + | |
+ +----------+ + +----------+
+ | Client | + | Client |
+ | Instance | + | Instance |
+ +----------+ + +----------+
+ + + +
+ + + +
+ + + +
+-----------+ + +------------+ +-----------+ + +------------+
| | + + + +| | | | + + + | |
| Resource | | End | | Resource | | End |
| Owner | ~ ~ ~ ~ ~ ~ | User | | Owner | ~ ~ ~ ~ ~ ~ | User |
| | | | | | | |
+-----------+ +------------+ +-----------+ +------------+
Legend Legend
+ + + indicates interaction between a human and computer + + + indicates interaction between a human and computer
----- indicates interaction between two pieces of software ----- indicates interaction between two pieces of software
~ ~ ~ indicates a potential equivalence or out-of-band ~ ~ ~ indicates a potential equivalence or out-of-band
communication between roles communication between roles
Authorization Server (AS) server that grants delegated privileges to Authorization Server (AS) server that grants delegated privileges to
a particular instance of client software in the form of access a particular instance of client software in the form of access
tokens or other information (such as subject information). tokens or other information (such as subject information).
Client application that consumes resources from one or several RSs, Client application that consumes resources from one or several RSs,
possibly requiring access privileges from one or several ASs. The possibly requiring access privileges from one or several ASs. The
client is operated by the end-user or it runs autonomously on client is operated by the end user or it runs autonomously on
behalf of a resource owner. behalf of a resource owner.
Example: a client can be a mobile application, a web application, Example: a client can be a mobile application, a web application,
etc. etc.
Note: this specification differentiates between a specific Note: this specification differentiates between a specific
instance (the client instance, identified by its unique key) and instance (the client instance, identified by its unique key) and
the software running the instance (the client software). For some the software running the instance (the client software). For some
kinds of client software, there could be many instances of that kinds of client software, there could be many instances of that
software, each instance with a different key. software, each instance with a different key.
skipping to change at page 8, line 22 skipping to change at page 8, line 22
resources, where operations require a valid access token issued by resources, where operations require a valid access token issued by
an AS. an AS.
Resource Owner (RO) subject entity that may grant or deny operations Resource Owner (RO) subject entity that may grant or deny operations
on resources it has authority upon. on resources it has authority upon.
Note: the act of granting or denying an operation may be manual Note: the act of granting or denying an operation may be manual
(i.e. through an interaction with a physical person) or automatic (i.e. through an interaction with a physical person) or automatic
(i.e. through predefined organizational rules). (i.e. through predefined organizational rules).
End-user natural person that operates a client instance. End user natural person that operates a client instance.
Note: that natural person may or may not be the same entity as the Note: that natural person may or may not be the same entity as the
RO. RO.
The design of GNAP does not assume any one deployment architecture, The design of GNAP does not assume any one deployment architecture,
but instead attempts to define roles that can be fulfilled in a but instead attempts to define roles that can be fulfilled in a
number of different ways for different use cases. As long as a given number of different ways for different use cases. As long as a given
role fulfills all of its obligations and behaviors as defined by the role fulfills all of its obligations and behaviors as defined by the
protocol, GNAP does not make additional requirements on its structure protocol, GNAP does not make additional requirements on its structure
or setup. or setup.
Multiple roles can be fulfilled by the same party, and a given party Multiple roles can be fulfilled by the same party, and a given party
can switch roles in different instances of the protocol. For can switch roles in different instances of the protocol. For
example, the RO and end-user in many instances are the same person, example, the RO and end user in many instances are the same person,
where a user is authorizing the client instance to act on their own where a user is authorizing the client instance to act on their own
behalf at the RS. In this case, one party fulfills both of the RO behalf at the RS. In this case, one party fulfills both of the RO
and end-user roles, but the roles themselves are still defined and end-user roles, but the roles themselves are still defined
separately from each other to allow for other use cases where they separately from each other to allow for other use cases where they
are fulfilled by different parties. are fulfilled by different parties.
For another example, in some complex scenarios, an RS receiving For another example, in some complex scenarios, an RS receiving
requests from one client instance can act as a client instance for a requests from one client instance can act as a client instance for a
downstream secondary RS in order to fulfill the original request. In downstream secondary RS in order to fulfill the original request. In
this case, one piece of software is both an RS and a client instance this case, one piece of software is both an RS and a client instance
from different perspectives, and it fulfills these roles separately from different perspectives, and it fulfills these roles separately
as far as the overall protocol is concerned. as far as the overall protocol is concerned.
A single role need not be deployed as a monolithic service. For A single role need not be deployed as a monolithic service. For
example, A client instance could have components that are installed example, a client instance could have components that are installed
on the end-user's device as well as a back-end system that it on the end user's device as well as a back-end system that it
communicates with. If both of these components participate in the communicates with. If both of these components participate in the
delegation protocol, they are both considered part of the client delegation protocol, they are both considered part of the client
instance. If there are several copies of the client software that instance. If there are several copies of the client software that
run separately but all share the same key material, such as a run separately but all share the same key material, such as a
deployed cluster, then this cluster is considered a single client deployed cluster, then this cluster is considered a single client
instance. instance.
In these cases, the distinct components of what is considered a GNAP In these cases, the distinct components of what is considered a GNAP
client instance may use any number of different communication client instance may use any number of different communication
mechanisms between them, all of which would be considered an mechanisms between them, all of which would be considered an
skipping to change at page 10, line 7 skipping to change at page 10, line 7
Grant (verb): to permit an instance of client software to receive Grant (verb): to permit an instance of client software to receive
some attributes at a specific time and valid for a specific some attributes at a specific time and valid for a specific
duration and/or to exercise some set of delegated rights to access duration and/or to exercise some set of delegated rights to access
a protected resource (noun): the act of granting. a protected resource (noun): the act of granting.
Privilege right or attribute associated with a subject. Privilege right or attribute associated with a subject.
Note: the RO defines and maintains the rights and attributes Note: the RO defines and maintains the rights and attributes
associated to the protected resource, and might temporarily associated to the protected resource, and might temporarily
delegate some set of those privileges to an end-user. This delegate some set of those privileges to an end user. This
process is refered to as privilege delegation. process is refered to as privilege delegation.
Protected Resource protected API (Application Programming Interface) Protected Resource protected API (Application Programming Interface)
served by an RS and that can be accessed by a client, if and only served by an RS and that can be accessed by a client, if and only
if a valid access token is provided. if a valid access token is provided.
Note: to avoid complex sentences, the specification document may Note: to avoid complex sentences, the specification document may
simply refer to resource instead of protected resource. simply refer to "resource" instead of "protected resource".
Right ability given to a subject to perform a given operation on a Right ability given to a subject to perform a given operation on a
resource under the control of an RS. resource under the control of an RS.
Subject person, organization or device. It decides whether and Subject person, organization or device. It decides whether and
under which conditions its attributes can be disclosed to other under which conditions its attributes can be disclosed to other
parties. parties.
Subject Information statement asserted by an AS about a subject. Subject Information statement asserted by an AS about a subject.
1.4. Trust relationships 1.4. Trust relationships
GNAP defines its trust objective as: "the RO trusts the AS to ensure GNAP defines its trust objective as: "the RO trusts the AS to ensure
access validation and delegation of protected resources to end-users, access validation and delegation of protected resources to end users,
through third party clients." through third party clients."
This trust objective can be decomposed into trust relationships This trust objective can be decomposed into trust relationships
between software elements and roles, especially the pairs end-user/ between software elements and roles, especially the pairs end user/
RO, end-user/client, client/AS, RS/RO, AS/RO, AS/RS. Trust of an RO, end user/client, client/AS, RS/RO, AS/RO, AS/RS. Trust of an
agent by its pair can exist if the pair is informed that the agent agent by its pair can exist if the pair is informed that the agent
has made a promise to follow the protocol in the past (e.g. pre- has made a promise to follow the protocol in the past (e.g. pre-
registration, uncompromised cryptographic components) or if the pair registration, uncompromised cryptographic components) or if the pair
is able to infer by indirect means that the agent has made such a is able to infer by indirect means that the agent has made such a
promise (e.g. a compliant client request). Each agent defines its promise (e.g. a compliant client request). Each agent defines its
own valuation function of promises given or received. Examples of own valuation function of promises given or received. Examples of
such valuations can be the benefits from interacting with other such valuations can be the benefits from interacting with other
agents (e.g. safety in client access, interoperability with identity agents (e.g. safety in client access, interoperability with identity
standards), the cost of following the protocol (including its standards), the cost of following the protocol (including its
security and privacy requirements and recommendations), a ranking of security and privacy requirements and recommendations), a ranking of
skipping to change at page 11, line 7 skipping to change at page 11, line 7
assessment of one's vulnerability or risk of not being able to defend assessment of one's vulnerability or risk of not being able to defend
against threats, etc. Those valuations may depend on the context of against threats, etc. Those valuations may depend on the context of
the request. For instance, the AS may decide to either take into the request. For instance, the AS may decide to either take into
account or discard hints provided by the client, the RS may refuse account or discard hints provided by the client, the RS may refuse
bearer tokens, etc. depending on the specific case in which GNAP is bearer tokens, etc. depending on the specific case in which GNAP is
used. Some promises can be conditional of some previous interactions used. Some promises can be conditional of some previous interactions
(e.g. repeated requests). (e.g. repeated requests).
Looking back on each trust relationship: Looking back on each trust relationship:
* end-user/RO: this relationship exists only when the end-user and * end user/RO: this relationship exists only when the end user and
the RO are different, in which case the end-user needs some out of the RO are different, in which case the end user needs some out of
band mechanism of getting the RO consent (see Section 4). GNAP band mechanism of getting the RO consent (see Section 4). GNAP
generally assumes that humans can be authenticated thanks to generally assumes that humans can be authenticated thanks to
identity protocols (for instance, through an id_token assertion in identity protocols (for instance, through an id_token assertion in
Section 2.2). Section 2.2).
* end-user/client: the client acts as a user agent. Depending on * end user/client: the client acts as a user agent. Depending on
the technology used (browser, SPA, mobile application, IoT device, the technology used (browser, SPA, mobile application, IoT device,
etc.), some interactions may or may not be possible (as described etc.), some interactions may or may not be possible (as described
in Section 2.5.1). Client developers promise to implement in Section 2.5.1). Client developers promise to implement
requirements and generally some recommendations or best practices, requirements and generally some recommendations or best practices,
so that the end-users may confidently use their software. so that the end users may confidently use their software.
However, end-users might also be facing some attacker's client However, end users might also be facing some attacker's client
software, without even realizing it. software, without even realizing it.
* end-user / AS: when the client supports it (see Section 3.3), the * end user/AS: when the client supports it (see Section 3.3), the
end-user gets to interact with front-channel URLs provided by the end user gets to interact with front-channel URIs provided by the
AS. See Section 12.24 for some considerations in trusting these AS. See Section 12.26 for some considerations in trusting these
interactions. interactions.
* client/AS: An honest AS may be facing an attacker's client (as * client/AS: An honest AS may be facing an attacker's client (as
discussed just above), or the reverse, and GNAP aims at making discussed just above), or the reverse, and GNAP aims at making
common attacks impractical. The core specification makes access common attacks impractical. The core specification makes access
tokens opaque to the client and defines the request/response tokens opaque to the client and defines the request/response
scheme in detail, therefore avoiding extra trust hypotheses from scheme in detail, therefore avoiding extra trust hypotheses from
this critical piece of software. Yet the AS may further define this critical piece of software. Yet the AS may further define
cryptographic attestations or optional rules to simplify the cryptographic attestations or optional rules to simplify the
access of clients it already trusts, due to past behavior or access of clients it already trusts, due to past behavior or
skipping to change at page 12, line 29 skipping to change at page 12, line 29
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 a that a particular step is required every time. For example, for a
client instance interested in only getting subject information client instance interested in only getting subject information
directly, and not calling an RS, all steps involving the RS below do directly, and not calling an RS, all steps involving the RS below do
not apply. not apply.
In some circumstances, the information needed at a given stage is In some circumstances, the information needed at a given stage is
communicated out of band or is preconfigured between the components communicated out of band or is preconfigured between the components
or entities performing the roles. For example, one entity can fulfil or entities performing the roles. For example, one entity can
multiple roles, and so explicit communication between the roles is fulfill multiple roles, and so explicit communication between the
not necessary within the protocol flow. Additionally some components roles is not necessary within the protocol flow. Additionally some
may not be involved in all use cases. For example, a client instance components may not be involved in all use cases. For example, a
could be calling the AS just to get direct user information and have client instance could be calling the AS just to get direct user
no need to get an access token to call an RS. information and have no need to get an access token to call an RS.
1.5.1. Overall Protocol Sequence
The following diagram provides a general overview of GNAP, including
many different optional phases and connections. The diagrams in the
following sections provide views of GNAP under more specific
circumstances.
+------------+ +------------+ +------------+ +------------+
| End-user | ~ ~ ~ ~ | Resource | | End user | ~ ~ ~ ~ | Resource |
| | | Owner (RO) | | | | Owner (RO) |
+------------+ +------------+ +------------+ +------------+
+ + + +
+ + + +
(A) (B) (A) (B)
+ + + +
+ + + +
+--------+ + +------------+ +--------+ + +------------+
| Client | (1) + | Resource | | Client | (1) + | Resource |
|Instance| + | Server | |Instance| + | Server |
| | +---------------+ | (RS) | | | +---------------+ | (RS) |
| |--(2)->| Authorization | | | | |--(2)->| Authorization | | |
| |<-(3)--| Server | | | | |<-(3)--| Server | | |
| | | (AS) | | | | | | (AS) | | |
| |--(4)->| | | | | |--(4)->| | | |
| |<-(5)--| | | | | |<-(5)--| | | |
| |--------------(6)------------->| | | |--------------(6)------------->| |
skipping to change at page 13, line 40 skipping to change at page 13, line 40
| |-(13)->| | | | | |-(13)->| | | |
| | | | | | | | | | | |
+--------+ +---------------+ +------------+ +--------+ +---------------+ +------------+
Legend Legend
+ + + indicates a possible interaction with a human + + + indicates a possible interaction with a human
----- indicates an interaction between protocol roles ----- indicates an interaction between protocol roles
~ ~ ~ indicates a potential equivalence or out-of-band ~ ~ ~ indicates a potential equivalence or out-of-band
communication between roles communication between roles
* (A) The end-user interacts with the client instance to indicate a * (A) The end user interacts with the client instance to indicate a
need for resources on behalf of the RO. This could identify the need for resources on behalf of the RO. This could identify the
RS the client instance needs to call, the resources needed, or the RS the client instance needs to call, the resources needed, or the
RO that is needed to approve the request. Note that the RO and RO that is needed to approve the request. Note that the RO and
end-user are often the same entity in practice, but GNAP makes no end user are often the same entity in practice, but GNAP makes no
general assumption that they are. general assumption that they are.
* (1) The client instance determines what access is needed and which * (1) The client instance determines what access is needed and which
AS to approach for access. Note that for most situations, the AS to approach for access. Note that for most situations, the
client instance is pre-configured with which AS to talk to and client instance is pre-configured with which AS to talk to and
which kinds of access it needs, but some more dynamic processes which kinds of access it needs, but some more dynamic processes
are discussed in Section 9.1. are discussed in Section 9.1.
* (2) The client instance requests access at the AS (Section 2). * (2) The client instance requests access at the AS (Section 2).
* (3) The AS processes the request and determines what is needed to * (3) The AS processes the request and determines what is needed to
fulfill the request. (See Section 4.) The AS sends its response fulfill the request. (See Section 4.) The AS sends its response
to the client instance (Section 3). to the client instance (Section 3).
* (B) If interaction is required, the AS interacts with the RO * (B) If interaction is required, the AS interacts with the RO
(Section 4) to gather authorization. The interactive component of (Section 4) to gather authorization. The interactive component of
the AS can function using a variety of possible mechanisms the AS can function using a variety of possible mechanisms
including web page redirects, applications, challenge/response including web page redirects, applications, challenge/response
protocols, or other methods. The RO approves the request for the protocols, or other methods. The RO approves the request for the
client instance being operated by the end-user. Note that the RO client instance being operated by the end user. Note that the RO
and end-user are often the same entity in practice, and many of and end user are often the same entity in practice, and many of
GNAP's interaction methods allow the client instance to facilitate GNAP's interaction methods allow the client instance to facilitate
the end user interacting with the AS in order to fulfill the role the end user interacting with the AS in order to fulfill the role
of the RO. of the RO.
* (4) The client instance continues the grant at the AS (Section 5). * (4) The client instance continues the grant at the AS (Section 5).
* (5) If the AS determines that access can be granted, it returns a * (5) If the AS determines that access can be granted, it returns a
response to the client instance (Section 3) including an access response to the client instance (Section 3) including an access
token (Section 3.2) for calling the RS and any directly returned token (Section 3.2) for calling the RS and any directly returned
information (Section 3.4) about the RO. information (Section 3.4) about the RO.
skipping to change at page 15, line 20 skipping to change at page 15, line 20
* (13) The client instance disposes of the token (Section 6.2) once * (13) The client instance disposes of the token (Section 6.2) once
the client instance has completed its access of the RS and no the client instance has completed its access of the RS and no
longer needs the token. longer needs the token.
The following sections and Appendix D contain specific guidance on The following sections and Appendix D contain specific guidance on
how to use GNAP in different situations and deployments. For how to use GNAP in different situations and deployments. For
example, it is possible for the client instance to never request an example, it is possible for the client instance to never request an
access token and never call an RS, just as it is possible for there access token and never call an RS, just as it is possible for there
not to be a user involved in the delegation process. not to be a user involved in the delegation process.
1.5.1. Redirect-based Interaction 1.5.2. Redirect-based Interaction
In this example flow, the client instance is a web application that In this example flow, the client instance is a web application that
wants access to resources on behalf of the current user, who acts as wants access to resources on behalf of the current user, who acts as
both the end-user and the resource owner (RO). Since the client both the end user and the resource owner (RO). Since the client
instance is capable of directing the user to an arbitrary URL and instance is capable of directing the user to an arbitrary URI and
receiving responses from the user's browser, interaction here is receiving responses from the user's browser, interaction here is
handled through front-channel redirects using the user's browser. handled through front-channel redirects using the user's browser.
The redirection URL used for interaction is a service hosted by the The redirection URI used for interaction is a service hosted by the
AS in this example. The client instance uses a persistent session AS in this example. The client instance uses a persistent session
with the user to ensure the same user that is starting the with the user to ensure the same user that is starting the
interaction is the user that returns from the interaction. interaction is the user that returns from the interaction.
+--------+ +--------+ +------+ +--------+ +--------+ +------+
| Client | | AS | | User | | Client | | AS | | User |
|Instance| | | | | |Instance| | | | |
| |< (1) + Start Session + + + + + + + + + + + + + + + +| | | |< (1) + Start Session + + + + + + + + + + + + + + + +| |
| | | | | | | | | | | |
| |--(2)--- Request Access --------->| | | | | |--(2)--- Request Access --------->| | | |
skipping to change at page 16, line 36 skipping to change at page 16, line 36
| |<-(9)----- Grant Access ----------| | | |<-(9)----- Grant Access ----------| |
| | | | | | | |
| | | | +--------+ | | | | +--------+
| |--(10)-- Access API ---------------------------->| RS | | |--(10)-- Access API ---------------------------->| RS |
| | | | | | | | | | | |
| |<-(11)-- API Response ---------------------------| | | |<-(11)-- API Response ---------------------------| |
| | | | +--------+ | | | | +--------+
+--------+ +--------+ +--------+ +--------+
1. The client instance establishes a verifiable session to the 1. The client instance establishes a verifiable session to the
user, in the role of the end-user. user, in the role of the end user.
2. The client instance requests access to the resource (Section 2). 2. The client instance requests access to the resource (Section 2).
The client instance indicates that it can redirect to an The client instance indicates that it can redirect to an
arbitrary URL (Section 2.5.1.1) and receive a redirect from the arbitrary URI (Section 2.5.1.1) and receive a redirect from the
browser (Section 2.5.2.1). The client instance stores browser (Section 2.5.2.1). The client instance stores
verification information for its redirect in the session created verification information for its redirect in the session created
in (1). in (1).
3. The AS determines that interaction is needed and responds 3. The AS determines that interaction is needed and responds
(Section 3) with a URL to send the user to (Section 3.3.1) and (Section 3) with a URI to send the user to (Section 3.3.1) and
information needed to verify the redirect (Section 3.3.4) in information needed to verify the redirect (Section 3.3.5) in
(7). The AS also includes information the client instance will (7). The AS also includes information the client instance will
need to continue the request (Section 3.1) in (8). The AS need to continue the request (Section 3.1) in (8). The AS
associates this continuation information with an ongoing request associates this continuation information with an ongoing request
that will be referenced in (4), (6), and (8). that will be referenced in (4), (6), and (8).
4. The client instance stores the verification and continuation 4. The client instance stores the verification and continuation
information from (3) in the session from (1). The client information from (3) in the session from (1). The client
instance then redirects the user to the URL (Section 4.1.1) instance then redirects the user to the URI (Section 4.1.1)
given by the AS in (3). The user's browser loads the given by the AS in (3). The user's browser loads the
interaction redirect URL. The AS loads the pending request interaction redirect URI. The AS loads the pending request
based on the incoming URL generated in (3). based on the incoming URI generated in (3).
5. The user authenticates at the AS, taking on the role of the RO. 5. The user authenticates at the AS, taking on the role of the RO.
6. As the RO, the user authorizes the pending request from the 6. As the RO, the user authorizes the pending request from the
client instance. client instance.
7. When the AS is done interacting with the user, the AS redirects 7. When the AS is done interacting with the user, the AS redirects
the user back (Section 4.2.1) to the client instance using the the user back (Section 4.2.1) to the client instance using the
redirect URL provided in (2). The redirect URL is augmented redirect URI provided in (2). The redirect URI is augmented
with an interaction reference that the AS associates with the with an interaction reference that the AS associates with the
ongoing request created in (2) and referenced in (4). The ongoing request created in (2) and referenced in (4). The
redirect URL is also augmented with a hash of the security redirect URI is also augmented with a hash of the security
information provided in (2) and (3). The client instance loads information provided in (2) and (3). The client instance loads
the verification information from (2) and (3) from the session the verification information from (2) and (3) from the session
created in (1). The client instance calculates a hash created in (1). The client instance calculates a hash
(Section 4.2.3) based on this information and continues only if (Section 4.2.3) based on this information and continues only if
the hash validates. Note that the client instance needs to the hash validates. Note that the client instance needs to
ensure that the parameters for the incoming request match those ensure that the parameters for the incoming request match those
that it is expecting from the session created in (1). The that it is expecting from the session created in (1). The
client instance also needs to be prepared for the end-user never client instance also needs to be prepared for the end user never
being returned to the client instance and handle timeouts being returned to the client instance and handle timeouts
appropriately. appropriately.
8. The client instance loads the continuation information from (3) 8. The client instance loads the continuation information from (3)
and sends the interaction reference from (7) in a request to and sends the interaction reference from (7) in a request to
continue the request (Section 5.1). The AS validates the continue the request (Section 5.1). The AS validates the
interaction reference ensuring that the reference is associated interaction reference ensuring that the reference is associated
with the request being continued. with the 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
skipping to change at page 18, line 5 skipping to change at page 18, line 5
10. The client instance uses the access token (Section 7.2) to call 10. The client instance uses the access token (Section 7.2) to call
the RS. the RS.
11. The RS validates the access token and returns an appropriate 11. The RS validates the access token and returns an appropriate
response for the API. response for the API.
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.5.2. User-code Interaction 1.5.3. User-code Interaction
In this example flow, the client instance is a device that is capable In this example flow, the client instance is a device that is capable
of presenting a short, human-readable code to the user and directing of presenting a short, human-readable code to the user and directing
the user to enter that code at a known URL. The URL the user enters the user to enter that code at a known URI. The URI the user enters
the code at is an interactive service hosted by the AS in this the code at is an interactive service hosted by the AS in this
example. The client instance is not capable of presenting an example. The client instance is not capable of presenting an
arbitrary URL to the user, nor is it capable of accepting incoming arbitrary URI to the user, nor is it capable of accepting incoming
HTTP requests from the user's browser. The client instance polls the HTTP requests from the user's browser. The client instance polls the
AS while it is waiting for the RO to authorize the request. 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 user's interaction is assumed to occur on a secondary device. In
this example it is assumed that the user is both the end-user and RO, this example it is assumed that the user is both the end user and RO,
though the user is not assumed to be interacting with the client though the user is not assumed to be interacting with the client
instance through the same web browser used for interaction at the AS. instance through the same web browser used for interaction at the AS.
+--------+ +--------+ +------+ +--------+ +--------+ +------+
| Client | | AS | | User | | Client | | AS | | User |
|Instance|--(1)--- Request Access --------->| | | | |Instance|--(1)--- Request Access --------->| | | |
| | | | | | | | | | | |
| |<-(2)-- Interaction Needed -------| | | | | |<-(2)-- Interaction Needed -------| | | |
| | | | | | | | | | | |
| |+ (3) + + Display User Code + + + + + + + + + + + + >| | | |+ (3) + + Display User Code + + + + + + + + + + + + >| |
skipping to change at page 19, line 10 skipping to change at page 19, line 10
| | | | | | | | | | | |
| |<-(14)-- API Response ---------------------------| | | |<-(14)-- API Response ---------------------------| |
| | | | +--------+ | | | | +--------+
+--------+ +--------+ +--------+ +--------+
1. The client instance requests access to the resource (Section 2). 1. The client instance requests access to the resource (Section 2).
The client instance indicates that it can display a user code The client instance indicates that it can display a user code
(Section 2.5.1.3). (Section 2.5.1.3).
2. The AS determines that interaction is needed and responds 2. The AS determines that interaction is needed and responds
(Section 3) with a user code to communicate to the user (Section 3) with a user code to communicate to the user
(Section 3.3.3). This could optionally include a URL to direct (Section 3.3.3). This could optionally include a URI to direct
the user to, but this URL should be static and so could be the user to, but this URI should be static and so could be
configured in the client instance's documentation. The AS also configured in the client instance's documentation. The AS also
includes information the client instance will need to continue includes information the client instance will need to continue
the request (Section 3.1) in (8) and (10). The AS associates the request (Section 3.1) in (8) and (10). The AS associates
this continuation information with an ongoing request that will this continuation information with an ongoing request that will
be referenced in (4), (6), (8), and (10). be referenced in (4), (6), (8), and (10).
3. The client instance stores the continuation information from (2) 3. The client instance stores the continuation information from (2)
for use in (8) and (10). The client instance then communicates for use in (8) and (10). The client instance then communicates
the code to the user (Section 4.1.1) given by the AS in (2). the code to the user (Section 4.1.2) given by the AS in (2).
4. The user's directs their browser to the user code URL. This URL 4. The users directs their browser to the user code URI. This URI
is stable and can be communicated via the client software's is stable and can be communicated via the client software's
documentation, the AS documentation, or the client software documentation, the AS documentation, or the client software
itself. Since it is assumed that the RO will interact with the itself. Since it is assumed that the RO will interact with the
AS through a secondary device, the client instance does not AS through a secondary device, the client instance does not
provide a mechanism to launch the RO's browser at this URL. provide a mechanism to launch the RO's browser at this URI.
5. The end-user authenticates at the AS, taking on the role of the 5. The end user authenticates at the AS, taking on the role of the
RO. RO.
6. The RO enters the code communicated in (3) to the AS. The AS 6. The RO enters the code communicated in (3) to the AS. The AS
validates this code against a current request in process. validates this code against a current request in process.
7. As the RO, the user authorizes the pending request from the 7. As the RO, the user authorizes the pending request from the
client instance. client instance.
8. When the AS is done interacting with the user, the AS indicates 8. When the AS is done interacting with the user, the AS indicates
to the RO that the request has been completed. to the RO that the request has been completed.
skipping to change at page 20, line 26 skipping to change at page 20, line 26
13. The client instance uses the access token (Section 7.2) to call 13. The client instance uses the access token (Section 7.2) to call
the RS. the RS.
14. The RS validates the access token and returns an appropriate 14. The RS validates the access token and returns an appropriate
response for the API. response for the API.
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.2. Appendix D.2.
1.5.3. Asynchronous Authorization 1.5.4. Asynchronous Authorization
In this example flow, the end-user and RO roles are fulfilled by In this example flow, the end user and RO roles are fulfilled by
different parties, and the RO does not interact with the client different parties, and the RO does not interact with the client
instance. The AS reaches out asynchronously to the RO during the instance. The AS reaches out asynchronously to the RO during the
request process to gather the RO's authorization for the client request process to gather the RO's authorization for the client
instance's request. The client instance polls the AS while it is instance's request. The client instance polls the AS while it is
waiting for the RO to authorize the request. waiting for the RO to authorize the request.
+--------+ +--------+ +------+ +--------+ +--------+ +------+
| Client | | AS | | RO | | Client | | AS | | RO |
|Instance|--(1)--- Request Access --------->| | | | |Instance|--(1)--- Request Access --------->| | | |
| | | | | | | | | | | |
skipping to change at page 21, line 31 skipping to change at page 21, line 31
| |<-(9)------ Grant Access ---------| | | |<-(9)------ Grant Access ---------| |
| | | | | | | |
| | | | +--------+ | | | | +--------+
| |--(10)-- Access API ---------------------------->| RS | | |--(10)-- Access API ---------------------------->| RS |
| | | | | | | | | | | |
| |<-(11)-- API Response ---------------------------| | | |<-(11)-- API Response ---------------------------| |
| | | | +--------+ | | | | +--------+
+--------+ +--------+ +--------+ +--------+
1. The client instance requests access to the resource (Section 2). 1. The client instance requests access to the resource (Section 2).
The client instance does not send any interactions modes to the The client instance does not send any interaction modes to the
server, indicating that it does not expect to interact with the server, indicating that it does not expect to interact with the
RO. The client instance can also signal which RO it requires RO. The client instance can also signal which RO it requires
authorization from, if known, by using the user request section authorization from, if known, by using the user request section
(Section 2.4). (Section 2.4).
2. The AS determines that interaction is needed, but the client 2. The AS determines that interaction is needed, but the client
instance cannot interact with the RO. The AS responds instance cannot interact with the RO. The AS responds
(Section 3) with the information the client instance will need (Section 3) with the information the client instance will need
to continue the request (Section 3.1) in (6) and (8), including to continue the request (Section 3.1) in (6) and (8), including
a signal that the client instance should wait before checking a signal that the client instance should wait before checking
skipping to change at page 22, line 40 skipping to change at page 22, line 40
10. The client instance uses the access token (Section 7.2) to call 10. The client instance uses the access token (Section 7.2) to call
the RS. the RS.
11. The RS validates the access token and returns an appropriate 11. The RS validates the access token and returns an appropriate
response for the API. response for the API.
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.4. Appendix D.4.
1.5.4. Software-only Authorization 1.5.5. Software-only Authorization
In this example flow, the AS policy allows the client instance to In this example flow, the AS policy allows the client instance to
make a call on its own behalf, without the need for a RO to be make a call on its own behalf, without the need for an RO to be
involved at runtime to approve the decision. Since there is no involved at runtime to approve the decision. Since there is no
explicit RO, the client instance does not interact with an RO. explicit RO, the client instance does not interact with an RO.
+--------+ +--------+ +--------+ +--------+
| Client | | AS | | Client | | AS |
|Instance|--(1)--- Request Access --->| | |Instance|--(1)--- Request Access --->| |
| | | | | | | |
| |<-(2)---- Grant Access -----| | | |<-(2)---- Grant Access -----| |
| | | | +--------+ | | | | +--------+
| |--(3)--- Access API ------------------->| RS | | |--(3)--- Access API ------------------->| RS |
| | | | | | | | | | | |
| |<-(4)--- API Response ------------------| | | |<-(4)--- API Response ------------------| |
| | | | +--------+ | | | | +--------+
+--------+ +--------+ +--------+ +--------+
1. The client instance requests access to the resource (Section 2). 1. The client instance requests access to the resource (Section 2).
The client instance does not send any interactions modes to the The client instance does not send any interaction modes to the
server. server.
2. The AS determines that the request is been authorized, the AS 2. The AS determines that the request has been authorized, the AS
grants access to the information in the form of access tokens grants access to the resource in the form of access tokens
(Section 3.2) to the client instance. Note that direct subject (Section 3.2) to the client instance. Note that direct subject
information (Section 3.4) is not generally applicable in this use information (Section 3.4) is not generally applicable in this use
case, as there is no user involved. case, as there is no user involved.
3. The client instance uses the access token (Section 7.2) to call 3. The client instance uses the access token (Section 7.2) to call
the RS. the RS.
4. The RS validates the access token and returns an appropriate 4. The RS validates the access token and returns an appropriate
response for the API. response for the API.
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.3. Appendix D.3.
1.5.5. Refreshing an Expired Access Token 1.5.6. Refreshing an Expired Access Token
In this example flow, the client instance receives an access token to In this example flow, the client instance receives an access token to
access a resource server through some valid GNAP process. The client access a resource server through some valid GNAP process. The client
instance uses that token at the RS for some time, but eventually the instance uses that token at the RS for some time, but eventually the
access token expires. The client instance then gets a new access access token expires. The client instance then gets a new access
token by rotating the expired access token at the AS using the token by rotating the expired access token at the AS using the
token's management URL. token's management URI.
+--------+ +--------+ +--------+ +--------+
| Client | | AS | | Client | | AS |
|Instance|--(1)--- Request Access ----------------->| | |Instance|--(1)--- Request Access ----------------->| |
| | | | | | | |
| |<-(2)--- Grant Access --------------------| | | |<-(2)--- Grant Access --------------------| |
| | | | | | | |
| | +--------+ | | | | +--------+ | |
| |--(3)--- Access Resource --->| RS | | | | |--(3)--- Access Resource --->| RS | | |
| | | | | | | | | | | |
skipping to change at page 24, line 45 skipping to change at page 24, line 45
3. The client instance uses the access token (Section 7.2) to call 3. The client instance uses the access token (Section 7.2) to call
the RS. the RS.
4. The RS validates the access token and returns an appropriate 4. The RS validates the access token and returns an appropriate
response for the API. response for the API.
5. Time passes and the client instance uses the access token to call 5. Time passes and the client instance uses the access token to call
the RS again. the RS again.
6. The RS validates the access token and determines that the access 6. The RS validates the access token and determines that the access
token is expired The RS responds to the client instance with an token is expired. The RS responds to the client instance with an
error. error.
7. The client instance calls the token management URI returned in 7. The client instance calls the token management URI returned in
(2) to rotate the access token (Section 6.1). The client (2) to rotate the access token (Section 6.1). The client
instance uses the access token (Section 7.2) in this call as well instance uses the access token (Section 7.2) in this call as well
as the appropriate key, see the token rotation section for as the appropriate key, see the token rotation section for
details. details.
8. The AS validates the rotation request including the signature and 8. The AS validates the rotation request including the signature and
keys presented in (5) and returns a new access token keys presented in (5) and returns a new access token
(Section 3.2.1). The response includes a new access token and (Section 3.2.1). The response includes a new access token and
can also include updated token management information, which the can also include updated token management information, which the
client instance will store in place of the values returned in client instance will store in place of the values returned in
(2). (2).
1.5.6. Requesting User Information 1.5.7. Requesting User Information
In this scenario, the client instance does not call an RS and does In this scenario, the client instance does not call an RS and does
not request an access token. Instead, the client instance only not request an access token. Instead, the client instance only
requests and is returned direct subject information (Section 3.4). requests and is returned direct subject information (Section 3.4).
Many different interaction modes can be used in this scenario, so Many different interaction modes can be used in this scenario, so
these are shown only in the abstract as functions of the AS here. these are shown only in the abstract as functions of the AS here.
+--------+ +--------+ +------+ +--------+ +--------+ +------+
| Client | | AS | | User | | Client | | AS | | User |
|Instance| | | | | |Instance| | | | |
skipping to change at page 26, line 27 skipping to change at page 26, line 27
requested direct subject information (Section 3.4) to the client requested direct subject information (Section 3.4) to the client
instance. At this stage, the user is generally considered instance. At this stage, the user is generally considered
"logged in" to the client instance based on the identifiers and "logged in" to the client instance based on the identifiers and
assertions provided by the AS. Note that the AS can restrict the assertions provided by the AS. Note that the AS can restrict the
subject information returned and it might not match what the subject information returned and it might not match what the
client instance requested, see the section on subject information client instance requested, see the section on subject information
for details. for details.
2. Requesting Access 2. Requesting Access
To start a request, the client instance sends JSON [RFC8259] document To start a request, the client instance sends a JSON [RFC8259]
with an object as its root. Each member of the request object document with an object as its root. Each member of the request
represents a different aspect of the client instance's request. Each object represents a different aspect of the client instance's
field is described in detail in a section below. request. Each field is described in detail in a section below.
access_token (object / array of objects) Describes the rights and access_token (object / array of objects): Describes the rights and
properties associated with the requested access token. properties associated with the requested access token. REQUIRED
Section 2.1 if requesting an access token. See Section 2.1.
subject (object) Describes the information about the RO that the subject (object): Describes the information about the RO that the
client instance is requesting to be returned directly in the client instance is requesting to be returned directly in the
response from the AS. Section 2.2 response from the AS. REQUIRED if requesting subject information.
See Section 2.2.
client (object / string) Describes the client instance that is client (object / string): Describes the client instance that is
making this request, including the key that the client instance making this request, including the key that the client instance
will use to protect this request and any continuation requests at will use to protect this request and any continuation requests at
the AS and any user-facing information about the client instance the AS and any user-facing information about the client instance
used in interactions. Section 2.3 used in interactions. REQUIRED. See Section 2.3.
user (object / string) Identifies the end-user to the AS in a manner user (object / string): Identifies the end user to the AS in a
that the AS can verify, either directly or by interacting with the manner that the AS can verify, either directly or by interacting
end-user to determine their status as the RO. Section 2.4 with the end user to determine their status as the RO. OPTIONAL.
See Section 2.4.
interact (object) Describes the modes that the client instance has interact (object): Describes the modes that the client instance
for allowing the RO to interact with the AS and modes for the supports for allowing the RO to interact with the AS and modes for
client instance to receive updates when interaction is complete. the client instance to receive updates when interaction is
Section 2.5 complete. REQUIRED if interaction is supported. See Section 2.5.
Additional members of this request object can be defined by Additional members of this request object can be defined by
extensions to this protocol as described in Section 2.6 extensions to this protocol as described in Section 2.6.
A non-normative example of a grant request is below: A non-normative example of a grant request is below:
{ {
"access_token": { "access_token": {
"access": [ "access": [
{ {
"type": "photo-api", "type": "photo-api",
"actions": [ "actions": [
"read", "read",
skipping to change at page 27, line 43 skipping to change at page 27, line 43
] ]
}, },
"client": { "client": {
"display": { "display": {
"name": "My Client Display Name", "name": "My Client Display Name",
"uri": "https://example.net/client" "uri": "https://example.net/client"
}, },
"key": { "key": {
"proof": "httpsig", "proof": "httpsig",
"jwk": { "jwk": {
"kty": "RSA", "kty": "RSA",
"e": "AQAB", "e": "AQAB",
"kid": "xyz-1", "kid": "xyz-1",
"alg": "RS256", "alg": "RS256",
"n": "kOB5rR4Jv0GMeL...." "n": "kOB5rR4Jv0GMeL...."
} }
} }
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"uri": "https://client.example.net/return/123455", "uri": "https://client.example.net/return/123455",
"nonce": "LKLTI25DK82FX4T4QFZC" "nonce": "LKLTI25DK82FX4T4QFZC"
} }
}, },
"subject": { "subject": {
"formats": ["iss_sub", "opaque"], "sub_id_formats": ["iss_sub", "opaque"],
"assertions": ["id_token"] "assertion_formats": ["id_token"]
} }
} }
The request and response MUST be sent as a JSON object in the body of The request and response MUST be sent as a JSON object in the body of
the HTTP POST request with Content-Type application/json, unless the HTTP POST request with Content-Type application/json, unless
otherwise specified by the signature mechanism. otherwise specified by the signature mechanism.
The authorization server MUST include the HTTP "Cache-Control" The authorization server MUST include the HTTP "Cache-Control"
response header field [RFC7234] with a value set to "no-store". response header field [RFC7234] with a value set to "no-store".
skipping to change at page 28, line 38 skipping to change at page 28, line 38
access_token field. This field MUST be an object (for a single access_token field. This field MUST be an object (for a single
access token (Section 2.1.1)) or an array of these objects (for access token (Section 2.1.1)) or an array of these objects (for
multiple access tokens (Section 2.1.2)), as described in the multiple access tokens (Section 2.1.2)), as described in the
following sections. following sections.
2.1.1. Requesting a Single Access Token 2.1.1. Requesting a Single Access Token
To request a single access token, the client instance sends an To request a single access token, the client instance sends an
acccess_token object composed of the following fields. acccess_token object composed of the following fields.
access (array of objects/strings) Describes the rights that the access (array of objects/strings): Describes the rights that the
client instance is requesting for one or more access tokens to be client instance is requesting for one or more access tokens to be
used at RS's. This field is REQUIRED. Section 8 used at RS's. REQUIRED. See Section 8.
label (string) A unique name chosen by the client instance to refer label (string): A unique name chosen by the client instance to refer
to the resulting access token. The value of this field is opaque to the resulting access token. The value of this field is opaque
to the AS. If this field is included in the request, the AS MUST to the AS. If this field is included in the request, the AS MUST
include the same label in the token response (Section 3.2). This include the same label in the token response (Section 3.2).
field is REQUIRED if used as part of a multiple access token REQUIRED if used as part of a multiple access token request
request (Section 2.1.2), and is OPTIONAL otherwise. (Section 2.1.2), OPTIONAL otherwise.
flags (array of strings) A set of flags that indicate desired flags (array of strings): A set of flags that indicate desired
attributes or behavior to be attached to the access token by the attributes or behavior to be attached to the access token by the
AS. This field is OPTIONAL. AS. OPTIONAL.
The values of the flags field defined by this specification are as The values of the flags field defined by this specification are as
follows: follows:
"bearer" If this flag is included, the access token being requested "bearer": If this flag is included, the access token being requested
is a bearer token. If this flag is omitted, the access token is is a bearer token. If this flag is omitted, the access token is
bound to the key used by the client instance in this request (or bound to the key used by the client instance in this request (or
that key's most recent rotation) and the access token MUST be that key's most recent rotation) and the access token MUST be
presented using the same key and proofing method. Methods for presented using the same key and proofing method. Methods for
presenting bound and bearer access tokens are described in presenting bound and bearer access tokens are described in
Section 7.2. See Section 12.7 for additional considerations on Section 7.2. See Section 12.7 for additional considerations on
the use of bearer tokens. the use of bearer tokens.
"split" If this flag is included, the client instance is capable of "split": If this flag is included, the client instance is capable of
receiving a different number of tokens than specified in the token receiving a different number of tokens than specified in the token
request (Section 2.1), including receiving multiple access tokens request (Section 2.1), including 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 a different number of access tokens than (Section 2.1.1) or a different number of access tokens than
requested in a multiple access token request (Section 2.1.2). The requested in a multiple access token request (Section 2.1.2). The
label fields of the returned additional tokens are chosen by the label fields of the returned additional tokens are chosen by the
AS. The client instance MUST be able to tell from the token AS. The client instance MUST be able to tell from the token
response where and how it can use each of the access tokens. [[ response where and how it can use each of the access tokens. [[
See issue #37 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ See issue #37 (https://github.com/ietf-wg-gnap/gnap-core-protocol/
issues/37) ]] issues/37) ]]
skipping to change at page 33, line 15 skipping to change at page 33, line 15
token response (Section 3.2.2) structure using the values of the token response (Section 3.2.2) structure using the values of the
label fields in the request. label fields in the request.
2.2. Requesting Subject Information 2.2. Requesting Subject Information
If the client instance is requesting information about the RO from If the client instance is requesting information about the RO from
the AS, it sends a subject field as a JSON object. This object MAY the AS, it sends a subject field as a JSON object. This object MAY
contain the following fields (or additional fields defined in a contain the following fields (or additional fields defined in a
registry TBD (Section 11)). registry TBD (Section 11)).
formats (array of strings) An array of subject identifier subject sub_id_formats (array of strings): An array of subject identifier
types requested for the RO, as defined by subject formats requested for the RO, as defined by
[I-D.ietf-secevent-subject-identifiers]. [I-D.ietf-secevent-subject-identifiers]. REQUIRED if subject
identifiers are requested.
assertions (array of strings) An array of requested assertion assertion_formats (array of strings): An array of requested
formats. Possible values include id_token for an [OIDC] ID Token assertion formats. Possible values include id_token for an [OIDC]
and saml2 for a SAML 2 assertion. Additional assertion values are ID Token and saml2 for a SAML 2 assertion. Additional assertion
defined by a registry TBD (Section 11). [[ See issue #41 formats are defined by a registry TBD (Section 11). REQUIRED if
(https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/41) ]] assertions are requested.
"subject": { "subject": {
"formats": [ "iss_sub", "opaque" ], "sub_id_formats": [ "iss_sub", "opaque" ],
"assertions": [ "id_token", "saml2" ] "assertion_formats": [ "id_token", "saml2" ]
} }
The AS can determine the RO's identity and permission for releasing The AS can determine the RO's identity and permission for releasing
this information through interaction with the RO (Section 4), AS this information through interaction with the RO (Section 4), AS
policies, or assertions presented by the client instance policies, or assertions presented by the client instance
(Section 2.4). If this is determined positively, the AS MAY return (Section 2.4). If this is determined positively, the AS MAY return
the RO's information in its response (Section 3.4) as requested. the RO's information in its response (Section 3.4) as requested.
Subject identifier types requested by the client instance serve only Subject identifier types requested by the client instance serve only
to identify the RO in the context of the AS and can't be used as to identify the RO in the context of the AS and can't be used as
communication channels by the client instance, as discussed in communication channels by the client instance, as discussed in
Section 3.4. Section 3.4.
The AS SHOULD NOT re-use subject identifiers for multiple different The AS SHOULD NOT re-use subject identifiers for multiple different
ROs. ROs.
Note: the "formats" and "assertions" request fields are independent The "formats" and "assertions" request fields are independent of each
of each other, and a returned assertion MAY use a different subject other, and a returned assertion MAY use a different subject
identifier. identifier than other assertions and subject identifiers in the
response. All subject identifiers and assertions returned MUST refer
[[ See issue #43 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ to the same person.
issues/43) ]]
2.3. Identifying the Client Instance 2.3. Identifying the Client Instance
When sending a non-continuation request to the AS, the client When sending a non-continuation request to the AS, the client
instance MUST identify itself by including the client field of the instance MUST identify itself by including the client field of the
request and by signing the request as described in Section 7.3. Note request and by signing the request as described in Section 7.3. Note
that for a continuation request (Section 5), the client instance is that for a continuation request (Section 5), the client instance is
identified by its association with the request being continued and so identified by its association with the request being continued and so
this field is not sent under those circumstances. this field is not sent under those circumstances.
When client instance information is sent by value, the client field When client instance information is sent by value, the client field
of the request consists of a JSON object with the following fields. of the request consists of a JSON object with the following fields.
key (object / string) The public key of the client instance to be key (object / string): The public key of the client instance to be
used in this request as described in Section 7.1 or a reference to used in this request as described in Section 7.1 or a reference to
a key as described in Section 7.1.1. This field is REQUIRED. a key as described in Section 7.1.1. REQUIRED.
class_id (string) An identifier string that the AS can use to class_id (string): An identifier string that the AS can use to
identify the client software comprising this client instance. The identify the client software comprising this client instance. The
contents and format of this field are up to the AS. This field is contents and format of this field are up to the AS. OPTIONAL.
OPTIONAL.
display (object) An object containing additional information that display (object): An object containing additional information that
the AS MAY display to the RO during interaction, authorization, the AS MAY display to the RO during interaction, authorization,
and management. This field is OPTIONAL. and management. OPTIONAL.
"client": { "client": {
"key": { "key": {
"proof": "httpsig", "proof": "httpsig",
"jwk": { "jwk": {
"kty": "RSA", "kty": "RSA",
"e": "AQAB", "e": "AQAB",
"kid": "xyz-1", "kid": "xyz-1",
"alg": "RS256", "alg": "RS256",
"n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8..." "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8..."
}, },
"cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..."
}, },
"class_id": "web-server-1234", "class_id": "web-server-1234",
"display": { "display": {
"name": "My Client Display Name", "name": "My Client Display Name",
"uri": "https://example.net/client" "uri": "https://example.net/client"
} }
} }
Additional fields are defined in a registry TBD (Section 11). Additional fields are defined in a registry TBD (Section 11).
The client instance MUST prove possession of any presented key by the The client instance MUST prove possession of any presented key by the
proof mechanism associated with the key in the request. Proof types proof mechanism associated with the key in the request. Proof types
are defined in a registry TBD (Section 11) and an initial set of are defined in a registry TBD (Section 11) and an initial set of
methods is described in Section 7.3. methods is described in Section 7.3.
If the same public key is sent by value on different access requests, If the same public key is sent by value on different access requests,
the AS MUST treat these requests as coming from the same client the AS MUST treat these requests as coming from the same client
skipping to change at page 35, line 37 skipping to change at page 35, line 37
time and associated with a set of policies and allowable actions time and associated with a set of policies and allowable actions
pertaining to that client. If this pre-registration includes other pertaining to that client. If this pre-registration includes other
fields that can occur in the client request object described in this fields that can occur in the client request object described in this
section, such as class_id or display, the pre-registered values MUST section, such as class_id or display, the pre-registered values MUST
take precedence over any values given at runtime. Additional fields take precedence over any values given at runtime. Additional fields
sent during a request but not present in a pre-registered client sent during a request but not present in a pre-registered client
instance record at the AS SHOULD NOT be added to the client's pre- instance record at the AS SHOULD NOT be added to the client's pre-
registered record. See additional considerations regarding client registered record. See additional considerations regarding client
instance impersonation in Section 12.13. instance impersonation in Section 12.13.
A client instance that is capable of talking to multiple AS's SHOULD
use a different key for each AS to prevent a class of mix-up attacks
as described in Section 12.28.
2.3.1. Identifying the Client Instance by Reference 2.3.1. Identifying the Client Instance by Reference
If the client instance has an instance identifier that the AS can use If the client instance has an instance identifier that the AS can use
to determine appropriate key information, the client instance can to determine appropriate key information, the client instance can
send this instance identifier as a direct reference value in lieu of send this instance identifier as a direct reference value in lieu of
the client object. The instance identifier MAY be assigned to a the client object. The instance identifier MAY be assigned to a
client instance at runtime through the Section 3.5 or MAY be obtained client instance at runtime through a grant response (Section 3.5) or
in another fashion, such as a static registration process at the AS. MAY be obtained in another fashion, such as a static registration
process at the AS.
"client": "client-541-ab" "client": "client-541-ab"
When the AS receives a request with an instance identifier, the AS When the AS receives a request with an instance identifier, the AS
MUST ensure that the key used to sign the request (Section 7.3) is MUST ensure that the key used to sign the request (Section 7.3) is
associated with the instance identifier. associated with the instance identifier.
If the AS does not recognize the instance identifier, the request If the AS does not recognize the instance identifier, the request
MUST be rejected with an error. MUST be rejected with an error.
If the client instance is identified in this manner, the registered If the client instance is identified in this manner, the registered
key for the client instance MAY be a symmetric key known to the AS. key for the client instance MAY be a symmetric key known to the AS.
See considerations on symmetric keys in Section 12.5. See considerations on symmetric keys in Section 12.5.
skipping to change at page 36, line 19 skipping to change at page 36, line 22
key for the client instance MAY be a symmetric key known to the AS. key for the client instance MAY be a symmetric key known to the AS.
See considerations on symmetric keys in Section 12.5. See considerations on symmetric keys in Section 12.5.
2.3.2. Providing Displayable Client Instance Information 2.3.2. Providing Displayable Client Instance Information
If the client instance has additional information to display to the If the client instance has additional information to display to the
RO during any interactions at the AS, it MAY send that information in RO during any interactions at the AS, it MAY send that information in
the "display" field. This field is a JSON object that declares the "display" field. This field is a JSON object that declares
information to present to the RO during any interactive sequences. information to present to the RO during any interactive sequences.
name (string) Display name of the client software name (string): Display name of the client software. RECOMMENDED.
uri (string) User-facing web page of the client software uri (string): User-facing web page of the client software.
OPTIONAL.
logo_uri (string) Display image to represent the client software logo_uri (string) Display image to represent the client software.
The logo MAY be passed by value by using a data: URI [RFC2397]
referencing an image mediatype. OPTIONAL.
"display": { "display": {
"name": "My Client Display Name", "name": "My Client Display Name",
"uri": "https://example.net/client" "uri": "https://example.net/client",
"logo_uri": "data:image/png;base64,Eeww...="
} }
[[ See issue #48 (https://github.com/ietf-wg-gnap/gnap-core-protocol/
issues/48) ]]
Additional display fields are defined by a registry TBD (Section 11). Additional display fields are defined by a registry TBD (Section 11).
The AS SHOULD use these values during interaction with the RO. The The AS SHOULD use these values during interaction with the RO. The
values are for informational purposes only and MUST NOT be taken as values are for informational purposes only and MUST NOT be taken as
authentic proof of the client instance's identity or source. The AS authentic proof of the client instance's identity or source. The AS
MAY restrict display values to specific client instances, as MAY restrict display values to specific client instances, as
identified by their keys in Section 2.3. See additional identified by their keys in Section 2.3. See additional
considerations for displayed client information in Section 12.13. considerations for displayed client information in Section 12.13.
2.3.3. Authenticating the Client Instance 2.3.3. Authenticating the Client Instance
skipping to change at page 37, line 24 skipping to change at page 37, line 36
pairs per instance and use the keys within the protocol without pairs per instance and use the keys within the protocol without
having to go through a separate registration step. The AS MAY limit having to go through a separate registration step. The AS MAY limit
which capabilities are made available to client instances with which capabilities are made available to client instances with
unknown keys. For example, the AS could have a policy saying that unknown keys. For example, the AS could have a policy saying that
only previously-registered client instances can request particular only previously-registered client instances can request particular
resources, or that all client instances with unknown keys have to be resources, or that all client instances with unknown keys have to be
interactively approved by an RO. interactively approved by an RO.
2.4. Identifying the User 2.4. Identifying the User
If the client instance knows the identity of the end-user through one If the client instance knows the identity of the end user through one
or more identifiers or assertions, the client instance MAY send that or more identifiers or assertions, the client instance MAY send that
information to the AS in the "user" field. The client instance MAY information to the AS in the "user" field. The client instance MAY
pass this information by value or by reference. pass this information by value or by reference.
sub_ids (array of objects) An array of subject identifiers for the sub_ids (array of objects): An array of subject identifiers for the
end-user, as defined by [I-D.ietf-secevent-subject-identifiers]. end user, as defined by [I-D.ietf-secevent-subject-identifiers].
OPTIONAL.
assertions (object) An object containing assertions as values keyed assertions (array of objects) An array containing assertions as
on the assertion type defined by a registry TBD (Section 11). objects each containing the assertion format and the assertion
Possible keys include id_token for an [OIDC] ID Token and saml2 value as the JSON string serialization of the assertion.
for a SAML 2 assertion. The assertion values are the string OPTIONAL.
serialization of the assertion format, encoded as a plain JSON
string. Additional assertion types are defined by a registry TBD
(Section 11). [[ See issue #41 (https://github.com/ietf-wg-gnap/
gnap-core-protocol/issues/41) ]]
"user": { "user": {
"sub_ids": [ { "sub_ids": [ {
"format": "opaque", "format": "opaque",
"id": "J2G8G8O4AZ" "id": "J2G8G8O4AZ"
} ], } ],
"assertions": { "assertions": [ {
"id_token": "eyj..." "format": "id_token",
} "value": "eyj..."
} ]
} }
Subject identifiers are hints to the AS in determining the RO and Subject identifiers are hints to the AS in determining the RO and
MUST NOT be taken as declarative statements that a particular RO is MUST NOT be taken as declarative statements that a particular RO is
present at the client instance and acting as the end-user. present at the client instance and acting as the end user.
Assertions SHOULD be validated by the AS. [[ See issue #49 Assertions SHOULD be validated by the AS. [[ See issue #49
(https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/49) ]] (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/49) ]]
If the identified end-user does not match the RO present at the AS If the identified end user does not match the RO present at the AS
during an interaction step, the AS SHOULD reject the request with an during an interaction step, the AS SHOULD reject the request with an
error. error.
[[ See issue #50 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ [[ See issue #50 (https://github.com/ietf-wg-gnap/gnap-core-protocol/
issues/50) ]] issues/50) ]]
If the AS trusts the client instance to present verifiable If the AS trusts the client instance to present verifiable
assertions, the AS MAY decide, based on its policy, to skip assertions, the AS MAY decide, based on its policy, to skip
interaction with the RO, even if the client instance provides one or interaction with the RO, even if the client instance provides one or
more interaction modes in its request. more interaction modes in its request.
See Section 12.25 for considerations that the AS has to make when See Section 12.27 for considerations that the AS has to make when
accepting and processing assertions from the client instance. accepting and processing assertions from the client instance.
2.4.1. Identifying the User by Reference 2.4.1. Identifying the User by Reference
The AS can identify the current end-user to the client instance with The AS can identify the current end user to the client instance with
a reference which can be used by the client instance to refer to the a reference which can be used by the client instance to refer to the
end-user across multiple requests. If the client instance has a end user across multiple requests. If the client instance has a
reference for the end-user at this AS, the client instance MAY pass reference for the end user at this AS, the client instance MAY pass
that reference as a string. The format of this string is opaque to that reference as a string. The format of this string is opaque to
the client instance. the client instance.
"user": "XUT2MFM1XBIKJKSDU8QM" "user": "XUT2MFM1XBIKJKSDU8QM"
One means of dynamically obtaining such a user reference is from the One means of dynamically obtaining such a user reference is from the
AS returning an opaque subject identifier as described in AS returning an opaque subject identifier as described in
Section 3.4. Other means of configuring a client instance with a Section 3.4. Other means of configuring a client instance with a
user identifier are out of scope of this specification. user identifier are out of scope of this specification.
skipping to change at page 39, line 10 skipping to change at page 39, line 18
instead. instead.
If the AS does not recognize the user reference, it MUST return an If the AS does not recognize the user reference, it MUST return an
error. error.
2.5. Interacting with the User 2.5. Interacting with the User
Often, the AS will require interaction with the RO (Section 4) in Often, the AS will require interaction with the RO (Section 4) in
order to approve a requested delegation to the client instance for order to approve a requested delegation to the client instance for
both access to resources and direct subject information. Many times both access to resources and direct subject information. Many times
the end-user using the client instance is the same person as the RO, the end user using the client instance is the same person as the RO,
and the client instance can directly drive interaction with the end and the client instance can directly drive interaction with the end
user by facilitating the process through means such as redirection to user by facilitating the process through means such as redirection to
a URL or launching an application. Other times, the client instance a URI or launching an application. Other times, the client instance
can provide information to start the RO's interaction on a secondary can provide information to start the RO's interaction on a secondary
device, or the client instance will wait for the RO to approve the device, or the client instance will wait for the RO to approve the
request asynchronously. The client instance could also be signaled request asynchronously. The client instance could also be signaled
that interaction has concluded through a callback mechanism. that interaction has concluded through a callback mechanism.
The client instance declares the parameters for interaction methods The client instance declares the parameters for interaction methods
that it can support using the interact field. that it can support using the interact field.
The interact field is a JSON object with three keys whose values The interact field is a JSON object with three keys whose values
declare how the client can initiate and complete the request, as well declare how the client can initiate and complete the request, as well
as provide hints to the AS about user preferences such as locale. A as provide hints to the AS about user preferences such as locale. A
client instance MUST NOT declare an interaction mode it does not client instance MUST NOT declare an interaction mode it does not
support. The client instance MAY send multiple modes in the same support. The client instance MAY send multiple modes in the same
request. There is no preference order specified in this request. An request. There is no preference order specified in this request. An
AS MAY respond to any, all, or none of the presented interaction AS MAY respond to any, all, or none of the presented interaction
modes (Section 3.3) in a request, depending on its capabilities and modes (Section 3.3) in a request, depending on its capabilities and
what is allowed to fulfill the request. what is allowed to fulfill the request.
start (list of strings/objects) Indicates how the client instance start (array of strings/objects): Indicates how the client instance
can start an interaction. can start an interaction. REQUIRED.
finish (object) Indicates how the client instance can receive an
indication that interaction has finished at the AS.
hints (object) Provides additional information to inform the finish (object): Indicates how the client instance can receive an
interaction process at the AS. indication that interaction has finished at the AS. OPTIONAL.
The interact field MUST contain the start key, and MAY contain the hints (object): Provides additional information to inform the
finish and hints keys. The value of each key is an array which interaction process at the AS. OPTIONAL.
contains strings or JSON objects as defined below.
In this non-normative example, the client instance is indicating that In this non-normative example, the client instance is indicating that
it can redirect (Section 2.5.1.1) the end-user to an arbitrary URL it can redirect (Section 2.5.1.1) the end user to an arbitrary URI
and can receive a redirect (Section 2.5.2.1) through a browser and can receive a redirect (Section 2.5.2.1) through a browser
request. request.
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
"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 client instance is indicating that In this non-normative example, the client instance is indicating that
it can display a user code (Section 2.5.1.3) and direct the end-user it can display a user code (Section 2.5.1.3) and direct the end user
to an arbitrary URL (Section 2.5.1.1) on a secondary device, but it to an arbitrary URI (Section 2.5.1.1) on a secondary device, but it
cannot accept a redirect or push callback. cannot accept a redirect or push callback.
"interact": { "interact": {
"start": ["redirect", "user_code"] "start": ["redirect", "user_code"]
} }
If the client instance does not provide a suitable interaction If the client instance does not provide a suitable interaction
mechanism, the AS cannot contact the RO asynchronously, and the AS mechanism, the AS cannot contact the RO asynchronously, and the AS
determines that interaction is required, then the AS SHOULD return an determines that interaction is required, then the AS SHOULD return an
error since the client instance will be unable to complete the error since the client instance will be unable to complete the
request without authorization. request without authorization.
The AS SHOULD apply suitable timeouts to any interaction mechanisms The AS SHOULD handle any interact request as a one-time-use mechanism
provided, including user codes and redirection URLs. The client and SHOULD apply suitable timeouts to any interaction mechanisms
instance SHOULD apply suitable timeouts to any callback URLs. provided, including user codes and redirection URIs. The client
instance SHOULD apply suitable timeouts to any callback URIs.
2.5.1. Start Mode Definitions 2.5.1. Start Mode Definitions
This specification defines the following interaction start modes as This specification defines the following interaction start modes as
an array of string values under the start key: an array of string values under the start key:
"redirect" Indicates that the client instance can direct the end- "redirect": Indicates that the client instance can direct the end
user to an arbitrary URL for interaction. Section 2.5.1.1 user to an arbitrary URI for interaction. Section 2.5.1.1
"app" Indicates that the client instance can launch an application "app": Indicates that the client instance can launch an application
on the end-user's device for interaction. Section 2.5.1.2 on the end user's device for interaction. Section 2.5.1.2
"user_code" Indicates that the client instance can communicate a "user_code": Indicates that the client instance can communicate a
human-readable short code to the end-user for use with a stable human-readable short code to the end user for use with a stable
URL. Section 2.5.1.3 URI. Section 2.5.1.3
2.5.1.1. Redirect to an Arbitrary URL "user_code_uri": Indicates that the client instance can communicate
a human-readable short code to the end user for use with a short,
dynamic URI. Section 2.5.1.4
If the client instance is capable of directing the end-user to a URL 2.5.1.1. Redirect to an Arbitrary URI
If the client instance is capable of directing the end user to a URI
defined by the AS at runtime, the client instance indicates this by defined by the AS at runtime, the client instance indicates this by
including redirect in the array under the start key. The means by including redirect in the array under the start key. The means by
which the client instance will activate this URL is out of scope of which the client instance will activate this URI is out of scope of
this specification, but common methods include an HTTP redirect, this specification, but common methods include an HTTP redirect,
launching a browser on the end-user's device, providing a scannable launching a browser on the end user's device, providing a scannable
image encoding, and printing out a URL to an interactive console. image encoding, and printing out a URI to an interactive console.
While this URL is generally hosted at the AS, the client instance can While this URI is generally hosted at the AS, the client instance can
make no assumptions about its contents, composition, or relationship make no assumptions about its contents, composition, or relationship
to the AS grant URL. to the AS grant URI.
"interact": { "interact": {
"start": ["redirect"] "start": ["redirect"]
} }
If this interaction mode is supported for this client instance and If this interaction mode is supported for this client instance and
request, the AS returns a redirect interaction response request, the AS returns a redirect interaction response
Section 3.3.1. The client instance manages this interaction method Section 3.3.1. The client instance manages this interaction method
as described in Section 4.1.1. as described in Section 4.1.1.
See Section 12.24 for more considerations regarding the use of front- See Section 12.26 for more considerations regarding the use of front-
channel communication techniques such as this. channel communication techniques such as this.
2.5.1.2. Open an Application-specific URL 2.5.1.2. Open an Application-specific URI
If the client instance can open a URL associated with an application If the client instance can open a URI associated with an application
on the end-user's device, the client instance indicates this by on the end user's device, the client instance indicates this by
including app in the array under the start key. The means by which including app in the array under the start key. The means by which
the client instance determines the application to open with this URL the client instance determines the application to open with this URI
are out of scope of this specification. are out of scope of this specification.
"interact": { "interact": {
"start": ["app"] "start": ["app"]
} }
If this interaction mode is supported for this client instance and If this interaction mode is supported for this client instance and
request, the AS returns an app interaction response with an app URL request, the AS returns an app interaction response with an app URI
payload Section 3.3.2. The client instance manages this interaction payload Section 3.3.2. The client instance manages this interaction
method as described in Section 4.1.3. method as described in Section 4.1.4.
[[ See issue #54 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ [[ See issue #54 (https://github.com/ietf-wg-gnap/gnap-core-protocol/
issues/54) ]] issues/54) ]]
2.5.1.3. Display a Short User Code 2.5.1.3. Display a Short User Code
If the client instance is capable of displaying or otherwise If the client instance is capable of displaying or otherwise
communicating a short, human-entered code to the RO, the client communicating a short, human-entered code to the RO, the client
instance indicates this by including user_code in the array under the instance indicates this by including user_code in the array under the
start key. This code is to be entered at a static URL that does not start key. This code is to be entered at a static URI that does not
change at runtime. While this URL is generally hosted at the AS, the change at runtime. The client instance has no reasonable means to
client instance can make no assumptions about its contents, communicate a dynamic URI to the RO, and so this URI is usually
composition, or relationship to the AS grant URL. communicated out of band to the RO through documentation or other
messaging outside of GNAP. While this URI is generally hosted at the
AS, the client instance can make no assumptions about its contents,
composition, or relationship to the AS grant URI.
"interact": { "interact": {
"start": ["user_code"] "start": ["user_code"]
} }
If this interaction mode is supported for this client instance and If this interaction mode is supported for this client instance and
request, the AS returns a user code as specified in Section 3.3.3.
The client instance manages this interaction method as described in
Section 4.1.2.
2.5.1.4. Display a Short User Code and URI
If the client instance is capable of displaying or otherwise
communicating a short, human-entered code along with a short, human-
entered URI to the RO, the client instance indicates this by
including user_code_uri in the array under the start key. This code
is to be entered at the dynamic URL given in the response. While
this URL is generally hosted at the AS, the client instance can make
no assumptions about its contents, composition, or relationship to
the AS grant URL.
"interact": {
"start": ["user_code_uri"]
}
If this interaction mode is supported for this client instance and
request, the AS returns a user code and interaction URL as specified request, the AS returns a user code and interaction URL as specified
in Section 3.3.3. The client instances manages this interaction in Section 3.3.4. The client instance manages this interaction
method as described in Section 4.1.2 method as described in Section 4.1.3.
2.5.2. Finish Interaction Modes 2.5.2. Finish Interaction Methods
If the client instance is capable of receiving a message from the AS If the client instance is capable of receiving a message from the AS
indicating that the RO has completed their interaction, the client indicating that the RO has completed their interaction, the client
instance indicates this by sending the following members of an object instance indicates this by sending the following members of an object
under the finish key. under the finish key.
method (string) REQUIRED. The callback method that the AS will use method (string): The callback method that the AS will use to contact
to contact the client instance. This specification defines the the client instance. REQUIRED.
following interaction completion methods, with other values
defined by a registry TBD (Section 11):
"redirect" Indicates that the client instance can receive a
redirect from the end-user's device after interaction with the
RO has concluded. Section 2.5.2.1
"push" Indicates that the client instance can receive an HTTP
POST request from the AS after interaction with the RO has
concluded. Section 2.5.2.2
uri (string) REQUIRED. Indicates the URI that the AS will either uri (string): Indicates the URI that the AS will either send the RO
send the RO to after interaction or send an HTTP POST request. to after interaction or send an HTTP POST request. This URI MAY
This URI MAY be unique per request and MUST be hosted by or be unique per request and MUST be hosted by or accessible by the
accessible by the client instance. This URI MUST NOT contain any client instance. This URI MUST NOT contain any fragment
fragment component. This URI MUST be protected by HTTPS, be component. This URI MUST be protected by HTTPS, be hosted on a
hosted on a server local to the RO's browser ("localhost"), or use server local to the RO's browser ("localhost"), or use an
an application-specific URI scheme. If the client instance needs application-specific URI scheme. If the client instance needs any
any state information to tie to the front channel interaction state information to tie to the front channel interaction
response, it MUST use a unique callback URI to link to that response, it MUST use a unique callback URI to link to that
ongoing state. The allowable URIs and URI patterns MAY be ongoing state. The allowable URIs and URI patterns MAY be
restricted by the AS based on the client instance's presented key restricted by the AS based on the client instance's presented key
information. The callback URI SHOULD be presented to the RO information. The callback URI SHOULD be presented to the RO
during the interaction phase before redirect. during the interaction phase before redirect. REQUIRED for
redirect and push methods.
nonce (string) REQUIRED. Unique value to be used in the calculation nonce (string): Unique value to be used in the calculation of the
of the "hash" query parameter sent to the callback URL, must be "hash" query parameter sent to the callback URI, must be
sufficiently random to be unguessable by an attacker. MUST be sufficiently random to be unguessable by an attacker. MUST be
generated by the client instance as a unique value for this generated by the client instance as a unique value for this
request. request. REQUIRED.
hash_method (string) OPTIONAL. The hash calculation mechanism to be hash_method (string): The hash calculation mechanism to be used for
used for the callback hash in Section 4.2.3. Can be one of sha3 the callback hash in Section 4.2.3. Can be one of sha3 or sha2.
or sha2. If absent, the default value is sha3. [[ See issue #56 If absent, the default value is sha3. OPTIONAL. [[ See issue #56
(https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/56) ]] (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/56) ]]
This specification defines the following values for the method
parameter, with other values defined by a registry TBD (Section 11):
"redirect": Indicates that the client instance can receive a
redirect from the end user's device after interaction with the RO
has concluded. Section 2.5.2.1
"push": Indicates that the client instance can receive an HTTP POST
request from the AS after interaction with the RO has concluded.
Section 2.5.2.2
If this interaction mode is supported for this client instance and If this interaction mode is supported for this client instance and
request, the AS returns a nonce for use in validating the callback request, the AS returns a nonce for use in validating the callback
response (Section 3.3.4). Requests to the callback URI MUST be response (Section 3.3.5). Requests to the callback URI MUST be
processed as described in Section 4.2, and the AS MUST require processed as described in Section 4.2, and the AS MUST require
presentation of an interaction callback reference as described in presentation of an interaction callback reference as described in
Section 5.1. Section 5.1.
[[ See issue #58 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ [[ See issue #58 (https://github.com/ietf-wg-gnap/gnap-core-protocol/
issues/58) ]] issues/58) ]]
2.5.2.1. Receive an HTTP Callback Through the Browser 2.5.2.1. Receive an HTTP Callback Through the Browser
A finish method value of redirect indicates that the client instance A finish method value of redirect indicates that the client instance
skipping to change at page 43, line 47 skipping to change at page 44, line 25
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"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 client instance Requests to the callback URI MUST be processed by the client instance
as described in Section 4.2.1. as described in Section 4.2.1.
Since the incoming request to the callback URL is from the RO's Since the incoming request to the callback URI is from the RO's
browser, this method is usually used when the RO and end-user are the browser, this method is usually used when the RO and end user are the
same entity. As such, the client instance MUST ensure the end-user same entity. See Section 12.22 for considerations on ensuring the
is present on the request to prevent substitution attacks. incoming HTTP message matches the expected context of the request.
See Section 12.26 for more considerations regarding the use of front-
See Section 12.24 for more considerations regarding the use of front-
channel communication techniques such as this. channel communication techniques such as this.
2.5.2.2. Receive an HTTP Direct Callback 2.5.2.2. Receive an HTTP Direct Callback
A finish method value of push indicates that the client instance will A finish method value of push indicates that the client instance will
expect a request from the AS directly using the HTTP method POST as expect a request from the AS directly using the HTTP method POST as
described in Section 4.2.2. described in Section 4.2.2.
"interact": { "interact": {
"finish": { "finish": {
"method": "push", "method": "push",
"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 client instance Requests to the callback URI MUST be processed by the client instance
as described in Section 4.2.2. as described in Section 4.2.2.
Since the incoming request to the callback URL is from the AS and not Since the incoming request to the callback URI is from the AS and not
from the RO's browser, the client instance MUST NOT require the end- from the RO's browser, this request is not expected to have any
user to be present on the incoming HTTP request. shared session information from the start method. See Section 12.22
and Section 12.21 for more considerations regarding the use of back-
channel and polling mechanisms like this.
2.5.3. Hints 2.5.3. Hints
The hints key is an object describing one or more suggestions from The hints key is an object describing one or more suggestions from
the client instance that the AS can use to help drive user the client instance that the AS can use to help drive user
interaction. interaction.
This specification defines the following properties under the hints This specification defines the following properties under the hints
key: key:
ui_locales (array of strings) Indicates the end-user's preferred ui_locales (array of strings): Indicates the end user's preferred
locales that the AS can use during interaction, particularly locales that the AS can use during interaction, particularly
before the RO has authenticated. Section 2.5.3.1 before the RO has authenticated. OPTIONAL. Section 2.5.3.1
The following sections detail requests for interaction modes. The following sections detail requests for interaction hints.
Additional interaction modes are defined in a registry TBD Additional interaction hints are defined in a registry TBD
(Section 11). (Section 11).
2.5.3.1. Indicate Desired Interaction Locales 2.5.3.1. Indicate Desired Interaction Locales
If the client instance knows the end-user's locale and language If the client instance knows the end user's locale and language
preferences, the client instance can send this information to the AS preferences, the client instance can send this information to the AS
using the ui_locales field with an array of locale strings as defined using the ui_locales field with an array of locale strings as defined
by [RFC5646]. by [RFC5646].
"interact": { "interact": {
"hints": { "hints": {
"ui_locales": ["en-US", "fr-CA"] "ui_locales": ["en-US", "fr-CA"]
} }
} }
skipping to change at page 45, line 33 skipping to change at page 46, line 17
The request object MAY be extended by registering new items in a The request object MAY be extended by registering new items in a
registry TBD (Section 11). Extensions SHOULD be orthogonal to other registry TBD (Section 11). Extensions SHOULD be orthogonal to other
parameters. Extensions MUST document any aspects where the extension parameters. Extensions MUST document any aspects where the extension
item affects or influences the values or behavior of other request item affects or influences the values or behavior of other request
and response objects. and response objects.
3. Grant Response 3. Grant Response
In response to a client instance's request, the AS responds with a In response to a client instance's request, the AS responds with a
JSON object as the HTTP entity body. Each possible field is detailed JSON object as the HTTP entity body. Each possible field is detailed
in the sections below in the sections below.
continue (object) Indicates that the client instance can continue continue (object): Indicates that the client instance can continue
the request by making one or more continuation requests. the request by making one or more continuation requests. REQUIRED
Section 3.1 if continuation calls are allowed for this client instance on this
grant request. See Section 3.1.
access_token (object / array of objects) A single access token or access_token (object / array of objects): A single access token or
set of access tokens that the client instance can use to call the set of access tokens that the client instance can use to call the
RS on behalf of the RO. Section 3.2.1 RS on behalf of the RO. REQUIRED if an access token is included.
See Section 3.2.
interact (object) Indicates that interaction through some set of interact (object): Indicates that interaction through some set of
defined mechanisms needs to take place. Section 3.3 defined mechanisms needs to take place. REQUIRED if interaction
is needed or allowed. See Section 3.3.
subject (object) Claims about the RO as known and declared by the subject (object): Claims about the RO as known and declared by the
AS, as described in Section 3.4. AS. REQUIRED if subject information is included. See
Section 3.4.
instance_id (string) An identifier this client instance can use to instance_id (string): An identifier this client instance can use to
identify itself when making future requests. Section 3.5 identify itself when making future requests. OPTIONAL. See
Section 3.5.
error (object) An error code indicating that something has gone error (object): An error code indicating that something has gone
wrong. Section 3.6 wrong. REQUIRED for an error condition. If included, other
fields MUST NOT be included. See Section 3.6.
In this example, the AS is returning an interaction URL In this example, the AS is returning an interaction URI
(Section 3.3.1), a callback nonce (Section 3.3.4), and a continuation (Section 3.3.1), a callback nonce (Section 3.3.5), and a continuation
response (Section 3.1). response (Section 3.1).
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
{ {
"interact": { "interact": {
"redirect": "https://server.example.com/interact/4CF492ML\ "redirect": "https://server.example.com/interact/4CF492ML\
VMSW9MKMXKHQ", VMSW9MKMXKHQ",
"finish": "MBDOFXG4Y5CVJCX821LH" "finish": "MBDOFXG4Y5CVJCX821LH"
}, },
"continue": { "continue": {
"access_token": { "access_token": {
"value": "80UPRY5NM33OMUKMKSKU", "value": "80UPRY5NM33OMUKMKSKU",
}, },
"uri": "https://server.example.com/tx" "uri": "https://server.example.com/tx"
} }
} }
In this example, the AS is returning a bearer access token In this example, the AS is returning a bearer access token
(Section 3.2.1) with a management URL and a subject identifier (Section 3.2.1) with a management URI and a subject identifier
(Section 3.4) in the form of an opaque identifier. (Section 3.4) in the form of an opaque identifier.
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792 and a [subject identifier](#response-subject) in the form of
an opaque identifier.
{ {
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"flags": ["bearer"], "flags": ["bearer"],
"manage": "https://server.example.com/token/PRY5NM33O\ "manage": "https://server.example.com/token/PRY5NM33O\
M4TB8N6BW7OZB8CDFONP219RP1L", M4TB8N6BW7OZB8CDFONP219RP1L",
}, },
"subject": { "subject": {
"sub_ids": [ { "sub_ids": [ {
"format": "opaque", "format": "opaque",
"id": "J2G8G8O4AZ" "id": "J2G8G8O4AZ"
} ] } ]
} }
} }
In this example, the AS is returning set of subject identifiers In this example, the AS is returning set of subject identifiers
(Section 3.4), simultaneously as an opaque identifier, an email (Section 3.4), simultaneously as an opaque identifier, an email
address, and a decentralized identifier (DID). address, and a decentralized identifier URL (DID).
{ {
"subject": { "subject": {
"sub_ids": [ { "sub_ids": [ {
"format": "opaque", "format": "opaque",
"id": "J2G8G8O4AZ" "id": "J2G8G8O4AZ"
}, { }, {
"format": "email", "format": "email",
"email": "user@example.com" "email": "user@example.com"
}, { }, {
"format": "did", "format": "did",
"url": "did:example:123456" "url": "did:example:123456"
} ] } ]
} }
} }
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 field additional requests, it responds with the continue field. This field
contains a JSON object with the following properties. contains a JSON object with the following properties.
uri (string) REQUIRED. The URI at which the client instance can uri (string): The URI at which the client instance can make
make continuation requests. This URI MAY vary per request, or MAY continuation requests. This URI MAY vary per request, or MAY be
be stable at the AS. The client instance MUST use this value stable at the AS. The client instance MUST use this value exactly
exactly as given when making a continuation request (Section 5). as given when making a continuation request (Section 5).
REQUIRED.
wait (integer) RECOMMENDED. The amount of time in integer seconds wait (integer): The amount of time in integer seconds the client
the client instance SHOULD wait after receiving this continuation instance MUST wait after receiving this request continuation
handle and calling the URI. response and calling the continuation URI. The value SHOULD NOT
be less than five seconds, and omission of the value MUST NOT be
interpreted as zero (i.e., no delay between requests).
RECOMMENDED.
access_token (object) REQUIRED. A unique access token for access_token (object): A unique access token for continuing the
continuing the request, called the "continuation access token". request, called the "continuation access token". The value of
The value of this property MUST be in the format specified in this property MUST be in the format specified in Section 3.2.1.
Section 3.2.1. This access token MUST be bound to the client This access token MUST be bound to the client instance's key used
instance's key used in the request and MUST NOT be a bearer token. in the request and MUST NOT be a bearer token. As a consequence,
As a consequence, the flags array of this access token MUST NOT the flags array of this access token MUST NOT contain the string
contain the string bearer and the key field MUST be omitted. The bearer and the key field MUST be omitted. The client instance
client instance MUST present the continuation access token in all MUST present the continuation access token in all requests to the
requests to the continuation URI as described in Section 7.2. continuation URI as described in Section 7.2. REQUIRED.
{ {
"continue": { "continue": {
"access_token": { "access_token": {
"value": "80UPRY5NM33OMUKMKSKU" "value": "80UPRY5NM33OMUKMKSKU"
}, },
"uri": "https://server.example.com/continue", "uri": "https://server.example.com/continue",
"wait": 60 "wait": 60
} }
} }
skipping to change at page 48, line 43 skipping to change at page 49, line 43
The client instance uses any access tokens in this response to call The client instance uses any access tokens in this response to call
the RS as described in Section 7.2. the RS as described in Section 7.2.
3.2.1. Single Access Token 3.2.1. Single Access Token
If the client instance has requested a single access token and the AS If the client instance has requested a single access token and the AS
has granted that access token, the AS responds with the has granted that access token, the AS responds with the
"access_token" field. The value of this field is an object with the "access_token" field. The value of this field is an object with the
following properties. following properties.
value (string) REQUIRED. The value of the access token as a string. value (string): The value of the access token as a string. The
The value is opaque to the client instance. The value SHOULD be value is opaque to the client instance. The value SHOULD be
limited to ASCII characters to facilitate transmission over HTTP limited to ASCII characters to facilitate transmission over HTTP
headers within other protocols without requiring additional headers within other protocols without requiring additional
encoding. encoding. REQUIRED.
label (string) REQUIRED for multiple access tokens, OPTIONAL for label (string): The value of the label the client instance provided
single access token. The value of the label the client instance in the associated token request (Section 2.1), if present. If the
provided in the associated token request (Section 2.1), if token has been split by the AS, the value of the label field is
present. If the token has been split by the AS, the value of the chosen by the AS and the split flag is used. REQUIRED for
label field is chosen by the AS and the split flag is used. multiple access tokens, OPTIONAL for single access token.
manage (string) OPTIONAL. The management URI for this access token. manage (string): The management URI for this access token. If
If provided, the client instance MAY manage its access token as provided, the client instance MAY manage its access token as
described in Section 6. This management URI is a function of the described in Section 6. This management URI is a function of the
AS and is separate from the RS the client instance is requesting AS and is separate from the RS the client instance is requesting
access to. This URI MUST NOT include the access token value and access to. This URI MUST NOT include the access token value and
SHOULD be different for each access token issued in a request. SHOULD be different for each access token issued in a request.
OPTIONAL.
access (array of objects/strings) RECOMMENDED. A description of the access (array of objects/strings): A description of the rights
rights associated with this access token, as defined in Section 8. associated with this access token, as defined in Section 8. If
If included, this MUST reflect the rights associated with the included, this MUST reflect the rights associated with the issued
issued access token. These rights MAY vary from what was access token. These rights MAY vary from what was requested by
requested by the client instance. the client instance. REQUIRED.
expires_in (integer) OPTIONAL. The number of seconds in which the expires_in (integer): The number of seconds in which the access will
access will expire. The client instance MUST NOT use the access expire. The client instance MUST NOT use the access token past
token past this time. An RS MUST NOT accept an access token past this time. An RS MUST NOT accept an access token past this time.
this time. Note that the access token MAY be revoked by the AS or Note that the access token MAY be revoked by the AS or RS at any
RS at any point prior to its expiration. point prior to its expiration. OPTIONAL.
key (object / string) OPTIONAL. The key that the token is bound to, key (object / string): The key that the token is bound to, if
if different from the client instance's presented key. The key different from the client instance's presented key. The key MUST
MUST be an object or string in a format described in Section 7.1. be an object or string in a format described in Section 7.1. The
The client instance MUST be able to dereference or process the key client instance MUST be able to dereference or process the key
information in order to be able to sign the request. information in order to be able to sign the request. OPTIONAL.
flags (array of strings) OPTIONAL. A set of flags that represent flags (array of strings): A set of flags that represent attributes
attributes or behaviors of the access token issued by the AS. or behaviors of the access token issued by the AS. OPTIONAL.
The values of the flags field defined by this specification are as The values of the flags field defined by this specification are as
follows: follows:
"bearer" This flag indicates whether the token is a bearer token, "bearer": This flag indicates whether the token is a bearer token,
not bound to a key and proofing mechanism. If the bearer flag is not bound to a key and proofing mechanism. If the bearer flag is
present, the access token is a bearer token, and the key field in present, the access token is a bearer token, and the key field in
this response MUST be omitted. If the bearer flag is omitted and this response MUST be omitted. If the bearer flag is omitted and
the key field in this response is omitted, the token is bound the the key field in this response is omitted, the token is bound the
key used by the client instance (Section 2.3) in its request for key used by the client instance (Section 2.3) in its request for
access. If the bearer flag is omitted, and the key field is access. If the bearer flag is omitted, and the key field is
present, the token is bound to the key and proofing mechanism present, the token is bound to the key and proofing mechanism
indicated in the key field. See Section 12.7 for additional indicated in the key field. See Section 12.7 for additional
considerations on the use of bearer tokens. considerations on the use of bearer tokens.
"durable" OPTIONAL. Flag indicating a hint of AS behavior on token "durable": Flag indicating a hint of AS behavior on token rotation.
rotation. If this flag is present, then the client instance can If this flag is present, then the client instance can expect a
expect a previously-issued access token to continue to work after previously-issued access token to continue to work after it has
it has been rotated (Section 6.1) or the underlying grant request been rotated (Section 6.1) or the underlying grant request has
has been modified (Section 5.3), resulting in the issuance of new been modified (Section 5.3), resulting in the issuance of new
access tokens. If this flag is omitted, the client instance can access tokens. If this flag is omitted, the client instance can
anticipate a given access token will stop working after token anticipate a given access token could stop working after token
rotation or grant request modification. Note that a token flagged rotation or grant request modification. Note that a token flagged
as durable can still expire or be revoked through any normal as durable can still expire or be revoked through any normal
means. means.
"split" OPTIONAL. Flag indicating that this token was generated by "split": Flag indicating that this token was generated by issuing
issuing multiple access tokens in response to one of the client multiple access tokens in response to one of the client instance's
instance's token request (Section 2.1) objects. This behavior token request (Section 2.1) objects. This behavior MUST NOT be
MUST NOT be used unless the client instance has specifically used unless the client instance has specifically requested it by
requested it by use of the split flag. use of the split flag.
Flag values MUST NOT be included more than once. Flag values MUST NOT be included more than once.
Additional flags can be defined by extensions using a registry TBD Additional flags can be defined by extensions using a registry TBD
(Section 11). (Section 11).
The following non-normative example shows a single access token bound The following non-normative example shows a single access token bound
to the client instance's key used in the initial request, with a to the client instance's key used in the initial request, with a
management URL, and that has access to three described resources (one management URI, and that has access to three described resources (one
using an object and two described by reference strings). using an object and two described by reference strings).
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"manage": "https://server.example.com/token/PRY5NM33O\ "manage": "https://server.example.com/token/PRY5NM33O\
M4TB8N6BW7OZB8CDFONP219RP1L", M4TB8N6BW7OZB8CDFONP219RP1L",
"access": [ "access": [
{ {
skipping to change at page 52, line 16 skipping to change at page 53, line 16
If the client instance has requested multiple access tokens and the If the client instance has requested multiple access tokens and the
AS has granted at least one of them, the AS responds with the AS has granted at least one of them, the AS responds with the
"access_token" field. The value of this field is a JSON array, the "access_token" field. The value of this field is a JSON array, the
members of which are distinct access tokens as described in members of which are distinct access tokens as described in
Section 3.2.1. Each object MUST have a unique label field, Section 3.2.1. Each object MUST have a unique label field,
corresponding to the token labels chosen by the client instance in corresponding to the token labels chosen by the client instance in
the multiple access token request (Section 2.1.2). the multiple access token request (Section 2.1.2).
In this non-normative example, two tokens are issued under the names In this non-normative example, two tokens are issued under the names
token1 and token2, and only the first token has a management URL token1 and token2, and only the first token has a management URI
associated with it. associated with it.
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
"access_token": [ "access_token": [
{ {
"label": "token1", "label": "token1",
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"manage": "https://server.example.com/token/PRY5NM33O\ "manage": "https://server.example.com/token/PRY5NM33O\
M4TB8N6BW7OZB8CDFONP219RP1L", M4TB8N6BW7OZB8CDFONP219RP1L",
skipping to change at page 53, line 28 skipping to change at page 54, line 28
"label": "split-2", "label": "split-2",
"value": "FG7VGZZPJ3IZEMN21EVU71FHCAR-UFGLO2FDAP4J1", "value": "FG7VGZZPJ3IZEMN21EVU71FHCAR-UFGLO2FDAP4J1",
"flags": ["split"], "flags": ["split"],
"access": [ "vegetables" ] "access": [ "vegetables" ]
} }
} }
Each access token MAY be bound to different keys with different Each access token MAY be bound to different keys with different
proofing mechanisms. proofing mechanisms.
If token management (Section 6) is allowed, each access token SHOULD The manage URI MUST NOT contain the access token value.
have different manage URIs.
[[ See issue #70 (https://github.com/ietf-wg-gnap/gnap-core-protocol/
issues/70) ]]
3.3. Interaction Modes 3.3. Interaction Modes
If the client instance has indicated a capability to interact with If the client instance has indicated a capability to interact with
the RO in its request (Section 2.5), and the AS has determined that the RO in its request (Section 2.5), and the AS has determined that
interaction is both supported and necessary, the AS responds to the interaction is both supported and necessary, the AS responds to the
client instance with any of the following values in the interact client instance with any of the following values in the interact
field of the response. There is no preference order for interaction field of the response. There is no preference order for interaction
modes in the response, and it is up to the client instance to modes in the response, and it is up to the client instance to
determine which ones to use. All supported interaction methods are determine which ones to use. All supported interaction methods are
included in the same interact object. included in the same interact object.
redirect (string) Redirect to an arbitrary URL. Section 3.3.1 redirect (string): Redirect to an arbitrary URI. REQUIRED if the
redirect interaction start mode is possible for this request. See
Section 3.3.1.
app (string) Launch of an application URL. Section 3.3.2 app (string): Launch of an application URI. REQUIRED if the app
interaction start mode is possible for this request. See
Section 3.3.2.
finish (string) A nonce used by the client instance to verify the user_code (object): Display a short user code. REQUIRED if the
callback after interaction is completed. Section 3.3.4 user_code interaction start mode is possible for this request.
See Section 3.3.3.
user_code_uri (object): Display a short user code and URL. REQUIRED
if the user_code_uri interaction start mode is possible for this
request. Section 3.3.4
finish (string): A nonce used by the client instance to verify the
callback after interaction is completed. REQUIRED if the
interaction finish method requested by the client instance is
possible for this request. See Section 3.3.5.
user_code (object) Display a short user code. Section 3.3.3
Additional interaction mode responses can be defined in a registry Additional interaction mode responses can be defined in a registry
TBD (Section 11). TBD (Section 11).
The AS MUST NOT respond with any interaction mode that the client The AS MUST NOT respond with any interaction mode that the client
instance did not indicate in its request. The AS MUST NOT respond instance did not indicate in its request. The AS MUST NOT respond
with any interaction mode that the AS does not support. Since with any interaction mode that the AS does not support. Since
interaction responses include secret or unique information, the AS interaction responses include secret or unique information, the AS
SHOULD respond to each interaction mode only once in an ongoing SHOULD respond to each interaction mode only once in an ongoing
request, particularly if the client instance modifies its request request, particularly if the client instance modifies its request
(Section 5.3). (Section 5.3).
3.3.1. Redirection to an arbitrary URL 3.3.1. Redirection to an arbitrary URI
If the client instance indicates that it can redirect to an arbitrary If the client instance indicates that it can redirect to an arbitrary
URL (Section 2.5.1.1) and the AS supports this mode for the client URI (Section 2.5.1.1) and the AS supports this mode for the client
instance's request, the AS responds with the "redirect" field, which instance's request, the AS responds with the "redirect" field, which
is a string containing the URL to direct the end-user to. This URL is a string containing the URI to direct the end user to. This URI
MUST be unique for the request and MUST NOT contain any security- MUST be unique for the request and MUST NOT contain any security-
sensitive information such as user identifiers or access tokens. sensitive information such as user identifiers or access tokens.
"interact": { "interact": {
"redirect": "https://interact.example.com/4CF492MLVMSW9MKMXKHQ" "redirect": "https://interact.example.com/4CF492MLVMSW9MKMXKHQ"
} }
The URL returned is a function of the AS, but the URL itself MAY be The URI returned is a function of the AS, but the URI itself MAY be
completely distinct from the URL the client instance uses to request completely distinct from the URI the client instance uses to request
access (Section 2), allowing an AS to separate its user-interactive access (Section 2), allowing an AS to separate its user-interactive
functionality from its back-end security functionality. If the AS functionality from its back-end security functionality. If the AS
does not directly host the functionality accessed through the given does not directly host the functionality accessed through the given
URL, then the means for the interaction functionality to communicate URI, then the means for the interaction functionality to communicate
with the rest of the AS are out of scope for this specification. with the rest of the AS are out of scope for this specification.
[[ See issue #72 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ [[ See issue #72 (https://github.com/ietf-wg-gnap/gnap-core-protocol/
issues/72) ]] issues/72) ]]
The client instance sends the end-user to the URL to interact with The client instance sends the end user to the URI to interact with
the AS. The client instance MUST NOT alter the URL in any way. The the AS. The client instance MUST NOT alter the URI in any way. The
means for the client instance to send the end-user to this URL is out means for the client instance to send the end user to this URI is out
of scope of this specification, but common methods include an HTTP of scope of this specification, but common methods include an HTTP
redirect, launching the system browser, displaying a scannable code, redirect, launching the system browser, displaying a scannable code,
or printing out the URL in an interactive console. See details of or printing out the URI in an interactive console. See details of
the interaction in Section 4.1.1. the interaction in Section 4.1.1.
3.3.2. Launch of an application URL 3.3.2. Launch of an application URI
If the client instance indicates that it can launch an application If the client instance indicates that it can launch an application
URL (Section 2.5.1.2) and the AS supports this mode for the client URI (Section 2.5.1.2) and the AS supports this mode for the client
instance's request, the AS responds with the "app" field, which is a instance's request, the AS responds with the "app" field, which is a
string containing the URL for the client instance to launch. This string containing the URI for the client instance to launch. This
URL MUST be unique for the request and MUST NOT contain any security- URI MUST be unique for the request and MUST NOT contain any security-
sensitive information such as user identifiers or access tokens. sensitive information such as user identifiers or access tokens.
"interact": { "interact": {
"app": "https://app.example.com/launch?tx=4CF492MLV" "app": "https://app.example.com/launch?tx=4CF492MLV"
} }
The means for the launched application to communicate with the AS are The means for the launched application to communicate with the AS are
out of scope for this specification. out of scope for this specification.
The client instance launches the URL as appropriate on its platform, The client instance launches the URI as appropriate on its platform,
and the means for the client instance to launch this URL is out of and the means for the client instance to launch this URI is out of
scope of this specification. The client instance MUST NOT alter the scope of this specification. The client instance MUST NOT alter the
URL in any way. The client instance MAY attempt to detect if an URI in any way. The client instance MAY attempt to detect if an
installed application will service the URL being sent before installed application will service the URI being sent before
attempting to launch the application URL. See details of the attempting to launch the application URI. See details of the
interaction in Section 4.1.3. interaction in Section 4.1.4.
[[ See issue #71 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ [[ See issue #71 (https://github.com/ietf-wg-gnap/gnap-core-protocol/
issues/71) ]] issues/71) ]]
3.3.3. Display of a Short User Code 3.3.3. Display of a Short User Code
If the client instance indicates that it can display a short If the client instance indicates that it can display a short
user-typeable code (Section 2.5.1.3) and the AS supports this mode user-typeable code (Section 2.5.1.3) and the AS supports this mode
for the client instance's request, the AS responds with a "user_code" for the client instance's request, the AS responds with a "user_code"
field. This field is an object that contains the following members. field. This field is an object that contains the following members.
code (string) REQUIRED. A unique short code that the user can type code (string): A unique short code that the user can type into a web
into an authorization server. This string MUST be case- page. This string MUST be case-insensitive, MUST consist of only
insensitive, MUST consist of only easily typeable characters (such easily typeable characters (such as letters or numbers). The time
as letters or numbers). The time in which this code will be in which this code will be accepted SHOULD be short lived, such as
accepted SHOULD be short lived, such as several minutes. It is several minutes. It is RECOMMENDED that this code be no more than
RECOMMENDED that this code be no more than eight characters in eight characters in length. REQUIRED.
length.
url (string) RECOMMENDED. The interaction URL that the client
instance will direct the RO to. This URL MUST be stable such that
client instances can be statically configured with it.
"interact": { "interact": {
"user_code": { "user_code": {
"code": "A1BC-3DFF", "code": "A1BC-3DFF",
"url": "https://srv.ex/device"
} }
} }
The client instance MUST communicate the "code" to the end-user in The client instance MUST communicate the "code" to the end user in
some fashion, such as displaying it on a screen or reading it out some fashion, such as displaying it on a screen or reading it out
audibly. audibly. This code is used by the interaction component of the AS as
a means of identifying the pending grant request and does not
function as an authentication factor for the RO.
The client instance SHOULD also communicate the URL if possible to The URI that the end user is intended to enter the code into MUST be
facilitate user interaction, but since the URL should be stable, the stable, since the client instance is expected to have no means of
client instance should be able to safely decide to not display this communicating a dynamic URI to the end user at runtime.
value. As this interaction mode is designed to facilitate
interaction via a secondary device, it is not expected that the
client instance redirect the end-user to the URL given here at
runtime. Consequently, the URL needs to be stable enough that a
client instance could be statically configured with it, perhaps
referring the end-user to the URL via documentation instead of
through an interactive means. If the client instance is capable of
communicating an arbitrary URL to the end-user, such as through a
scannable code, the client instance can use the "redirect"
(Section 2.5.1.1) mode for this purpose instead of or in addition to
the user code mode.
The URL returned is a function of the AS, but the URL itself MAY be As this interaction mode is designed to facilitate interaction via a
completely distinct from the URL the client instance uses to request secondary device, it is not expected that the client instance
redirect the end user to the URL given here at runtime. If the
client instance is capable of communicating an short arbitrary URI to
the end user for use with the user code, the client instance can
instead use the "user_code_uri" (Section 2.5.1.4) method instead. If
the client instance is capable of communicating a long arbitrary URI
to the end user, such as through a scannable code, the client
instance can use the "redirect" (Section 2.5.1.1) mode for this
purpose instead of or in addition to the user code mode.
See details of the interaction in Section 4.1.2.
3.3.4. Display of a Short User Code and URI
If the client instance indicates that it can display a short
user-typeable code (Section 2.5.1.3) and the AS supports this mode
for the client instance's request, the AS responds with a
"user_code_uri" object that contains the following members.
code (string): A unique short code that the end user can type into a
provided URI. This string MUST be case-insensitive, MUST consist
of only easily typeable characters (such as letters or numbers).
The time in which this code will be accepted SHOULD be short
lived, such as several minutes. It is RECOMMENDED that this code
be no more than eight characters in length. REQUIRED.
uri (string): The interaction URI that the client instance will
direct the RO to. This URI MUST be short enough to be
communicated to the end user. It is RECOMMENDED that this URI be
short enough for an end user to type in manually. The URI MUST
NOT contain the code value. REQUIRED.
"interact": {
"user_code_uri": {
"code": "A1BC-3DFF",
"uri": "https://srv.ex/device"
}
}
The client instance MUST communicate the "code" to the end user in
some fashion, such as displaying it on a screen or reading it out
audibly. This code is used by the interaction component of the AS as
a means of identifying the pending grant request and does not
function as an authentication factor for the RO.
The client instance MUST also communicate the URI to the end user.
Since it is expected that the end user will continue interaction on a
secondary device, the URI needs to be short enough to allow the end
user to type or copy it to a secondary device without mistakes.
The URI returned is a function of the AS, but the URI itself MAY be
completely distinct from the URI the client instance uses to request
access (Section 2), allowing an AS to separate its user-interactive access (Section 2), allowing an AS to separate its user-interactive
functionality from its back-end security functionality. If the AS functionality from its back-end security functionality. If the AS
does not directly host the functionality accessed through the given does not directly host the functionality accessed through the given
URL, then the means for the interaction functionality to communicate URI, then the means for the interaction functionality to communicate
with the rest of the AS are out of scope for this specification. with the rest of the AS are out of scope for this specification.
See details of the interaction in Section 4.1.2. See details of the interaction in Section 4.1.2.
[[ See issue #72 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3.3.5. Interaction Finish
issues/72) ]]
3.3.4. Interaction Finish
If the client instance indicates that it can receive a If the client instance indicates that it can receive a
post-interaction redirect or push at a URL (Section 2.5.2) and the AS post-interaction redirect or push at a URI (Section 2.5.2) and the AS
supports this mode for the client instance's request, the AS responds supports this mode for the client instance's request, the AS responds
with a finish field containing a nonce that the client instance will with a finish field containing a nonce that the client instance will
use in validating the callback as defined in Section 4.2. use in validating the callback as defined in Section 4.2.
"interact": { "interact": {
"finish": "MBDOFXG4Y5CVJCX821LH" "finish": "MBDOFXG4Y5CVJCX821LH"
} }
When the interaction is completed, the interaction component MUST When the interaction is completed, the interaction component MUST
contact the client instance using either a redirect or launch of the contact the client instance using either a redirect or launch of the
RO's browser or through an HTTP POST to the client instance's RO's browser or through an HTTP POST to the client instance's
callback URL using the method indicated in the interaction request callback URI using the method indicated in the interaction request
(Section 2.5.2) as described in Section 4.2. (Section 2.5.2) as described in Section 4.2.
If the AS returns a nonce, the client instance MUST NOT continue a If the AS returns a nonce, the client instance MUST NOT continue a
grant request before it receives the associated interaction reference grant request before it receives the associated interaction reference
on the callback URI. See details in Section 4.2. on the callback URI. See details in Section 4.2.
3.3.5. Extending Interaction Mode Responses 3.3.6. Extending Interaction Mode Responses
Extensions to this specification can define new interaction mode Extensions to this specification can define new interaction mode
responses in a registry TBD (Section 11). Extensions MUST document responses in a registry TBD (Section 11). Extensions MUST document
the corresponding interaction request. the corresponding interaction request.
3.4. Returning Subject Information 3.4. Returning Subject Information
If information about the RO is requested and the AS grants the client If information about the RO is requested and the AS grants the client
instance access to that data, the AS returns the approved information instance access to that data, the AS returns the approved information
in the "subject" response field. The AS MUST return the subject in the "subject" response field. The AS MUST return the subject
field only in cases where the AS is sure that the RO and the end-user field only in cases where the AS is sure that the RO and the end user
are the same party. This can be accomplished through some forms of are the same party. This can be accomplished through some forms of
interaction with the RO (Section 4). interaction with the RO (Section 4).
This field is an object with the following OPTIONAL properties. This field is an object with the following OPTIONAL properties.
sub_ids (array of objects) An array of subject identifiers for the sub_ids (array of objects): An array of subject identifiers for the
RO, as defined by [I-D.ietf-secevent-subject-identifiers]. RO, as defined by [I-D.ietf-secevent-subject-identifiers].
REQUIRED if returning subject identifiers.
An object containing assertions as values keyed on the assertion assertions (array of objects): An array containing assertions as
type defined by a registry TBD (Section 11). Possible keys objects each containing the assertion format and the assertion
include id_token for an [OIDC] ID Token and saml2 for a SAML 2 value as the JSON string serialization of the assertion. Possible
assertion. The assertion values are the string serialization of formats include id_token for an [OIDC] ID Token and saml2 for a
the assertion format, encoded as a plain JSON string. Additional SAML 2 assertion. Additional assertion formats are defined by a
assertion types are defined by a registry TBD (Section 11). [[ registry TBD (Section 11). REQUIRED if returning assertions.
See issue #41 (https://github.com/ietf-wg-gnap/gnap-core-protocol/
issues/41) ]]
updated_at (string) Timestamp as an ISO8610 date string, indicating updated_at (string): Timestamp as an ISO8610 date string, indicating
when the identified account was last updated. The client instance when the identified account was last updated. The client instance
MAY use this value to determine if it needs to request updated MAY use this value to determine if it needs to request updated
profile information through an identity API. The definition of profile information through an identity API. The definition of
such an identity API is out of scope for this specification. such an identity API is out of scope for this specification.
RECOMMENDED.
"subject": { "subject": {
"sub_ids": [ { "sub_ids": [ {
"format": "opaque", "format": "opaque",
"id": "XUT2MFM1XBIKJKSDU8QM" "id": "XUT2MFM1XBIKJKSDU8QM"
} ], } ],
"assertions": { "assertions": [ {
"id_token": "eyj..." "format": "id_token",
} "value": "eyj..."
} ]
} }
Subject identifiers returned by the AS SHOULD uniquely identify the Subject identifiers returned by the AS SHOULD uniquely identify the
RO at the AS. Some forms of subject identifier are opaque to the RO at the AS. Some forms of subject identifier are opaque to the
client instance (such as the subject of an issuer and subject pair), client instance (such as the subject of an issuer and subject pair),
while others forms (such as email address and phone number) are while others forms (such as email address and phone number) are
intended to allow the client instance to correlate the identifier intended to allow the client instance to correlate the identifier
with other account information at the client instance. The AS MUST with other account information at the client instance. The AS MUST
ensure that the returned subject identifiers only apply to the ensure that the returned subject identifiers only apply to the
authenticated end user. The client instance MUST NOT request or use authenticated end user. The client instance MUST NOT request or use
skipping to change at page 58, line 37 skipping to change at page 60, line 38
represented email address or phone number in the identifier is represented email address or phone number in the identifier is
suitable for communication with the current user. To get such suitable for communication with the current user. To get such
information, the client instance MUST use an identity protocol to information, the client instance MUST use an identity protocol to
request and receive additional identity claims. The details of an request and receive additional identity claims. The details of an
identity protocol and associated schema are outside the scope of this identity protocol and associated schema are outside the scope of this
specification. specification.
Extensions to this specification MAY define additional response Extensions to this specification MAY define additional response
properties in a registry TBD (Section 11). properties in a registry TBD (Section 11).
See Section 12.25 for considerations that the client instance has to See Section 12.27 for considerations that the client instance has to
make when accepting and processing assertions from the AS. make when accepting and processing assertions from the AS.
3.5. Returning a Dynamically-bound Client Instance Identifier 3.5. Returning a Dynamically-bound Client Instance Identifier
Many parts of the client instance's request can be passed as either a Many parts of the client instance's request can be passed as either a
value or a reference. The use of a reference in place of a value value or a reference. The use of a reference in place of a value
allows for a client instance to optimize requests to the AS. allows for a client instance to optimize requests to the AS.
Some references, such as for the client instance's identity Some references, such as for the client instance's identity
(Section 2.3.1) or the requested resources (Section 8.1), can be (Section 2.3.1) or the requested resources (Section 8.1), can be
skipping to change at page 59, line 15 skipping to change at page 61, line 15
If desired, the AS MAY also generate and return an instance If desired, the AS MAY also generate and return an instance
identifier dynamically to the client instance in the response to identifier dynamically to the client instance in the response to
facilitate multiple interactions with the same client instance over facilitate multiple interactions with the same client instance over
time. The client instance SHOULD use this instance identifier in time. The client instance SHOULD use this instance identifier in
future requests in lieu of sending the associated data values in the future requests in lieu of sending the associated data values in the
client field. client field.
Dynamically generated client instance identifiers are string values Dynamically generated client instance identifiers are string values
that MUST be protected by the client instance as secrets. Instance that MUST be protected by the client instance as secrets. Instance
identifier values MUST be unguessable and MUST NOT contain any identifier values MUST be unguessable and MUST NOT contain any
sensitive information. Instance identifier values are opaque to the information that would compromise any party if revealed. Instance
client instance. identifier values are opaque to the client instance.
instance_id (string) A string value used to represent the instance_id (string): A string value used to represent the
information in the client object that the client instance can use information in the client object that the client instance can use
in a future request, as described in Section 2.3.1. in a future request, as described in Section 2.3.1. OPTIONAL.
This non-normative example shows an instance identifier along side an This non-normative example shows an instance identifier along side an
issued access token. issued access token.
{ {
"instance_id": "7C7C4AZ9KHRS6X63AJAO", "instance_id": "7C7C4AZ9KHRS6X63AJAO",
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0" "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0"
} }
} }
skipping to change at page 59, line 43 skipping to change at page 61, line 43
issues/77) ]] issues/77) ]]
[[ See issue #78 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ [[ See issue #78 (https://github.com/ietf-wg-gnap/gnap-core-protocol/
issues/78) ]] issues/78) ]]
3.6. Error Response 3.6. Error Response
If the AS determines that the request cannot be issued for any If the AS determines that the request cannot be issued for any
reason, it responds to the client instance with an error message. reason, it responds to the client instance with an error message.
error (string) The error code. error (string): A single ASCII error code from the following, with
additional values available in a registry TBD (Section 11).
REQUIRED.
{ "invalid_request": The request is missing a required parameter,
includes an invalid parameter value or is otherwise malformed.
"error": "user_denied" "invalid_client": The request was made from a client that was not
recognized or allowed by the AS, or the client's signature
validation failed.
} "user_denied": The RO denied the request.
The error code is one of the following, with additional values "too_fast": The client instance did not respect the timeout in
available in a registry TBD (Section 11): the wait response.
user_denied The RO denied the request. "unknown_request": The request referenced an unknown ongoing
access request.
too_fast The client instance did not respect the timeout in the wait "request_denied": The request was denied for an unspecified
response. reason.
unknown_request The request referenced an unknown ongoing access error_description (string): A human-readable string description of
request. the error intended for the developer of the client. OPTIONAL.
[[ See issue #79 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ For example, if the RO denied the request while interacting with the
issues/79) ]] AS, the AS would return the following error when the client instance
tries to continue the grant request:
{
"error": "user_denied"
}
3.7. Extending the Response 3.7. Extending the Response
Extensions to this specification MAY define additional fields for the Extensions to this specification MAY define additional fields for the
grant response in a registry TBD (Section 11). grant response in a registry TBD (Section 11).
4. Determining Authorization and Consent 4. Determining Authorization and Consent
When the client instance makes its initial request (Section 2) to the When the client instance makes its initial request (Section 2) to the
AS for delegated access, it is capable of asking for several AS for delegated access, it is capable of asking for several
skipping to change at page 61, line 33 skipping to change at page 63, line 51
* starting interaction with the end user facilitated by the client * starting interaction with the end user facilitated by the client
software, such as a redirection or user code software, such as a redirection or user code
* challenging the client instance through a challenge-response * challenging the client instance through a challenge-response
mechanism mechanism
* requesting that the client instance present specific additional * requesting that the client instance present specific additional
information, such as a user's credential or an assertion information, such as a user's credential or an assertion
* contacting a RO through an out-of-band mechanism, such as a push * contacting an RO through an out-of-band mechanism, such as a push
notification notification
* contacting an auxiliary software process through an out-of-band * contacting an auxiliary software process through an out-of-band
mechanism, such as querying a digital wallet mechanism, such as querying a digital wallet
The authorization and consent gathering process in GNAP is left The authorization and consent gathering process in GNAP is left
deliberately flexible to allow for a wide variety of different deliberately flexible to allow for a wide variety of different
deployments, interactions, and methodologies. In this process, the deployments, interactions, and methodologies. In this process, the
AS can gather consent from the RO as necessitated by the access that AS can gather consent from the RO as necessitated by the access that
has been requested. The AS can sometimes determine which RO needs to has been requested. The AS can sometimes determine which RO needs to
skipping to change at page 63, line 39 skipping to change at page 66, line 14
4.1.1. Interaction at a Redirected URI 4.1.1. Interaction at a Redirected URI
When the end user is directed to an arbitrary URI through the When the end user is directed to an arbitrary URI through the
"redirect" (Section 3.3.1) mode, the client instance facilitates "redirect" (Section 3.3.1) mode, the client instance facilitates
opening the URI through the end user's web browser. The client opening the URI through the end user's web browser. The client
instance could launch the URI through the system browser, provide a instance could launch the URI through the system browser, provide a
clickable link, redirect the user through HTTP response codes, or clickable link, redirect the user through HTTP response codes, or
display the URI in a form the end user can use to launch such as a display the URI in a form the end user can use to launch such as a
multidimensional barcode. With this method, it is common (though not multidimensional barcode. With this method, it is common (though not
required) for the RO to be the same party as the end-user, since the required) for the RO to be the same party as the end user, since the
client instance has to communicate the redirection URI to the end- client instance has to communicate the redirection URI to the end
user. user.
In many cases, the URI indicates a web page hosted at the AS, In many cases, the URI indicates a web page hosted at the AS,
allowing the AS to authenticate the end user as the RO and allowing the AS to authenticate the end user as the RO and
interactively provide consent. If the URI is hosted by the AS, the interactively provide consent. The URI value is used to identify the
AS MUST determine the grant request being referenced from the URL grant request being authorized. If the URI cannot be associated with
value itself. If the URL cannot be associated with a currently a currently active request, the AS MUST display an error to the RO
active request, the AS MUST display an error to the RO and MUST NOT and MUST NOT attempt to redirect the RO back to any client instance
attempt to redirect the RO back to any client instance even if a even if a redirect finish method is supplied (Section 2.5.2.1). If
redirect finish method is supplied (Section 2.5.2.1). If the URI is the URI is not hosted by the AS directly, the means of communication
not hosted by the AS directly, the means of communication between the between the AS and this URI are out of scope for this specification.
AS and this URI are out of scope for this specification.
The client instance MUST NOT modify the URI when launching it, in The client instance MUST NOT modify the URI when launching it, in
particular the client instance MUST NOT add any parameters to the particular the client instance MUST NOT add any parameters to the
URI. The URI MUST be reachable from the end user's browser, though URI. The URI MUST be reachable from the end user's browser, though
the URI MAY be opened on a separate device from the client instance the URI MAY be opened on a separate device from the client instance
itself. The URI MUST be accessible from an HTTP GET request and MUST itself. The URI MUST be accessible from an HTTP GET request and MUST
be protected by HTTPS or equivalent means. be protected by HTTPS or equivalent means.
4.1.2. Interaction at the User Code URI 4.1.2. Interaction at the Static User Code URI
When the end user is directed to enter a short code through the When the end user is directed to enter a short code through the
"user_code" (Section 3.3.3) mode, the client instance communicates "user_code" (Section 3.3.3) mode, the client instance communicates
the user code to the end-user and directs the end user to enter that the user code to the end user and directs the end user to enter that
code at an associated URI. This mode is used when the client code at an associated URI. This mode is used when the client
instance is not able to facilitate launching an arbitrary URI. The instance is not able to communicate or facilitate launching an
associated URI could be statically configured with the client arbitrary URI. The associated URI could be statically configured
instance or communicated in the response from the AS, but the client with the client instance or in the client software's documentation.
instance communicates that URL to the end user. As a consequence, As a consequence, these URIs SHOULD be short. The user code URI MUST
these URIs SHOULD be short. be reachable from the end user's browser, though the URI is usually
be opened on a separate device from the client instance itself.
Since it is designed to be typed in, the URI SHOULD be accessible
from an HTTP GET request and MUST be protected by HTTPS or equivalent
means.
In many cases, the URI indicates a web page hosted at the AS, In many cases, the URI indicates a web page hosted at the AS,
allowing the AS to authenticate the end user as the RO and allowing the AS to authenticate the end user as the RO and
interactively provide consent. If the URI is hosted by the AS, the interactively provide consent. The value of the user code is used to
AS MUST determine the grant request being referenced from the user identify the grant request being authorized. If the user code cannot
code. If the user code cannot be associated with a currently active be associated with a currently active request, the AS MUST display an
request, the AS MUST display an error to the RO and MUST NOT attempt error to the RO and MUST NOT attempt to redirect the RO back to any
to redirect the RO back to any client instance even if a redirect client instance even if a redirect finish method is supplied
finish method is supplied (Section 2.5.2.1). If the interaction (Section 2.5.2.1). If the interaction component at the user code URI
component at the user code URI is not hosted by the AS directly, the is not hosted by the AS directly, the means of communication between
means of communication between the AS and this URI, including the AS and this URI, including communication of the user code itself,
communication of the user code itself, are out of scope for this are out of scope for this specification.
specification.
When the RO enters this code at the user code URI, the AS MUST When the RO enters this code at the user code URI, the AS MUST
uniquely identify the pending request that the code was associated uniquely identify the pending request that the code was associated
with. If the AS does not recognize the entered code, the interaction with. If the AS does not recognize the entered code, the interaction
component MUST display an error to the user. If the AS detects too component MUST display an error to the user. If the AS detects too
many unrecognized code enter attempts, the interaction component many unrecognized code enter attempts, the interaction component
SHOULD display an error to the user and MAY take additional actions SHOULD display an error to the user and MAY take additional actions
such as slowing down the input interactions. The user should be such as slowing down the input interactions. The user should be
warned as such an error state is approached, if possible. warned as such an error state is approached, if possible.
The client instance MUST NOT modify the URI when launching it, in 4.1.3. Interaction at a Dynamic User Code URI
When the end user is directed to enter a short code through the
"user_code_uri" (Section 3.3.4) mode, the client instance
communicates the user code and associated URI to the end user and
directs the end user to enter that code at the URI. This mode is
used when the client instance is not able to facilitate launching an
arbitrary URI but can communicate arbitrary values like URIs. As a
consequence, these URIs SHOULD be short. The client instance MUST
NOT modify the URI when communicating it to the end user; in
particular the client instance MUST NOT add any parameters to the particular the client instance MUST NOT add any parameters to the
URI. The user code URI MUST be reachable from the end user's URI. The user code URI MUST be reachable from the end user's
browser, though the URI is usually be opened on a separate device browser, though the URI is usually be opened on a separate device
from the client instance itself. The URI MUST be accessible from an from the client instance itself. Since it is designed to be typed
HTTP GET request and MUST be protected by HTTPS or equivalent means. in, the URI SHOULD be accessible from an HTTP GET request and MUST be
protected by HTTPS or equivalent means.
4.1.3. Interaction through an Application URI In many cases, the URI indicates a web page hosted at the AS,
allowing the AS to authenticate the end user as the RO and
interactively provide consent. The value of the user code is used to
identify the grant request being authorized. If the user code cannot
be associated with a currently active request, the AS MUST display an
error to the RO and MUST NOT attempt to redirect the RO back to any
client instance even if a redirect finish method is supplied
(Section 2.5.2.1). If the interaction component at the user code URI
is not hosted by the AS directly, the means of communication between
the AS and this URI, including communication of the user code itself,
are out of scope for this specification.
When the RO enters this code at the given URI, the AS MUST uniquely
identify the pending request that the code was associated with. If
the AS does not recognize the entered code, the interaction component
MUST display an error to the user. If the AS detects too many
unrecognized code enter attempts, the interaction component SHOULD
display an error to the user and MAY take additional actions such as
slowing down the input interactions. The user should be warned as
such an error state is approached, if possible.
4.1.4. Interaction through an Application URI
When the client instance is directed to launch an application through When the client instance is directed to launch an application through
the "app" (Section 3.3.2) mode, the client launches the URL as the "app" (Section 3.3.2) mode, the client launches the URI as
appropriate to the system, such as through a deep link or custom URI appropriate to the system, such as through a deep link or custom URI
scheme registered to a mobile application. The means by which the AS scheme registered to a mobile application. The means by which the AS
and the launched application communicate with each other and perform and the launched application communicate with each other and perform
any of the required actions are out of scope for this specification. any of the required actions are out of scope for this specification.
4.2. Post-Interaction Completion 4.2. Post-Interaction Completion
If an interaction "finish" (Section 3.3.4) method is associated with If an interaction "finish" (Section 3.3.5) method is associated with
the current request, the AS MUST follow the appropriate method at the current request, the AS MUST follow the appropriate method at
upon completion of interaction in order to signal the client instance upon completion of interaction in order to signal the client instance
to continue, except for some limited error cases discussed below. If to continue, except for some limited error cases discussed below. If
a finish method is not available, the AS SHOULD instruct the RO to a finish method is not available, the AS SHOULD instruct the RO to
return to the client instance upon completion. return to the client instance upon completion.
The AS MUST create an interaction reference and associate that The AS MUST create an interaction reference and associate that
reference with the current interaction and the underlying pending reference with the current interaction and the underlying pending
request. This interaction reference value MUST be sufficiently request. This interaction reference value MUST be sufficiently
random so as not to be guessable by an attacker. The interaction random so as not to be guessable by an attacker. The interaction
skipping to change at page 66, line 23 skipping to change at page 69, line 31
method are dangerous or blocked. method are dangerous or blocked.
* The AS cannot determine which ongoing grant request is being * The AS cannot determine which ongoing grant request is being
referenced. referenced.
* The ongoing grant request has been cancelled or otherwise blocked. * The ongoing grant request has been cancelled or otherwise blocked.
4.2.1. Completing Interaction with a Browser Redirect to the Callback 4.2.1. Completing Interaction with a Browser Redirect to the Callback
URI URI
When using the redirect interaction finish method (Section 3.3.4), When using the redirect interaction finish method (Section 3.3.5),
the AS signals to the client instance that interaction is complete the AS signals to the client instance that interaction is complete
and the request can be continued by directing the RO (in their and the request can be continued by directing the RO (in their
browser) back to the client instance's redirect URL sent in the browser) back to the client instance's redirect URI sent in the
callback request (Section 2.5.2.1). callback request (Section 2.5.2.1).
The AS secures this redirect by adding the hash and interaction The AS secures this redirect by adding the hash and interaction
reference as query parameters to the client instance's redirect URL. reference as query parameters to the client instance's redirect URI.
hash REQUIRED. The interaction hash value as described in hash: The interaction hash value as described in Section 4.2.3.
Section 4.2.3. REQUIRED.
interact_ref REQUIRED. The interaction reference generated for this interact_ref: The interaction reference generated for this
interaction. interaction. REQUIRED.
The means of directing the RO to this URL are outside the scope of The means of directing the RO to this URI are outside the scope of
this specification, but common options include redirecting the RO this specification, but common options include redirecting the RO
from a web page and launching the system browser with the target URL. from a web page and launching the system browser with the target URI.
See Section 12.16 for considerations on which HTTP status code to use
when redirecting a request that potentially contains credentials.
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
https://client.example.net/return/123455\ https://client.example.net/return/123455\
?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2\ ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2\
HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A\ HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A\
&interact_ref=4IFWWIKYBC2PQ6U56NL1 &interact_ref=4IFWWIKYBC2PQ6U56NL1
When receiving the request, the client instance MUST parse the query When receiving the request, the client instance MUST parse the query
parameters to calculate and validate the hash value as described in parameters to calculate and validate the hash value as described in
Section 4.2.3. If the hash validates, the client instance sends a Section 4.2.3. If the hash validates, the client instance sends a
continuation request to the AS as described in Section 5.1 using the continuation request to the AS as described in Section 5.1 using the
interaction reference value received here. interaction reference value received here.
4.2.2. Completing Interaction with a Direct HTTP Request Callback 4.2.2. Completing Interaction with a Direct HTTP Request Callback
When using the push interaction finish method (Section 3.3.4), the AS When using the push interaction finish method (Section 3.3.5), the AS
signals to the client instance that interaction is complete and the signals to the client instance that interaction is complete and the
request can be continued by sending an HTTP POST request to the request can be continued by sending an HTTP POST request to the
client instance's callback URL sent in the callback request client instance's callback URI sent in the callback request
(Section 2.5.2.2). (Section 2.5.2.2).
The entity message body is a JSON object consisting of the following The entity message body is a JSON object consisting of the following
two fields: two fields:
hash (string) REQUIRED. The interaction hash value as described in hash (string): The interaction hash value as described in
Section 4.2.3. Section 4.2.3. REQUIRED.
interact_ref (string) REQUIRED. The interaction reference generated interact_ref (string) The interaction reference generated for this
for this interaction. interaction. REQUIRED.
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
POST /push/554321 HTTP/1.1 POST /push/554321 HTTP/1.1
Host: client.example.net Host: client.example.net
Content-Type: application/json Content-Type: application/json
{ {
"hash": "p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R\ "hash": "p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R\
2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A", 2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A",
"interact_ref": "4IFWWIKYBC2PQ6U56NL1" "interact_ref": "4IFWWIKYBC2PQ6U56NL1"
} }
When processing such a call, the AS MUST protect itself against SSRF
attacks as discussed in Section 12.31.
When receiving the request, the client instance MUST parse the JSON When receiving the request, the client instance MUST parse the JSON
object and validate the hash value as described in Section 4.2.3. If object and validate the hash value as described in Section 4.2.3. If
the hash validates, the client instance sends a continuation request the hash validates, the client instance sends a continuation request
to the AS as described in Section 5.1 using the interaction reference to the AS as described in Section 5.1 using the interaction reference
value received here. value received here.
4.2.3. Calculating the interaction hash 4.2.3. Calculating the interaction hash
The "hash" parameter in the request to the client instance's callback The "hash" parameter in the request to the client instance's callback
URL ties the front channel response to an ongoing request by using URI ties the front channel response to an ongoing request by using
values known only to the parties involved. This security mechanism values known only to the parties involved. This security mechanism
allows the client instance to protect itself against several kinds of allows the client instance to protect itself against several kinds of
session fixation and injection attacks. The AS MUST always provide session fixation and injection attacks. The AS MUST always provide
this hash, and the client instance MUST validate the hash when this hash, and the client instance MUST validate the hash when
received. received.
To calculate the "hash" value, the party doing the calculation To calculate the "hash" value, the party doing the calculation
creates a hash string by concatenating the following values in the creates a hash string by concatenating the following values in the
following order using a single newline (\n) character to separate following order using a single newline (\n) character to separate
them: them:
* the "nonce" value sent by the client instance in the interaction * the "nonce" value sent by the client instance in the interaction
"finish" section of the initial request (Section 2.5.2) "finish" section of the initial request (Section 2.5.2)
* the AS's nonce value from the interaction finish response * the AS's nonce value from the interaction finish response
(Section 3.3.4) (Section 3.3.5)
* the "interact_ref" returned from the AS as part of the interaction * the "interact_ref" returned from the AS as part of the interaction
finish method (Section 4.2) finish method (Section 4.2)
* the grant endpoint URL the client instance used to make its * the grant endpoint URI the client instance used to make its
initial request (Section 2) initial request (Section 2)
There is no padding or whitespace before or after any of the lines, There is no padding or whitespace before or after any of the lines,
and no trailing newline character. and no trailing newline character.
VJLO6A4CAYLBXHTR0KRO VJLO6A4CAYLBXHTR0KRO
MBDOFXG4Y5CVJCX821LH MBDOFXG4Y5CVJCX821LH
4IFWWIKYBC2PQ6U56NL1 4IFWWIKYBC2PQ6U56NL1
https://server.example.com/tx https://server.example.com/tx
skipping to change at page 68, line 52 skipping to change at page 72, line 9
"hash_method" value is not present in the client instance's request, "hash_method" value is not present in the client instance's request,
the algorithm defaults to "sha3". the algorithm defaults to "sha3".
[[ See issue #56 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ [[ See issue #56 (https://github.com/ietf-wg-gnap/gnap-core-protocol/
issues/56) ]] issues/56) ]]
4.2.3.1. SHA3-512 4.2.3.1. SHA3-512
The "sha3" hash method consists of hashing the input string with the The "sha3" hash method consists of hashing the input string with the
512-bit SHA3 algorithm. The byte array is then encoded using URL 512-bit SHA3 algorithm. The byte array is then encoded using URL
Safe Base64 with no padding. The resulting string is the hash value. Safe Base64 with no padding [RFC4648]. The resulting string is the
hash value.
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM\ p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM\
7XHPAdJzTZMtKBsaraJ64A 7XHPAdJzTZMtKBsaraJ64A
4.2.3.2. SHA2-512 4.2.3.2. SHA2-512
The "sha2" hash method consists of hashing the input string with the The "sha2" hash method consists of hashing the input string with the
512-bit SHA2 algorithm. The byte array is then encoded using URL 512-bit SHA2 algorithm. The byte array is then encoded using URL
Safe Base64 with no padding. The resulting string is the hash value. Safe Base64 with no padding [RFC4648]. The resulting string is the
hash value.
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
62SbcD3Xs7L40rjgALA-ymQujoh2LB2hPJyX9vlcr1H6ecChZ8BNKkG_HrOKP_Bp\ 62SbcD3Xs7L40rjgALA-ymQujoh2LB2hPJyX9vlcr1H6ecChZ8BNKkG_HrOKP_Bp\
j84rh4mC9aE9x7HPBFcIHw j84rh4mC9aE9x7HPBFcIHw
5. Continuing a Grant Request 5. Continuing a Grant Request
While it is possible for the AS to return a grant response While it is possible for the AS to return a grant response
(Section 3) with all the client instance's requested information (Section 3) with all the client instance's requested information
skipping to change at page 69, line 42 skipping to change at page 72, line 50
To enable this ongoing negotiation, the AS provides a continuation To enable this ongoing negotiation, the AS provides a continuation
API to the client software. The AS returns a continue field in the API to the client software. The AS returns a continue field in the
response (Section 3.1) that contains information the client instance response (Section 3.1) that contains information the client instance
needs to access this API, including a URI to access as well as a needs to access this API, including a URI to access as well as a
continuation access token to use during the requests. continuation access token to use during the requests.
The continuation access token is initially bound to the same key and The continuation access token is initially bound to the same key and
method the client instance used to make the initial request. As a method the client instance used to make the initial request. As a
consequence, when the client instance makes any calls to the consequence, when the client instance makes any calls to the
continuation URL, the client instance MUST present the continuation continuation URI, the client instance MUST present the continuation
access token as described in Section 7.2 and present proof of the access token as described in Section 7.2 and present proof of the
client instance's key (or its most recent rotation) by signing the client instance's key (or its most recent rotation) by signing the
request as described in Section 7.3. The AS MUST validate all keys request as described in Section 7.3. The AS MUST validate all keys
presented by the client instance or referenced in an ongoing request presented by the client instance or referenced in an ongoing request
for each call within that request. for each call within that request.
Access tokens other than the continuation access tokens MUST NOT be Access tokens other than the continuation access tokens MUST NOT be
usable for continuation requests. usable for continuation requests.
[[ See issue #85 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ [[ See issue #85 (https://github.com/ietf-wg-gnap/gnap-core-protocol/
skipping to change at page 70, line 19 skipping to change at page 73, line 25
unique URI and signs the request with HTTP Message Signatures: unique URI and signs the request with HTTP Message Signatures:
POST /continue/KSKUOMUKM HTTP/1.1 POST /continue/KSKUOMUKM HTTP/1.1
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Host: server.example.com Host: server.example.com
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
The AS MUST be able to tell from the client instance's request which The AS MUST be able to tell from the client instance's request which
specific ongoing request is being accessed, using a combination of specific ongoing request is being accessed, using a combination of
the continuation URL, the provided continuation access token, and the the continuation URI, the provided continuation access token, and the
client instance identified by the key signature. If the AS cannot client instance identified by the key signature. If the AS cannot
determine a single active grant request to map the continuation determine a single active grant request to map the continuation
request to, the AS MUST return an error. request to, the AS MUST return an error.
The ability to continue an already-started request allows the client The ability to continue an already-started request allows the client
instance to perform several important functions, including presenting instance to perform several important functions, including presenting
additional information from interaction, modifying the initial additional information from interaction, modifying the initial
request, and getting the current state of the request. request, and getting the current state of the request.
All requests to the continuation API are protected by this bound All requests to the continuation API are protected by this bound
continuation access token. For example, here the client instance continuation access token. For example, here the client instance
makes a POST request to a stable continuation endpoint URL with the makes a POST request to a stable continuation endpoint URI with the
interaction reference (Section 5.1), includes the access token, and interaction reference (Section 5.1), includes the access token, and
signs with HTTP Message Signatures: signs with HTTP Message Signatures:
POST /continue HTTP/1.1 POST /continue HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Digest: sha256=... Content-Digest: sha-256=...
{ {
"interact_ref": "4IFWWIKYBC2PQ6U56NL1" "interact_ref": "4IFWWIKYBC2PQ6U56NL1"
} }
If a wait parameter was included in the continuation response If a wait parameter was included in the continuation response
(Section 3.1), the client instance MUST NOT call the continuation URI (Section 3.1), the client instance MUST NOT call the continuation URI
prior to waiting the number of seconds indicated. If no wait period prior to waiting the number of seconds indicated. If no wait period
is indicated, the client instance SHOULD wait at least 5 seconds. If is indicated, the client instance MUST NOT poll immediately and
the client instance does not respect the given wait period, the AS SHOULD wait at least 5 seconds. If the client instance does not
MUST return an error. respect the given wait period, the AS MUST return the error too_fast
defined in Section 3.6.
The response from the AS is a JSON object and MAY contain any of the The response from the AS is a JSON object and MAY contain any of the
fields described in Section 3, as described in more detail in the fields described in Section 3, as described in more detail in the
sections below. sections below.
If the AS determines that the client instance can make a further If the AS determines that the client instance can make a further
continuation request, the AS MUST include a new "continue" response continuation request, the AS MUST include a new "continue" response
(Section 3.1). The new continue response MUST include a continuation (Section 3.1). The new continue response MUST include a continuation
access token as well, and this token SHOULD be a new access token, access token as well, and this token SHOULD be a new access token,
invalidating the previous access token. If the AS does not return a invalidating the previous access token. If the AS does not return a
skipping to change at page 71, line 35 skipping to change at page 74, line 42
Section 4.2.1, this response includes an interaction reference. The Section 4.2.1, this response includes an interaction reference. The
client instance MUST include that value as the field interact_ref in client instance MUST include that value as the field interact_ref in
a POST request to the continuation URI. a POST request to the continuation URI.
POST /continue HTTP/1.1 POST /continue HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Digest: sha256=... Content-Digest: sha-256=...
{ {
"interact_ref": "4IFWWIKYBC2PQ6U56NL1" "interact_ref": "4IFWWIKYBC2PQ6U56NL1"
} }
Since the interaction reference is a one-time-use value as described Since the interaction reference is a one-time-use value as described
in Section 4.2.1, if the client instance needs to make additional in Section 4.2.1, if the client instance needs to make additional
continuation calls after this request, the client instance MUST NOT continuation calls after this request, the client instance MUST NOT
include the interaction reference. If the AS detects a client include the interaction reference. If the AS detects a client
instance submitting the same interaction reference multiple times, instance submitting the same interaction reference multiple times,
skipping to change at page 72, line 26 skipping to change at page 75, line 29
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
{ {
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"manage": "https://server.example.com/token/PRY5NM33O\ "manage": "https://server.example.com/token/PRY5NM33O\
M4TB8N6BW7OZB8CDFONP219RP1L", M4TB8N6BW7OZB8CDFONP219RP1L",
}, },
"subject": { "subject": {
"sub_ids": [ { "sub_ids": [ {
"format": "opaque", "format": "opaque",
"id": "J2G8G8O4AZ" "id": "J2G8G8O4AZ"
} ] } ]
} }
} }
With this example, the client instance can not make an additional With this example, the client instance can not make an additional
continuation request because a continue field is not included. continuation request because a continue field is not included.
[[ See issue #88 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ [[ See issue #88 (https://github.com/ietf-wg-gnap/gnap-core-protocol/
issues/88) ]] issues/88) ]]
skipping to change at page 74, line 15 skipping to change at page 77, line 15
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
{ {
"access_token": { "access_token": {
"value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
"manage": "https://server.example.com/token/PRY5NM33O\ "manage": "https://server.example.com/token/PRY5NM33O\
M4TB8N6BW7OZB8CDFONP219RP1L", M4TB8N6BW7OZB8CDFONP219RP1L",
}, },
"subject": { "subject": {
"sub_ids": [ { "sub_ids": [ {
"format": "opaque", "format": "opaque",
"id": "J2G8G8O4AZ" "id": "J2G8G8O4AZ"
} ] } ]
} }
} }
See Section 12.20 for considerations on polling for continuation See Section 12.21 for considerations on polling for continuation
without an interaction finish method. without an interaction finish method.
5.3. Modifying an Existing Request 5.3. Modifying an Existing Request
The client instance might need to modify an ongoing request, whether The client instance might need to modify an ongoing request, whether
or not tokens have already been issued or claims have already been or not tokens have already been issued or claims have already been
released. In such cases, the client instance makes an HTTP PATCH released. In such cases, the client instance makes an HTTP PATCH
request to the continuation URI and includes any fields it needs to request to the continuation URI and includes any fields it needs to
modify. Fields that aren't included in the request are considered modify. Fields that aren't included in the request are considered
unchanged from the original request. unchanged from the original request.
skipping to change at page 75, line 6 skipping to change at page 78, line 6
core-protocol/issues/92) ]] core-protocol/issues/92) ]]
The client instance MAY include the interact field as described in The client instance MAY include the interact field as described in
Section 2.5. Inclusion of this field indicates that the client Section 2.5. Inclusion of this field indicates that the client
instance is capable of driving interaction with the RO, and this instance is capable of driving interaction with the RO, and this
field replaces any values from a previous request. The AS MAY field replaces any values from a previous request. The AS MAY
respond to any of the interaction responses as described in respond to any of the interaction responses as described in
Section 3.3, just like it would to a new request. Section 3.3, just like it would to a new request.
The client instance MAY include the user field as described in The client instance MAY include the user field as described in
Section 2.4 to present new assertions or information about the end- Section 2.4 to present new assertions or information about the end
user. [[ See issue #93 (https://github.com/ietf-wg-gnap/gnap-core- user. [[ See issue #93 (https://github.com/ietf-wg-gnap/gnap-core-
protocol/issues/93) ]] protocol/issues/93) ]]
The client instance MUST NOT include the client section of the The client instance MUST NOT include the client section of the
request. [[ See issue #94 (https://github.com/ietf-wg-gnap/gnap-core- request. [[ See issue #94 (https://github.com/ietf-wg-gnap/gnap-core-
protocol/issues/94) ]] protocol/issues/94) ]]
The client instance MAY include post-interaction responses such as The client instance MAY include post-interaction responses such as
described in Section 5.1. [[ See issue #95 (https://github.com/ietf- described in Section 5.1. [[ See issue #95 (https://github.com/ietf-
wg-gnap/gnap-core-protocol/issues/95) ]] wg-gnap/gnap-core-protocol/issues/95) ]]
skipping to change at page 76, line 10 skipping to change at page 79, line 10
contain interaction responses (Section 3.3) as well. contain interaction responses (Section 3.3) as well.
For example, a client instance initially requests a set of resources For example, a client instance initially requests a set of resources
using references: using references:
POST /tx HTTP/1.1 POST /tx HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Digest: sha256=... Content-Digest: sha-256=...
{ {
"access_token": { "access_token": {
"access": [ "access": [
"read", "write" "read", "write"
] ]
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
skipping to change at page 77, line 16 skipping to change at page 80, line 16
it no longer needs "write" access and therefore modifies its ongoing it no longer needs "write" access and therefore modifies its ongoing
request, here asking for just "read" access instead of both "read" request, here asking for just "read" access instead of both "read"
and "write" as before. and "write" as before.
PATCH /continue HTTP/1.1 PATCH /continue HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Digest: sha256=... Content-Digest: sha-256=...
{ {
"access_token": { "access_token": {
"access": [ "access": [
"read" "read"
] ]
} }
... ...
} }
skipping to change at page 78, line 13 skipping to change at page 81, line 13
} }
For another example, the client instance initially requests read-only For another example, the client instance initially requests read-only
access but later needs to step up its access. The initial request access but later needs to step up its access. The initial request
could look like this example. could look like this example.
POST /tx HTTP/1.1 POST /tx HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Digest: sha256=... Content-Digest: sha-256=...
{ {
"access_token": { "access_token": {
"access": [ "access": [
"read" "read"
] ]
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
skipping to change at page 79, line 15 skipping to change at page 82, line 15
call. The client instance later realizes that it now needs "write" call. The client instance later realizes that it now needs "write"
access in addition to the "read" access. Since this is an expansion access in addition to the "read" access. Since this is an expansion
of what it asked for previously, the client instance also includes a of what it asked for previously, the client instance also includes a
new interaction section in case the AS needs to interact with the RO new interaction section in case the AS needs to interact with the RO
again to gather additional authorization. Note that the client again to gather additional authorization. Note that the client
instance's nonce and callback are different from the initial request. instance's nonce and callback are different from the initial request.
Since the original callback was already used in the initial exchange, Since the original callback was already used in the initial exchange,
and the callback is intended for one-time-use, a new one needs to be and the callback is intended for one-time-use, a new one needs to be
included in order to use the callback again. included in order to use the callback again.
[[ See issue #97 (https://github.com/ietf-wg-gnap/gnap-core-protocol/
issues/97) ]]
PATCH /continue HTTP/1.1 PATCH /continue HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Digest: sha256=... Content-Digest: sha-256=...
{ {
"access_token": { "access_token": {
"access": [ "access": [
"read", "write" "read", "write"
] ]
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
skipping to change at page 80, line 22 skipping to change at page 83, line 22
Content-Type: application/json Content-Type: application/json
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
If the request is successfully cancelled, the AS responds with an If the request is successfully cancelled, the AS responds with an
HTTP 202. The AS SHOULD revoke all associated access tokens. HTTP 202. The AS SHOULD revoke all associated access tokens.
6. Token Management 6. Token Management
If an access token response includes the "manage" parameter as If an access token response includes the manage parameter as
described in Section 3.2.1, the client instance MAY call this URL to described in Section 3.2.1, the client instance MAY call this URI to
manage the access token with any of the actions defined in the manage the access token with any of the actions defined in the
following sections. Other actions are undefined by this following sections: rotate and revoke. Other actions are undefined
specification. by this specification.
The access token being managed acts as the access element for its own The access token being managed acts as the access element for its own
management API. The client instance MUST present proof of an management API. The client instance MUST present proof of an
appropriate key along with the access token. appropriate key along with the access token.
If the token is sender-constrained (i.e., not a bearer token), it If the token is sender-constrained (i.e., not a bearer token), it
MUST be sent with the appropriate binding for the access token MUST be sent with the appropriate binding for the access token
(Section 7.2). (Section 7.2).
If the token is a bearer token, the client instance MUST present If the token is a bearer token, the client instance MUST present
proof of the same key identified in the initial request (Section 2.3) proof of the same key identified in the initial request (Section 2.3)
as described in Section 7.3. as described in Section 7.3.
The AS MUST validate the proof and assure that it is associated with The AS MUST validate the proof and assure that it is associated with
either the token itself or the client instance the token was issued either the token itself or the client instance the token was issued
to, as appropriate for the token's presentation type. to, as appropriate for the token's presentation type.
6.1. Rotating the Access Token 6.1. Rotating the Access Token
The client instance makes an HTTP POST to the token management URI, If the client instance has an access token and that access token
sending the access token in the appropriate header and signing the expires, the client instance might want to rotate the access token.
request with the appropriate key. Rotating an access token consists of issuing a new access token in
place of an existing access token, with the same rights and
properties as the original token, apart from an updated expiration
time.
To rotate an access token, the client instance makes an HTTP POST to
the token management URI, sending the access token in the appropriate
header and signing the request with the appropriate key.
POST /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 POST /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Digest: sha256=... Content-Digest: sha-256=...
The AS validates that the token presented is associated with the The AS validates that the token presented is associated with the
management URL, that the AS issued the token to the given client management URI, that the AS issued the token to the given client
instance, and that the presented key is appropriate to the token. instance, and that the presented key is appropriate to the token.
If the access token has expired, the AS SHOULD honor the rotation Note that in many cases, the access token will have expired for
request to the token management URL since it is likely that the regular use. To facilitate token rotation, the AS SHOULD honor the
client instance is attempting to refresh the expired token. To rotation request of the expired access token since it is likely that
support this, the AS MAY apply different lifetimes for the use of the the client instance is attempting to refresh the expired token. To
token in management vs. its use at an RS. An AS MUST NOT honor a support this, the AS MAY allow a longer lifetime for token management
rotation request for an access token that has been revoked, either by compared to its use at an RS. An AS MUST NOT honor a rotation
the AS or by the client instance through the token management URI request for an access token that has been revoked or otherwise
(Section 6.2). disabled.
If the token is validated and the key is appropriate for the request, If the token is validated and the key is appropriate for the request,
the AS MUST invalidate the current access token associated with this the AS MUST invalidate the current access token associated with this
URL, if possible, and return a new access token response as described URI, if possible. Note that stateless access tokens can make
in Section 3.2.1, unless the multi_token flag is specified in the proactive revocation difficult within a system, see Section 12.29.
request. The value of the access token MUST NOT be the same as the
current value of the access token used to access the management API. The AS responds with an HTTP 200 with a JSON body consisting of the
The response MAY include an updated access token management URL as rotated access token in the access_token field described in
well, and if so, the client instance MUST use this new URL to manage Section 3.2.1. The value of the access token MUST NOT be the same as
the new access token. [[ See issue #101 (https://github.com/ietf-wg- the current value of the access token used to access the management
gnap/gnap-core-protocol/issues/101) ]] API. The response MUST include an access token management URI, and
the value of this URI MAY be different from the URI used by the
client instance to make the rotation call. The client instance MUST
use this new URI to manage the rotated access token.
The access rights in the access array for the rotated access token
MUST be included in the response and MUST be the same as the token
before rotation. If the client instance requires different access
rights, the client instance can request a new access token by
creating a new request (Section 2) or by updating an existing grant
request (Section 5.3).
[[ See issue #102 (https://github.com/ietf-wg-gnap/gnap-core-
protocol/issues/102) ]]
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
{ {
"access_token": { "access_token": {
"value": "FP6A8H6HY37MH13CK76LBZ6Y1UADG6VEUPEER5H2", "value": "FP6A8H6HY37MH13CK76LBZ6Y1UADG6VEUPEER5H2",
"manage": "https://server.example.com/token/PRY5NM33O\ "manage": "https://server.example.com/token/PRY5NM33O\
M4TB8N6BW7OZB8CDFONP219RP1L", M4TB8N6BW7OZB8CDFONP219RP1L",
"expires_in": 3600,
"access": [ "access": [
{ {
"type": "photo-api", "type": "photo-api",
"actions": [ "actions": [
"read", "read",
"write", "write",
"dolphin" "dolphin"
], ],
"locations": [ "locations": [
"https://server.example.net/", "https://server.example.net/",
skipping to change at page 83, line 21 skipping to change at page 86, line 21
If the key presented is associated with the token (or the client If the key presented is associated with the token (or the client
instance, in the case of a bearer token), the AS MUST invalidate the instance, in the case of a bearer token), the AS MUST invalidate the
access token, if possible, and return an HTTP 204 response code. access token, if possible, and return an HTTP 204 response code.
204 No Content 204 No Content
Though the AS MAY revoke an access token at any time for any reason, Though the AS MAY revoke an access token at any time for any reason,
the token management function is specifically for the client the token management function is specifically for the client
instance's use. If the access token has already expired or has been instance's use. If the access token has already expired or has been
revoked through other means, the AS SHOULD honor the revocation revoked through other means, the AS SHOULD honor the revocation
request to the token management URL as valid, since the end result is request to the token management URI as valid, since the end result is
still the token not being usable. still the token not being usable.
7. Securing Requests from the Client Instance 7. Securing Requests from the Client Instance
In GNAP, the client instance secures its requests to the AS and RS by In GNAP, the client instance secures its requests to the AS and RS by
presenting an access token, presenting proof of a key that it presenting an access token, presenting proof of a key that it
possesses (aka, a "key proof"), or both an access token and key proof possesses (aka, a "key proof"), or both an access token and key proof
together. together.
* When an access token is used with a key proof, this is a bound * When an access token is used with a key proof, this is a bound
skipping to change at page 84, line 23 skipping to change at page 87, line 23
that request. For a key used as part of an access token response in that request. For a key used as part of an access token response in
Section 3.2.1, the proof of that key MUST be used when presenting the Section 3.2.1, the proof of that key MUST be used when presenting the
access token. access token.
A key presented by value MUST be a public key in at least one A key presented by value MUST be a public key in at least one
supported format. If a key is sent in multiple formats, all the key supported format. If a key is sent in multiple formats, all the key
format values MUST be equivalent. Note that while most formats format values MUST be equivalent. Note that while most formats
present the full value of the public key, some formats present a present the full value of the public key, some formats present a
value cryptographically derived from the public key. value cryptographically derived from the public key.
proof (string) The form of proof that the client instance will use proof (string): The form of proof that the client instance will use
when presenting the key. The valid values of this field and the when presenting the key. The valid values of this field and the
processing requirements for each are detailed in Section 7.3. The processing requirements for each are detailed in Section 7.3.
proof field is REQUIRED. REQUIRED.
jwk (object) The public key and its properties represented as a JSON jwk (object): The public key and its properties represented as a
Web Key [RFC7517]. A JWK MUST contain the alg (Algorithm) and kid JSON Web Key [RFC7517]. A JWK MUST contain the alg (Algorithm)
(Key ID) parameters. The alg parameter MUST NOT be "none". The and kid (Key ID) parameters. The alg parameter MUST NOT be
x5c (X.509 Certificate Chain) parameter MAY be used to provide the "none". The x5c (X.509 Certificate Chain) parameter MAY be used
X.509 representation of the provided public key. to provide the X.509 representation of the provided public key.
OPTIONAL.
cert (string) PEM serialized value of the certificate used to sign cert (string): PEM serialized value of the certificate used to sign
the request, with optional internal whitespace per [RFC7468]. The the request, with optional internal whitespace per [RFC7468]. The
PEM header and footer are optionally removed. PEM header and footer are optionally removed. OPTIONAL.
cert#S256 (string) The certificate thumbprint calculated as per cert#S256 (string): The certificate thumbprint calculated as per
OAuth-MTLS [RFC8705] in base64 URL encoding. Note that this OAuth-MTLS [RFC8705] in base64 URL encoding. Note that this
format does not include the full public key. format does not include the full public key. OPTIONAL.
Additional key formats are defined in a registry TBD (Section 11). Additional key formats are defined in a registry TBD (Section 11).
This non-normative example shows a single key presented in multiple This non-normative example shows a single key presented in multiple
formats. This example key is intended to be used with the HTTP formats. This example key is intended to be used with the HTTP
Message Signatures ({{httpsig-binding}}) proofing mechanism, as Message Signatures ({{httpsig-binding}}) proofing mechanism, as
indicated by the httpsig value of the proof field. indicated by the httpsig value of the proof field.
"key": { "key": {
"proof": "httpsig", "proof": "httpsig",
"jwk": { "jwk": {
"kty": "RSA", "kty": "RSA",
"e": "AQAB", "e": "AQAB",
"kid": "xyz-1", "kid": "xyz-1",
"alg": "RS256", "alg": "RS256",
"n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..."
}, },
"cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..."
} }
7.1.1. Key References 7.1.1. Key References
Keys in GNAP can also be passed by reference such that the party Keys in GNAP can also be passed by reference such that the party
receiving the reference will be able to determine the appropriate receiving the reference will be able to determine the appropriate
keying material for use in that part of the protocol. keying material for use in that part of the protocol.
"key": "S-P4XJQ_RYJCRTSU1.63N3E" "key": "S-P4XJQ_RYJCRTSU1.63N3E"
Keys referenced in this manner MAY be shared symmetric keys. The key Keys referenced in this manner MAY be shared symmetric keys. The key
reference MUST NOT contain any unencrypted private or shared reference MUST NOT contain any unencrypted private or shared
symmetric key information. symmetric key information.
Keys referenced in this manner MUST be bound to a single proofing Keys referenced in this manner MUST be bound to a single proofing
mechanism. mechanism.
The means of dereferencing this value are out of scope for this The means of dereferencing this value are out of scope for this
specification. specification. Commonly, key references are created by the AS and
are not necessarily needed to be dereferencable by the client. These
types of key references are an internal reference to the AS, such as
an identifier of a record in a database. In other applications, it
can be useful to use key references that are resolvable by both
clients and ASs, which could be accomplished by e.g. a client
publishing a public key at a URI. For interoperability, this method
could later be described as an extension.
7.1.2. Key Protection
The security of GNAP relies on the cryptographic security of the keys
themselves. When symmetric keys are used in GNAP, a key management
system or secure key derivation mechanism MUST be used to supply the
keys. Symmetric keys MUST NOT be a human memorable password or a
value derived from one. Symmetric keys MUST NOT be passed by value
from the client instance to the AS.
7.2. Presenting Access Tokens 7.2. Presenting Access Tokens
The method the client instance uses to send an access token depends The method the client instance uses to send an access token depends
on whether the token is bound to a key, and if so which proofing on whether the token is bound to a key, and if so which proofing
method is associated with the key. This information is conveyed by method is associated with the key. This information is conveyed by
the key parameter and the bearer flag in the single (Section 3.2.1) the key parameter and the bearer flag in the single (Section 3.2.1)
and multiple access tokens (Section 3.2.2) responses. and multiple access tokens (Section 3.2.2) responses.
If the flags field does not contain the bearer flag and the key is If the flags field does not contain the bearer flag and the key is
skipping to change at page 86, line 17 skipping to change at page 89, line 35
proof as described in Section 7.3 for the key bound to the access proof as described in Section 7.3 for the key bound to the access
token. For example, an "httpsig"-bound access token is sent as token. For example, an "httpsig"-bound access token is sent as
follows: follows:
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
GET /stuff HTTP/1.1 GET /stuff HTTP/1.1
Host: resource.example.com Host: resource.example.com
Authorization: GNAP 80UPRY5NM33OMUKMKSKU Authorization: GNAP 80UPRY5NM33OMUKMKSKU
Signature-Input: sig1=("@method" "@target-uri" "authorization")\ Signature-Input: sig1=("@method" "@target-uri" "authorization")\
;created=1618884475;keyid="gnap-rsa" ;created=1618884473;keyid="gnap-rsa"
Signature: sig1=:KymTn1/++nwWsNHdc48sguMjnVSnvqQNrijQT0/kXDfljaIgHl\ Signature: sig1=:ThgXGQjGiJYQW8JYxcNypXk7wQWG8KZ6AtyKOrqNOkgoa8iWgm\
o12NkEt4e5qZeCFutzRxWpHKtjVEDldIUSsktxj4Li7PgUNJtIkJkdA1EoebGz1X/\ feHLkRmT6BUj83DkLX84TQehhK3D5Lcgllhghuu2Pr3JmYVY7FFYwYAcfoISzVPKp\
AD3coqYpoaFsOcPyfXjYHYWFd8HxLOUz3imA8xbxS+J9GZAjyDjTfG6yfsMsfd10f\ YyDbh/g34qOpFvlCYDgG94ZX16LAKlqYXWn5vYgealgm54zzCCnvyaLKViGVWz6PM\
nrDRJqalPNDEgOOwwyEtjht4MnzpV1Wf43YWwgEJOC2rvxPIeuNxWbUc5v/o3s3Zr\ 7rOIZqMQPOu6JceqdsiVn8xj2qTS9CWEmuJABtTnRoXNGVg8tUEQp7qt3F7tCI/AM\
ywo2sunUcwXwlmbgyiGY0vgGFWjdHfgKvjda7eNLTr7r3jPgo/GlOB3jyadD4xcKs\ vHW4FAYrQbE47qQsjh4zPiES1EM+lHdA9fCE0OEsfabxB7Gr9GvkMyiApWTf/Zs45\
S/idS3RGk1+e9jbGHK5cRTp0ZzF94kWw==: IoJhr1OVtOCGVhEmoiNFreBTm7cTyTgg==:
If the flags field contains the bearer flag, the access token is a If the flags field contains the bearer flag, the access token is a
bearer token that MUST be sent using the Authorization Request Header bearer token that MUST be sent using the Authorization Request Header
Field method defined in [RFC6750]. Field method defined in [RFC6750].
Authorization: Bearer OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 Authorization: Bearer OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0
The Form-Encoded Body Parameter and URI Query Parameter methods of The Form-Encoded Body Parameter and URI Query Parameter methods of
[RFC6750] MUST NOT be used. [RFC6750] MUST NOT be used.
skipping to change at page 86, line 49 skipping to change at page 90, line 20
with any value. with any value.
7.3. Proving Possession of a Key with a Request 7.3. Proving Possession of a Key with a Request
Any keys presented by the client instance to the AS or RS MUST be Any keys presented by the client instance to the AS or RS MUST be
validated as part of the request in which they are presented. The validated as part of the request in which they are presented. The
type of binding used is indicated by the proof parameter of the key type of binding used is indicated by the proof parameter of the key
object in Section 7.1. Values defined by this specification are as object in Section 7.1. Values defined by this specification are as
follows: follows:
httpsig HTTP Signing signature header "httpsig": HTTP Signing signature headers. See Section 7.3.1.
mtls Mutual TLS certificate verification "mtls": Mutual TLS certificate verification. See Section 7.3.2.
jwsd A detached JWS signature header
jws Attached JWS payload "jwsd": A detached JWS signature header. See Section 7.3.3.
"jws": Attached JWS payload. See Section 7.3.4.
Additional proofing methods are defined by a registry TBD Additional proofing methods are defined by a registry TBD
(Section 11). (Section 11).
All key binding methods used by this specification MUST cover all All key binding methods used by this specification MUST cover all
relevant portions of the request, including anything that would relevant portions of the request, including anything that would
change the nature of the request, to allow for secure validation of change the nature of the request, to allow for secure validation of
the request. Relevant aspects include the URI being called, the HTTP the request. Relevant aspects include the URI being called, the HTTP
method being used, any relevant HTTP headers and values, and the HTTP method being used, any relevant HTTP headers and values, and the HTTP
message body itself. The verifier of the signed message MUST message body itself. The verifier of the signed message MUST
skipping to change at page 88, line 50 skipping to change at page 92, line 47
bunS0K3bA_3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kO\ bunS0K3bA_3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kO\
zywzwPTuq-cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" zywzwPTuq-cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ"
} }
7.3.1. HTTP Message Signing 7.3.1. HTTP Message Signing
This method is indicated by httpsig in the proof field. The signer This method is indicated by httpsig in the proof field. The signer
creates an HTTP Message Signature as described in creates an HTTP Message Signature as described in
[I-D.ietf-httpbis-message-signatures]. [I-D.ietf-httpbis-message-signatures].
The message components of the signature MUST include the following: The covered components of the signature MUST include the following:
@method: the method used in the HTTP request "@method": The method used in the HTTP request.
@target-uri: the full request URL of the HTTP request "@target-uri": The full request URI of the HTTP request.
content-digest or digest: The Content-Digest or Digest header as When the message contains a request body, the covered components MUST
defined in [I-D.ietf-httpbis-digest-headers]. When the request also include the following:
message has a body, the signer MUST calculate this header value
and the verifier MUST validate this field value. Use of Content-
Digest is RECOMMENDED. Use of content-encoding agnostic digest
methods (such as id-sha-256) is RECOMMENDED.
When the request is bound to an access token, the covered content "content-digest": The Content-Digest header as defined in
MUST also include: [I-D.ietf-httpbis-digest-headers]. When the request message has a
body, the signer MUST calculate this header value and the verifier
MUST validate this field value. Use of content-encoding agnostic
digest methods (such as sha-256) is RECOMMENDED.
authorization: The Authorization header used to present the access When the request is bound to an access token, the covered components
MUST also include the following:
"authorization": The Authorization header used to present the access
token as discussed in Section 7.2. token as discussed in Section 7.2.
Other message components MAY also be included. Other message components MAY also be included.
If the signer's key presented is a JWK, the keyid parameter of the If the signer's key presented is a JWK, the keyid parameter of the
signature MUST be set to the kid value of the JWK, the signing signature MUST be set to the kid value of the JWK, the signing
algorithm used MUST be the JWS algorithm denoted by the key's alg algorithm used MUST be the JWS algorithm denoted by the key's alg
field, and the explicit alg signature parameter MUST NOT be included. field, and the explicit alg signature parameter MUST NOT be included.
In this example, the message body is the following JSON object: In this example, the message body is the following JSON object:
skipping to change at page 90, line 22 skipping to change at page 94, line 22
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"uri": "https://client.foo/callback", "uri": "https://client.foo/callback",
"nonce": "VJLO6A4CAYLBXHTR0KRO" "nonce": "VJLO6A4CAYLBXHTR0KRO"
} }
}, },
"client": { "client": {
"proof": "httpsig",
"key": { "key": {
"proof": "httpsig",
"jwk": { "jwk": {
"kid": "gnap-rsa", "kid": "gnap-rsa",
"kty": "RSA", "kty": "RSA",
"e": "AQAB", "e": "AQAB",
"alg": "RS256", "alg": "PS512",
"n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\
YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\
YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\
ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\
3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\
N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ"
} }
} }
"display": { "display": {
"name": "My Client Display Name", "name": "My Client Display Name",
"uri": "https://client.foo/" "uri": "https://client.foo/"
}, },
} }
} }
This body is hashed for the Content-Digest header using id-sha-256 This body is hashed for the Content-Digest header using sha-256 into
into the following encoded value: the following encoded value:
id-sha-256=98QzyNVYpdgTrWBKpC4qFSCmmR+CrwwvUoiaDCSjKxw= sha-256=:q2XBmzRDCREcS2nWo/6LYwYyjrlN1bRfv+HKLbeGAGg=:
The HTTP message signature input string is calculated to be the The HTTP message signature input string is calculated to be the
following: following:
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
"@method": POST "@method": POST
"@target-uri": https://server.example.com/gnap "@target-uri": https://server.example.com/gnap
"content-type": application/json "content-digest": \
"content-digest": id-sha-256=98QzyNVYpdgTrWBKpC4qFSCmmR+Crwwv\ sha-256=:q2XBmzRDCREcS2nWo/6LYwYyjrlN1bRfv+HKLbeGAGg=:
UoiaDCSjKxw= "content-length": 988
"content-length": 986 "content-type": application/json
"@signature-params": ("@method" "@target-uri" "content-type" \ "@signature-params": ("@method" "@target-uri" "content-digest" \
"content-digest" "content-length");created=1618884475\ "content-length" "content-type");created=1618884473;keyid="gnap-rsa"
;keyid="gnap-rsa"
This leads to the following full HTTP message request: This leads to the following full HTTP message request:
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
POST /gnap HTTP/1.1 POST /gnap HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Content-Length: 986 Content-Length: 988
Content-Digest: id-sha-256=98QzyNVYpdgTrWBKpC4qFSCmmR+CrwwvUoiaDCSj\ Content-Digest: sha-256=:q2XBmzRDCREcS2nWo/6LYwYyjrlN1bRfv+HKLbeGAG\
Kxw= g=:
Signature-Input: sig1=("@method" "@target-uri" "content-type" \ Signature-Input: sig1=("@method" "@target-uri" "content-digest" \
"content-digest" "content-length");created=1618884475\ "content-length" "content-type");created=1618884473;keyid="gnap-rsa"
;keyid="gnap-rsa" Signature: sig1=:EWJgAONk3D6542Scj8g51rYeMHw96cH2XiCMxcyL511wyemGcw\
Signature: sig1=:SatKrAh2qNxbDBY6H3XUtpWn07aSrukpi3202L4DIPLLGgKdSu\ 5PosYVO3eK+v+h1H+LiO4BjapL5ffZV+SgU8Q2v+qEDA4FrP0+/ni9W+lazjIrzNs\
XyObjdCK/agmEx36xyn40iiCAqYskXugpNARianBiWKOkcWHhSs31FSTSoJ8vvGpJ\ FAojwTlngMkAjZyDC/5+qUYB0KeEb4gnAhmuikv28DF30MT28yxCjeui2NGyzpPxB\
4GxemDPvI6BXmLZtJvYBehoXtfcRFKGLzYOtbbtefzw2vP+k19W4PrhNmxFEUCepT\ cWk1K2Cxb6hS1WXUSZufFN9jOzrTg2c8/jcKkROKbLZLshF/oCuxAAgDabTqJy+qk\
KRk0sBoz4zIYK6FqEAHir0oRjwdCcXHFqI9U6+/DgpuxjFFX+OSZehmN6Q1quJgu0\ kz/Z/U5hI181qlTzNIYijnAvXzezlsLPZcMpJ1Au9APyBYAtDipAzyD6+IZl3rhzP\
FITmsC9OANs5hwIAkXGJNdv3FuxAZAVrSnUScuGutSJXAn1daXToewVgBA+IrQ86m\ 2leuCMCOvDxg9qA83LVtsqfjNJO+dEHA==:
lsXtWgvmTTXENUvOELV6qTV2nenwr/UQ==:
{ {
"access_token": { "access_token": {
"access": [ "access": [
"dolphin-metadata" "dolphin-metadata"
] ]
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"uri": "https://client.foo/callback", "uri": "https://client.foo/callback",
"nonce": "VJLO6A4CAYLBXHTR0KRO" "nonce": "VJLO6A4CAYLBXHTR0KRO"
} }
}, },
"client": { "client": {
"proof": "httpsig",
"key": { "key": {
"proof": "httpsig",
"jwk": { "jwk": {
"kid": "gnap-rsa", "kid": "gnap-rsa",
"kty": "RSA", "kty": "RSA",
"e": "AQAB", "e": "AQAB",
"alg": "RS256", "alg": "PS512",
"n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\
YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\
YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\
ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\
3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\
N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ"
} }
} }
"display": { "display": {
"name": "My Client Display Name", "name": "My Client Display Name",
skipping to change at page 93, line 31 skipping to change at page 97, line 28
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"uri": "https://client.foo/callback", "uri": "https://client.foo/callback",
"nonce": "VJLO6A4CAYLBXHTR0KRO" "nonce": "VJLO6A4CAYLBXHTR0KRO"
} }
}, },
"client": { "client": {
"proof": "jws",
"key": { "key": {
"proof": "mtls",
"cert": "MIIC6jCCAdKgAwIBAgIGAXjw74xPMA0GCSqGSIb3DQEBCwUAMD\ "cert": "MIIC6jCCAdKgAwIBAgIGAXjw74xPMA0GCSqGSIb3DQEBCwUAMD\
YxNDAyBgNVBAMMK05JWU15QmpzRGp5QkM5UDUzN0Q2SVR6a3BEOE50UmppOXlhcEV\ YxNDAyBgNVBAMMK05JWU15QmpzRGp5QkM5UDUzN0Q2SVR6a3BEOE50UmppOXlhcEV\
6QzY2bVEwHhcNMjEwNDIwMjAxODU0WhcNMjIwMjE0MjAxODU0WjA2MTQwMgYDVQQD\ 6QzY2bVEwHhcNMjEwNDIwMjAxODU0WhcNMjIwMjE0MjAxODU0WjA2MTQwMgYDVQQD\
DCtOSVlNeUJqc0RqeUJDOVA1MzdENklUemtwRDhOdFJqaTl5YXBFekM2Nm1RMIIBI\ DCtOSVlNeUJqc0RqeUJDOVA1MzdENklUemtwRDhOdFJqaTl5YXBFekM2Nm1RMIIBI\
jANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhYOJ+XOKISdMMShn/G4W9m20mT\ jANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhYOJ+XOKISdMMShn/G4W9m20mT\
0VWtQBsmBBkI2cmRt4Ai8BfYdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8\ 0VWtQBsmBBkI2cmRt4Ai8BfYdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8\
KowlyVy8IkZ8NMwSrcUIBZGYXjHpwjzvfGvXH/5KJlnR3/uRUp4Z4Ujk2bCaKegDn\ KowlyVy8IkZ8NMwSrcUIBZGYXjHpwjzvfGvXH/5KJlnR3/uRUp4Z4Ujk2bCaKegDn\
11V2vxE41hqaPUnhRZxe0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDad\ 11V2vxE41hqaPUnhRZxe0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDad\
z8BkPo+uv4BC0bunS0K3bA/3UgVp7zBlQFoFnLTO2uWp/muLEWGl67gBq9MO3brKX\ z8BkPo+uv4BC0bunS0K3bA/3UgVp7zBlQFoFnLTO2uWp/muLEWGl67gBq9MO3brKX\
fGhi3kOzywzwPTuq+cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQIDAQABMA0\ fGhi3kOzywzwPTuq+cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQIDAQABMA0\
skipping to change at page 94, line 22 skipping to change at page 98, line 20
The verifier compares the TLS client certificate presented during The verifier compares the TLS client certificate presented during
mutual TLS negotiation to the expected key of the signer. Since the mutual TLS negotiation to the expected key of the signer. Since the
TLS connection covers the entire message, there are no additional TLS connection covers the entire message, there are no additional
requirements to check. requirements to check.
Note that in many instances, the verifier will not do a full Note that in many instances, the verifier will not do a full
certificate chain validation of the presented TLS client certificate, certificate chain validation of the presented TLS client certificate,
as the means of trust for this certificate could be in something as the means of trust for this certificate could be in something
other than a PKI system, such as a static registration or trust-on- other than a PKI system, such as a static registration or trust-on-
first-use. See Section 12.16 and Section 12.17 for some additional first-use. See Section 12.17 and Section 12.18 for some additional
considerations for this key proofing method. considerations for this key proofing method.
7.3.3. Detached JWS 7.3.3. Detached JWS
This method is indicated by jwsd in the proof field. A JWS [RFC7515] This method is indicated by jwsd in the proof field. A JWS [RFC7515]
object is created as follows: object is created as follows:
To protect the request, the JOSE header of the signature contains the To protect the request, the JOSE header of the signature contains the
following parameters: following claims:
kid (string) The key identifier. RECOMMENDED. If the key is kid (string): The key identifier. REQUIRED if the key is presented
presented in JWK format, this MUST be the value of the kid field in JWK format, this MUST be the value of the kid field of the key.
of the key.
alg (string) The algorithm used to sign the request. REQUIRED. alg (string): The algorithm used to sign the request. MUST be
MUST be appropriate to the key presented. If the key is presented appropriate to the key presented. If the key is presented as a
as a JWK, this MUST be equal to the alg parameter of the key. JWK, this MUST be equal to the alg parameter of the key. MUST NOT
MUST NOT be none. be none. REQUIRED.
typ (string) The type header, value "gnap-binding+jwsd". REQUIRED typ (string): The type header, value "gnap-binding+jwsd". REQUIRED.
htm (string) The HTTP Method used to make this request, as an htm (string): The HTTP Method used to make this request, as a case-
uppercase ASCII string. REQUIRED sensitive ASCII string. Note that most public HTTP methods are in
uppercase ASCII by convention. REQUIRED.
uri (string) The HTTP URI used for this request, including all path uri (string): The HTTP URI used for this request, including all path
and query components and no fragment component. REQUIRED and query components and no fragment component. REQUIRED.
created (integer) A timestamp of when the signature was created, in created (integer): A timestamp of when the signature was created, in
integer seconds since UNIX Epoch integer seconds since UNIX Epoch. REQUIRED.
ath (string) When a request is bound to an access token, the access When the request is bound to an access token, the JOSE header MUST
token hash value. The value MUST be the result of Base64url also include the following:
encoding (with no padding) the SHA-256 digest of the ASCII
encoding of the associated access token's value. REQUIRED if the ath (string): The hash of the access token. The value MUST be the
request protects an access token. result of Base64url encoding (with no padding) the SHA-256 digest
of the ASCII encoding of the associated access token's value.
REQUIRED.
If the HTTP request has a message body, such as an HTTP POST or PUT If the HTTP request has a message body, such as an HTTP POST or PUT
method, the payload of the JWS object is the Base64url encoding method, the payload of the JWS object is the Base64url encoding
(without padding) of the SHA256 digest of the bytes of the body. If (without padding) of the SHA256 digest of the bytes of the body. If
the request being made does not have a message body, such as an HTTP 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 GET, OPTIONS, or DELETE method, the JWS signature is calculated over
an empty payload. an empty payload.
The signer presents the signed object in compact form [RFC7515] in The signer presents the signed object in compact form [RFC7515] in
the Detached-JWS HTTP Header field. the Detached-JWS HTTP Header field.
skipping to change at page 96, line 22 skipping to change at page 100, line 22
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"uri": "https://client.foo/callback", "uri": "https://client.foo/callback",
"nonce": "VJLO6A4CAYLBXHTR0KRO" "nonce": "VJLO6A4CAYLBXHTR0KRO"
} }
}, },
"client": { "client": {
"proof": "jwsd",
"key": { "key": {
"proof": "jwsd",
"jwk": { "jwk": {
"kid": "gnap-rsa", "kid": "gnap-rsa",
"kty": "RSA", "kty": "RSA",
"e": "AQAB", "e": "AQAB",
"alg": "RS256", "alg": "RS256",
"n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\
YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\
YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\
ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\
3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\
skipping to change at page 97, line 36 skipping to change at page 101, line 36
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"uri": "https://client.foo/callback", "uri": "https://client.foo/callback",
"nonce": "VJLO6A4CAYLBXHTR0KRO" "nonce": "VJLO6A4CAYLBXHTR0KRO"
} }
}, },
"client": { "client": {
"proof": "jwsd",
"key": { "key": {
"proof": "jwsd",
"jwk": { "jwk": {
"kid": "gnap-rsa", "kid": "gnap-rsa",
"kty": "RSA", "kty": "RSA",
"e": "AQAB", "e": "AQAB",
"alg": "RS256", "alg": "RS256",
"n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\
YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\
YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\
ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\
3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\
skipping to change at page 98, line 22 skipping to change at page 102, line 22
expected key of the signer. All required fields MUST be present and expected key of the signer. All required fields MUST be present and
their values MUST be valid. If the HTTP message request contains a their values MUST be valid. If the HTTP message request contains a
body, the verifier MUST calculate the hash of body just as the signer body, the verifier MUST calculate the hash of body just as the signer
does, with no normalization or transformation of the request. does, with no normalization or transformation of the request.
7.3.4. Attached JWS 7.3.4. Attached JWS
This method is indicated by jws in the proof field. A JWS [RFC7515] This method is indicated by jws in the proof field. A JWS [RFC7515]
object is created as follows: object is created as follows:
The JOSE header MUST contain the kid parameter of the key bound to To protect the request, the JWS header contains the following claims.
this signer for this request. The alg parameter MUST be set to a
value appropriate for the key identified by kid and MUST NOT be none.
To protect the request, the JWS header MUST contain the following kid (string): The key identifier. REQUIRED if the key is presented
additional parameters. in JWK format, this MUST be the value of the kid field of the key.
typ (string) The type header, value "gnap-binding+jws". alg (string): The algorithm used to sign the request. MUST be
appropriate to the key presented. If the key is presented as a
JWK, this MUST be equal to the alg parameter of the key. MUST NOT
be none. REQUIRED.
htm (string) The HTTP Method used to make this request, as an typ (string): The type header, value "gnap-binding+jwsd". REQUIRED.
uppercase ASCII string.
uri (string) The HTTP URI used for this request, including all path htm (string): The HTTP Method used to make this request, as a case-
and query components and no fragment component. sensitive ASCII string. (Note that most public HTTP methods are
in uppercase.) REQUIRED.
created (integer) A timestamp of when the signature was created, in uri (string): The HTTP URI used for this request, including all path
integer seconds since UNIX Epoch and query components and no fragment component. REQUIRED.
ath (string) When a request is bound to an access token, the access created (integer): A timestamp of when the signature was created, in
token hash value. The value MUST be the result of Base64url integer seconds since UNIX Epoch. REQUIRED.
encoding (with no padding) the SHA-256 digest of the ASCII
encoding of the associated access token's value. When the request is bound to an access token, the JOSE header MUST
also include the following:
ath (string): The hash of the access token. The value MUST be the
result of Base64url encoding (with no padding) the SHA-256 digest
of the ASCII encoding of the associated access token's value.
REQUIRED.
If the HTTP request has a message body, such as an HTTP POST or PUT If the HTTP request has a message body, such as an HTTP POST or PUT
method, the payload of the JWS object is the JSON serialized body of method, the payload of the JWS object is the JSON serialized body of
the request, and the object is signed according to JWS and serialized the request, and the object is signed according to JWS and serialized
into compact form [RFC7515]. The signer presents the JWS as the body into compact form [RFC7515]. The signer presents the JWS as the body
of the request along with a content type of application/jose. The of the request along with a content type of application/jose. The
verifier MUST extract the payload of the JWS and treat it as the verifier MUST extract the payload of the JWS and treat it as the
request body for further processing. request body for further processing.
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
skipping to change at page 100, line 22 skipping to change at page 104, line 22
}, },
"interact": { "interact": {
"start": ["redirect"], "start": ["redirect"],
"finish": { "finish": {
"method": "redirect", "method": "redirect",
"uri": "https://client.foo/callback", "uri": "https://client.foo/callback",
"nonce": "VJLO6A4CAYLBXHTR0KRO" "nonce": "VJLO6A4CAYLBXHTR0KRO"
} }
}, },
"client": { "client": {
"proof": "jws",
"key": { "key": {
"proof": "jws",
"jwk": { "jwk": {
"kid": "gnap-rsa", "kid": "gnap-rsa",
"kty": "RSA", "kty": "RSA",
"e": "AQAB", "e": "AQAB",
"alg": "RS256", "alg": "RS256",
"n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\
YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\
YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\
ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\
3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\
skipping to change at page 101, line 42 skipping to change at page 105, line 42
gImRpc3BsYXkiOiB7CiAgICAgICAgIm5hbWUiOiAiTXkgQ2xpZW50IERpc3BsYXkgTm\ gImRpc3BsYXkiOiB7CiAgICAgICAgIm5hbWUiOiAiTXkgQ2xpZW50IERpc3BsYXkgTm\
FtZSIsCiAgICAgICAgInVyaSI6ICJodHRwczovL2NsaWVudC5mb28vIgogICAgICB9L\ FtZSIsCiAgICAgICAgInVyaSI6ICJodHRwczovL2NsaWVudC5mb28vIgogICAgICB9L\
AogICAgfSwKICAgICJzdWJqZWN0IjogewogICAgICAgICJmb3JtYXRzIjogWyJpc3Nf\ AogICAgfSwKICAgICJzdWJqZWN0IjogewogICAgICAgICJmb3JtYXRzIjogWyJpc3Nf\
c3ViIiwgIm9wYXF1ZSJdCiAgICB9Cn0K.MwNoVMQp5hVxI0mCs9LlOUdFtkDXaA1_eT\ c3ViIiwgIm9wYXF1ZSJdCiAgICB9Cn0K.MwNoVMQp5hVxI0mCs9LlOUdFtkDXaA1_eT\
vOXq7DOGrtDKH7q4vP2xUq3fH2jRAZqnobo0WdPP3eM3NH5QUjW8pa6_QpwdIWkK7r-\ vOXq7DOGrtDKH7q4vP2xUq3fH2jRAZqnobo0WdPP3eM3NH5QUjW8pa6_QpwdIWkK7r-\
u_52puE0lPBp7J4U2w4l9gIbg8iknsmWmXeY5F6wiGT8ptfuEYGgmloAJd9LIeNvD3U\ u_52puE0lPBp7J4U2w4l9gIbg8iknsmWmXeY5F6wiGT8ptfuEYGgmloAJd9LIeNvD3U\
LW2h2dz1Pn2eDnbyvgB0Ugae0BoZB4f69fKWj8Z9wvTIjk1LZJN1PcL7_zT8Lrlic9a\ LW2h2dz1Pn2eDnbyvgB0Ugae0BoZB4f69fKWj8Z9wvTIjk1LZJN1PcL7_zT8Lrlic9a\
PyzT7Q9ovkd1s-4whE7TrnGUzFc5mgWUn_gsOpsP5mIIljoEEv-FqOW2RyNYulOZl0Q\ PyzT7Q9ovkd1s-4whE7TrnGUzFc5mgWUn_gsOpsP5mIIljoEEv-FqOW2RyNYulOZl0Q\
8EnnDHV_vPzrHlUarbGg4YffgtwkQhdK72-JOxYQ 8EnnDHV_vPzrHlUarbGg4YffgtwkQhdK72-JOxYQ
[[ See issue #109 (https://github.com/ietf-wg-gnap/gnap-core-
protocol/issues/109) ]]
When the verifier receives an attached JWS request, it MUST parse and When the verifier receives an attached JWS request, it MUST parse and
validate the JWS object. The signature MUST be validated against the validate the JWS object. The signature MUST be validated against the
expected key of the signer. All required fields MUST be present and expected key of the signer. All required fields MUST be present and
their values MUST be valid. If the HTTP message request contains a their values MUST be valid. If the HTTP message request contains a
body, the verifier MUST decode the payload of the JWS object and body, the verifier MUST decode the payload of the JWS object and
treat this as the HTTP message body. treat this as the HTTP message body.
8. Resource Access Rights 8. Resource Access Rights
GNAP provides a rich structure for describing the protected resources GNAP provides a rich structure for describing the protected resources
skipping to change at page 102, line 22 skipping to change at page 106, line 22
The root of this structure is a JSON array. The elements of the JSON The root of this structure is a JSON array. The elements of the JSON
array represent rights of access that are associated with the the array represent rights of access that are associated with the the
access token. The resulting access is the union of all elements access token. The resulting access is the union of all elements
within the array. within the array.
The access associated with the access token is described using The access associated with the access token is described using
objects that each contain multiple dimensions of access. Each object objects that each contain multiple dimensions of access. Each object
contains a REQUIRED type property that determines the type of API contains a REQUIRED type property that determines the type of API
that the token is used for. that the token is used for.
type (string) The type of resource request as a string. This field type (string): The type of resource request as a string. This field
MAY define which other fields are allowed in the request object. MAY define which other fields are allowed in the request object.
This field is REQUIRED. REQUIRED.
The value of the type field is under the control of the AS. This The value of the type field is under the control of the AS. This
field MUST be compared using an exact byte match of the string value field MUST be compared using an exact byte match of the string value
against known types by the AS. The AS MUST ensure that there is no against known types by the AS. The AS MUST ensure that there is no
collision between different authorization data types that it collision between different authorization data types that it
supports. The AS MUST NOT do any collation or normalization of data supports. The AS MUST NOT do any collation or normalization of data
types during comparison. It is RECOMMENDED that designers of types during comparison. It is RECOMMENDED that designers of
general-purpose APIs use a URI for this field to avoid collisions general-purpose APIs use a URI for this field to avoid collisions
between multiple API types protected by a single AS. between multiple API types protected by a single AS.
While it is expected that many APIs will have their own properties, a While it is expected that many APIs will have their own properties, a
set of common properties are defined here. Specific API set of common properties are defined here. Specific API
implementations SHOULD NOT re-use these fields with different implementations SHOULD NOT re-use these fields with different
semantics or syntax. The available values for these properties are semantics or syntax. The available values for these properties are
determined by the API being protected at the RS. determined by the API being protected at the RS. All values are
OPTIONAL at the discretion of the API definition.
actions (array of strings) The types of actions the client instance actions (array of strings): The types of actions the client instance
will take at the RS as an array of strings. For example, a client will take at the RS as an array of strings. For example, a client
instance asking for a combination of "read" and "write" access. instance asking for a combination of "read" and "write" access.
locations (array of strings) The location of the RS as an array of locations (array of strings): The location of the RS as an array of
strings. These strings are typically URIs identifying the strings. These strings are typically URIs identifying the
location of the RS. location of the RS.
datatypes (array of strings) The kinds of data available to the datatypes (array of strings): The kinds of data available to the
client instance at the RS's API as an array of strings. For client instance at the RS's API as an array of strings. For
example, a client instance asking for access to raw "image" data example, a client instance asking for access to raw "image" data
and "metadata" at a photograph API. and "metadata" at a photograph API.
identifier (string) A string identifier indicating a specific identifier (string): A string identifier indicating a specific
resource at the RS. For example, a patient identifier for a resource at the RS. For example, a patient identifier for a
medical API or a bank account number for a financial API. medical API or a bank account number for a financial API.
privileges (array of strings) The types or levels of privilege being privileges (array of strings): The types or levels of privilege
requested at the resource. For example, a client instance asking being requested at the resource. For example, a client instance
for administrative level access, or access when the resource owner asking for administrative level access, or access when the
is no longer online. resource owner is no longer online.
The following non-normative example is describing three kinds of The following non-normative example is describing three kinds of
access (read, write, delete) to each of two different locations and access (read, write, delete) to each of two different locations and
two different data types (metadata, images) for a single access token two different data types (metadata, images) for a single access token
using the fictitious photo-api type definition. using the fictitious photo-api type definition.
"access": [ "access": [
{ {
"type": "photo-api", "type": "photo-api",
"actions": [ "actions": [
skipping to change at page 107, line 50 skipping to change at page 111, line 50
By design, the protocol minimizes the need for any pre-flight By design, the protocol minimizes the need for any pre-flight
discovery. To begin a request, the client instance only needs to discovery. To begin a request, the client instance only needs to
know the endpoint of the AS and which keys it will use to sign the know the endpoint of the AS and which keys it will use to sign the
request. Everything else can be negotiated dynamically in the course request. Everything else can be negotiated dynamically in the course
of the protocol. of the protocol.
However, the AS can have limits on its allowed functionality. If the However, the AS can have limits on its allowed functionality. If the
client instance wants to optimize its calls to the AS before making a client instance wants to optimize its calls to the AS before making a
request, it MAY send an HTTP OPTIONS request to the grant request request, it MAY send an HTTP OPTIONS request to the grant request
endpoint to retrieve the server's discovery information. The AS MUST endpoint to retrieve the server's discovery information. The AS MUST
respond with a JSON document containing the following information: respond with a JSON document with Content-Type application/json
containing a single object with the following information:
grant_request_endpoint (string) REQUIRED. The location of the AS's grant_request_endpoint (string): The location of the AS's grant
grant request endpoint. The location MUST be a URL [RFC3986] with request endpoint. The location MUST be a URL [RFC3986] with a
a scheme component that MUST be https, a host component, and scheme component that MUST be https, a host component, and
optionally, port, path and query components and no fragment optionally, port, path and query components and no fragment
components. This URL MUST match the URL the client instance used components. This URL MUST match the URL the client instance used
to make the discovery request. to make the discovery request. REQUIRED.
interaction_start_modes_supported (array of strings) OPTIONAL. A interaction_start_modes_supported (array of strings): A list of the
list of the AS's interaction start methods. The values of this AS's interaction start methods. The values of this list
list correspond to the possible values for the interaction start correspond to the possible values for the interaction start
section (Section 2.5.1) of the request. section (Section 2.5.1) of the request. OPTIONAL.
interaction_finish_methods_supported (array of strings) OPTIONAL. A interaction_finish_methods_supported (array of strings): A list of
list of the AS's interaction finish methods. The values of this the AS's interaction finish methods. The values of this list
list correspond to the possible values for the method element of correspond to the possible values for the method element of the
the interaction finish section (Section 2.5.2) of the request. interaction finish section (Section 2.5.2) of the request.
OPTIONAL.
key_proofs_supported (array of strings) OPTIONAL. A list of the key_proofs_supported (array of strings): A list of the AS's
AS's supported key proofing mechanisms. The values of this list supported key proofing mechanisms. The values of this list
correspond to possible values of the proof field of the key correspond to possible values of the proof field of the key
section (Section 7.1) of the request. section (Section 7.1) of the request. OPTIONAL.
subject_formats_supported (array of strings) OPTIONAL. A list of sub_id_formats_supported (array of strings): A list of the AS's
the AS's supported subject identifier types. The values of this supported subject identifier formats. The values of this list
list correspond to possible values of the subject identifier correspond to possible values of the subject identifier section
section (Section 2.2) of the request. (Section 2.2) of the request. OPTIONAL.
assertions_supported (array of strings) OPTIONAL. A list of the assertion_formats_supported (array of strings): A list of the AS's
AS's supported assertion formats. The values of this list supported assertion formats. The values of this list correspond
correspond to possible values of the subject assertion section to possible values of the subject assertion section (Section 2.2)
(Section 2.2) of the request. of the request. OPTIONAL.
The information returned from this method is for optimization The information returned from this method is for optimization
purposes only. The AS MAY deny any request, or any portion of a purposes only. The AS MAY deny any request, or any portion of a
request, even if it lists a capability as supported. For example, a request, even if it lists a capability as supported. For example, a
given client instance can be registered with the mtls key proofing given client instance can be registered with the mtls key proofing
mechanism, but the AS also returns other proofing methods, then the mechanism, but the AS also returns other proofing methods from the
AS will deny a request from that client instance using a different discovery document, then the AS will still deny a request from that
proofing mechanism. client instance using a different proofing mechanism.
9.1. RS-first Method of AS Discovery 9.1. RS-first Method of AS Discovery
If the client instance calls an RS without an access token, or with If the client instance calls an RS without an access token, or with
an invalid access token, the RS MAY respond to the client instance an invalid access token, the RS MAY respond to the client instance
with an authentication header indicating that GNAP needs to be used with an authentication header indicating that GNAP needs to be used
to access the resource. The address of the GNAP endpoint MUST be to access the resource. The address of the GNAP endpoint MUST be
sent in the "as_uri" parameter. The RS MAY additionally return a sent in the "as_uri" parameter. The RS MAY additionally return a
resource reference that the client instance MAY use in its access resource reference that the client instance MAY use in its access
token request. This resource reference MUST be sufficient for at token request. This resource reference MUST be sufficient for at
skipping to change at page 109, line 33 skipping to change at page 114, line 10
single access token using the resource reference FWWIKYBQ6U56NL1 single access token using the resource reference FWWIKYBQ6U56NL1
received from the RS in addition to the dolphin-metadata resource received from the RS in addition to the dolphin-metadata resource
reference that the client instance has been configured with out of reference that the client instance has been configured with out of
band. band.
POST /tx HTTP/1.1 POST /tx HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/json Content-Type: application/json
Signature-Input: sig1=... Signature-Input: sig1=...
Signature: sig1=... Signature: sig1=...
Digest: sha256=... Content-Digest: sha-256=...
{ {
"access_token": { "access_token": {
"access": [ "access": [
"FWWIKYBQ6U56NL1", "FWWIKYBQ6U56NL1",
"dolphin-metadata" "dolphin-metadata"
] ]
}, },
"client": "KHRS6X63AJ7C7C4AZ9AO" "client": "KHRS6X63AJ7C7C4AZ9AO"
} }
If issued, the resulting access token would contain sufficient access If issued, the resulting access token would contain sufficient access
to be used at both referenced resources. to be used at both referenced resources.
10. Acknowledgements 10. Acknowledgements
The editors would like to thank the feedback of the following The editors would like to thank the feedback of the following
individuals for their reviews, implementations, and contributions: individuals for their reviews, implementations, and contributions:
Aeke Axeland, Aaron Parecki, Adam Omar Oueidat, Andrii Deinega, Åke Axeland, Aaron Parecki, Adam Omar Oueidat, Andrii Deinega,
Annabelle Backman, Dick Hardt, Dmitri Zagidulin, Dmitry Barinov, Annabelle Backman, Dick Hardt, Dmitri Zagidulin, Dmitry Barinov,
Fabien Imbault, Francis Pouatcha, George Fletcher, Haardik Haardik, Fabien Imbault, Florian Helmschmidt, Francis Pouatcha, George
Florian Helmschmidt, Hamid Massaoud, Jacky Yuan, Joseph Heenan, Fletcher, Haardik Haardik, Hamid Massaoud, Jacky Yuan, Joseph Heenan,
Justin Richer, Kathleen Moriarty, Mike Jones, Mike Varley, Nat Justin Richer, Kathleen Moriarty, Mike Jones, Mike Varley, Nat
Sakimura, Takahiko Kawasaki, Takahiro Tsuchiya. Sakimura, Takahiko Kawasaki, Takahiro Tsuchiya.
The editors would also like to thank the GNAP working group design The editors would also like to thank the GNAP working group design
team of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones, team of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones,
and Justin Richer, who incorporated elements from the XAuth and XYZ and Justin Richer, who incorporated elements from the XAuth and XYZ
proposals to create the first version of this document. proposals to create the first version of this document.
In addition, the editors would like to thank Aaron Parecki and Mike In addition, the editors would like to thank Aaron Parecki and Mike
Jones for insights into how to integrate identity and authentication Jones for insights into how to integrate identity and authentication
skipping to change at page 113, line 49 skipping to change at page 118, line 24
Finally, if multiple instances of client software each have the same Finally, if multiple instances of client software each have the same
key, then from GNAP's perspective, these are functionally the same key, then from GNAP's perspective, these are functionally the same
client instance as GNAP has no reasonable way to differentiate client instance as GNAP has no reasonable way to differentiate
between them. This situation could happen if multiple instances between them. This situation could happen if multiple instances
within a cluster can securely share secret information among within a cluster can securely share secret information among
themselves. Even though there are multiple copies of the software, themselves. Even though there are multiple copies of the software,
the shared key makes these copies all present as a single instance. the shared key makes these copies all present as a single instance.
It is considered bad practice to share keys between copies of It is considered bad practice to share keys between copies of
software unless they are very tightly integrated with each other and software unless they are very tightly integrated with each other and
can be closely managed. It is particularly bad practice to allow an can be closely managed. It is particularly bad practice to allow an
end-user to copy keys between client instances and to willingly use end user to copy keys between client instances and to willingly use
the same key in multiple instances. the same key in multiple instances.
12.4. Protection of Authorization Server 12.4. Protection of Authorization Server
The AS performs critical functions in GNAP, including authenticating The AS performs critical functions in GNAP, including authenticating
client software, managing interactions with end-users to gather client software, managing interactions with end users to gather
consent and provide notice, and issuing access tokens for client consent and provide notice, and issuing access tokens for client
instances to present to resource servers. As such, protecting the AS instances to present to resource servers. As such, protecting the AS
is central to any GNAP deployment. is central to any GNAP deployment.
If an attacker is able to gain control over an AS, they would be able If an attacker is able to gain control over an AS, they would be able
to create fraudulent tokens and manipulate registration information to create fraudulent tokens and manipulate registration information
to allow for malicious clients. These tokens and clients would be to allow for malicious clients. These tokens and clients would be
trusted by other components in the ecosystem under the protection of trusted by other components in the ecosystem under the protection of
the AS. the AS.
skipping to change at page 115, line 34 skipping to change at page 120, line 20
material to any parties on the request path, including any attackers, material to any parties on the request path, including any attackers,
sending these kinds of keys is prohibited. Symmetric keys can still sending these kinds of keys is prohibited. Symmetric keys can still
be used by client instances, but only a reference to the key and not be used by client instances, but only a reference to the key and not
its value can be sent. This allows the AS to use pre-registered its value can be sent. This allows the AS to use pre-registered
symmetric keys as well as key derivation schemes to take advantage of symmetric keys as well as key derivation schemes to take advantage of
symmetric cryptography but without requiring key distribution at symmetric cryptography but without requiring key distribution at
runtime, which would expose the keys in transit. runtime, which would expose the keys in transit.
Both the AS and client software can use systems such as hardware Both the AS and client software can use systems such as hardware
security modules to strengthen their key security storage and security modules to strengthen their key security storage and
generation for both asymmetric and symmetric keys. generation for both asymmetric and symmetric keys (see also
Section 7.1.2).
12.6. Generation of Access Tokens 12.6. Generation of Access Tokens
The content of access tokens need to be such that only the generating The content of access tokens need to be such that only the generating
AS would be able to create them, and the contents cannot be AS would be able to create them, and the contents cannot be
manipulated by an attacker to gain different or additional access manipulated by an attacker to gain different or additional access
rights. rights.
One method for accomplishing this is to use a cryptographically One method for accomplishing this is to use a cryptographically
random value for the access token, generated by the AS using a secure random value for the access token, generated by the AS using a secure
skipping to change at page 116, line 34 skipping to change at page 121, line 19
consequence, any RS that a bearer token is presented to has the consequence, any RS that a bearer token is presented to has the
technical capability of presenting that bearer token to another RS, technical capability of presenting that bearer token to another RS,
as long as the token is valid. It also means that any party that is as long as the token is valid. It also means that any party that is
able capture of the token value in storage or in transit is able to able capture of the token value in storage or in transit is able to
use the access token. While bearer tokens are inherently simpler, use the access token. While bearer tokens are inherently simpler,
this simplicity has been misapplied and abused in making needlessly this simplicity has been misapplied and abused in making needlessly
insecure systems. insecure systems.
In GNAP, key-bound access tokens are the default due to their higher In GNAP, key-bound access tokens are the default due to their higher
security properties. While bearer tokens can be used in GNAP, their security properties. While bearer tokens can be used in GNAP, their
use should be limited onto to cases where the simplicity benefits use should be limited to cases where the simplicity benefits outweigh
outweigh the significant security downsides. the significant security downsides.
12.8. Key-Bound Token Access Tokens 12.8. Key-Bound Access Tokens
Key-bound access tokens, as the name suggests, are bound to a Key-bound access tokens, as the name suggests, are bound to a
specific key and must be presented along with proof of that key specific key and must be presented along with proof of that key
during use. The key itself is not presented at the same time as the during use. The key itself is not presented at the same time as the
token, so even if a token value is captured, it cannot be used to token, so even if a token value is captured, it cannot be used to
make a new request. This is particularly true for an RS, which will make a new request. This is particularly true for an RS, which will
see the token value but will not see the keys used to make the see the token value but will not see the keys used to make the
request. request.
Key-bound access tokens provide this additional layer of protection Key-bound access tokens provide this additional layer of protection
skipping to change at page 117, line 13 skipping to change at page 122, line 5
related signing key material. related signing key material.
In addition to validating the signature of the presentation message In addition to validating the signature of the presentation message
itself, the RS also needs to ensure that the signing key used is itself, the RS also needs to ensure that the signing key used is
appropriate for the presented token. If an RS does not ensure that appropriate for the presented token. If an RS does not ensure that
the right keys were used to sign a message with a specific token, an the right keys were used to sign a message with a specific token, an
attacker would be able to capture an access token and sign the attacker would be able to capture an access token and sign the
request with their own keys, thereby negating the benefits of using request with their own keys, thereby negating the benefits of using
key-bound access tokens. key-bound access tokens.
The RS also needs to ensure that a sufficient portions of the message The RS also needs to ensure that sufficient portions of the message
are covered by the signature. Any items outside the signature could are covered by the signature. Any items outside the signature could
still affect the API's processing decisions, but these items would still affect the API's processing decisions, but these items would
not be strongly bound to the token presentation. As such, an not be strongly bound to the token presentation. As such, an
attacker could capture a valid request, then manipulate portions of attacker could capture a valid request, then manipulate portions of
the request outside of the signature envelope in order to cause the request outside of the signature envelope in order to cause
unwanted actions at the protected API. unwanted actions at the protected API.
Some key-bound tokens are susceptible to replay attacks, depending on Some key-bound tokens are susceptible to replay attacks, depending on
the details of the signing method used. If a signature method covers the details of the signing method used. If a signature method covers
only portions of a given request, that same signature proof can be only portions of a given request, that same signature proof can be
skipping to change at page 117, line 39 skipping to change at page 122, line 31
uniqueness constraints. The details of using these will vary uniqueness constraints. The details of using these will vary
depending on the key proofing mechanism in use, but for example, HTTP depending on the key proofing mechanism in use, but for example, HTTP
Message Signatures has both a created and nonce signature parameter Message Signatures has both a created and nonce signature parameter
as well as the ability to cover significant portions of the HTTP as well as the ability to cover significant portions of the HTTP
message. message.
12.9. Exposure of End-user Credentials to Client Instance 12.9. Exposure of End-user Credentials to Client Instance
As a delegation protocol, one of the main goals of GNAP is to prevent As a delegation protocol, one of the main goals of GNAP is to prevent
the client software from being exposed to any credentials or the client software from being exposed to any credentials or
information about the end-user or resource owner as a requirement of information about the end user or resource owner as a requirement of
the delegation process. By using the variety of interaction the delegation process. By using the variety of interaction
mechanisms, the resource owner can interact with the AS without ever mechanisms, the resource owner can interact with the AS without ever
authenticating to the client software, and without the client authenticating to the client software, and without the client
software having to impersonate the resource owner through replay of software having to impersonate the resource owner through replay of
their credentials. their credentials.
Consequently, no interaction methods defined in the GNAP core require Consequently, no interaction methods defined in the GNAP core require
the end-user to enter their credentials, but it is technologically the end user to enter their credentials, but it is technologically
possible for an extension to be defined to carry such values. Such possible for an extension to be defined to carry such values. Such
an extension would be dangerous as it would allow rogue client an extension would be dangerous as it would allow rogue client
software to directly collect, store, and replay the end-user's software to directly collect, store, and replay the end user's
credentials outside of any legitimate use within a GNAP request. credentials outside of any legitimate use within a GNAP request.
The concerns of such an extension could be mitigated through use of a The concerns of such an extension could be mitigated through use of a
challenge and response unlocked by the end user's credentials. For challenge and response unlocked by the end user's credentials. For
example, the AS presents a challenge as part of an interaction start example, the AS presents a challenge as part of an interaction start
method, and the client instance signs that challenge using a key method, and the client instance signs that challenge using a key
derived from a password presented by the end user. It would be derived from a password presented by the end user. It would be
possible for the client software to collect this password in a secure possible for the client software to collect this password in a secure
software enclave without exposing the password to the rest of the software enclave without exposing the password to the rest of the
client software or putting it across the wire to the AS. The AS can client software or putting it across the wire to the AS. The AS can
skipping to change at page 118, line 38 skipping to change at page 123, line 29
legitimate client instance. legitimate client instance.
A client instance needs to always be aware of which AS it is talking A client instance needs to always be aware of which AS it is talking
to throughout a grant process, and ensure that any callback for one to throughout a grant process, and ensure that any callback for one
AS does not get conflated with the callback to different AS. The AS does not get conflated with the callback to different AS. The
interaction finish hash calculate allows a client instance to protect interaction finish hash calculate allows a client instance to protect
against this kind of substitution, but only if the client instance against this kind of substitution, but only if the client instance
validates the hash. If the client instance does not use an validates the hash. If the client instance does not use an
interaction finish method or does not check the interaction finish interaction finish method or does not check the interaction finish
hash value, the compromised AS can be granted a valid access token on hash value, the compromised AS can be granted a valid access token on
behalf of the resource owner. See [attack-surfaces] for details of behalf of the resource owner. See [AXELAND2021] for details of one
one such attack, which has been since addressed in this document by such attack, which has been since addressed in this document by
including the grant endpoint in the interaction hash calculation. including the grant endpoint in the interaction hash calculation.
The client instance still needs to validate the hash for the attack The client instance still needs to validate the hash for the attack
to be prevented. to be prevented.
12.11. Processing of Client-Presented User Information 12.11. Processing of Client-Presented User Information
GNAP allows the client instance to present assertions and identifiers GNAP allows the client instance to present assertions and identifiers
of the current user to the AS as part of the initial request. This of the current user to the AS as part of the initial request. This
information should only ever be taken by the AS as a hint, since the information should only ever be taken by the AS as a hint, since the
AS has no way to tell if the represented person is present at the AS has no way to tell if the represented person is present at the
skipping to change at page 119, line 24 skipping to change at page 124, line 6
into account. into account.
For example, if a specific user is claimed to be present prior to For example, if a specific user is claimed to be present prior to
interaction, but a different user is shown to be present during interaction, but a different user is shown to be present during
interaction, the AS can either determine this to be an error or interaction, the AS can either determine this to be an error or
signal to the client instance through returned subject information signal to the client instance through returned subject information
that the current user has changed from what the client instance that the current user has changed from what the client instance
thought. This user information can also be used by the AS to thought. This user information can also be used by the AS to
streamline the interaction process when the user is present. For streamline the interaction process when the user is present. For
example, instead of having the user type in their account identifier example, instead of having the user type in their account identifier
during interaction at a redirected URL, the AS can immediately during interaction at a redirected URI, the AS can immediately
challenge the user for their account credentials. Alternatively, if challenge the user for their account credentials. Alternatively, if
an existing session is detected, the AS can determine that it matches an existing session is detected, the AS can determine that it matches
the identifier provided by the client and subsequently skip an the identifier provided by the client and subsequently skip an
explicit authentication event by the resource owner. explicit authentication event by the resource owner.
In cases where the AS trusts the client software more completely, due In cases where the AS trusts the client software more completely, due
to policy or by previous approval of a given client instance, the AS to policy or by previous approval of a given client instance, the AS
can take this user information as a statement that the user is can take this user information as a statement that the user is
present and could issue access tokens and release subject information present and could issue access tokens and release subject information
without interaction. The AS should only take such action in very without interaction. The AS should only take such action in very
skipping to change at page 120, line 49 skipping to change at page 125, line 16
Furthermore, it is the case that any clients using symmetric Furthermore, it is the case that any clients using symmetric
cryptography for key proofing mechanisms need to have their keys pre- cryptography for key proofing mechanisms need to have their keys pre-
registered. The registration should also include any information registered. The registration should also include any information
that would aid in the authorization process, such as a display name that would aid in the authorization process, such as a display name
and logo. The registration record can also limit a given client to and logo. The registration record can also limit a given client to
ask for certain kinds of information and access, or be limited to ask for certain kinds of information and access, or be limited to
specific interaction mechanisms at runtime. specific interaction mechanisms at runtime.
It also is sensible to pre-register client instances when the It also is sensible to pre-register client instances when the
software is acting autonomously, without the need for a runtime software is acting autonomously, without the need for a runtime
approval by a resource owner or any interaction with an end-user. In approval by a resource owner or any interaction with an end user. In
these cases, an AS needs to rest on the trust decisions that have these cases, an AS needs to rest on the trust decisions that have
been determined prior to runtime in determining what rights and been determined prior to runtime in determining what rights and
tokens to grant to a given client instance. tokens to grant to a given client instance.
However, it does not make sense to pre-register many types of However, it does not make sense to pre-register many types of
clients. Single-page applications (SPAs) and mobile/desktop clients. Single-page applications (SPAs) and mobile/desktop
applications in particular present problems with pre-registration. applications in particular present problems with pre-registration.
For SPAs, the instances are ephemeral in nature and long-term For SPAs, the instances are ephemeral in nature and long-term
registration of a single instance leads to significant storage and registration of a single instance leads to significant storage and
management overhead at the AS. For mobile applications, each management overhead at the AS. For mobile applications, each
installation of the client software is a separate instance, and installation of the client software is a separate instance, and
sharing a key among all instances would be detrimental to security as sharing a key among all instances would be detrimental to security as
the compromise of any single installation would compromise all copies the compromise of any single installation would compromise all copies
for all users. for all users.
An AS can treat these classes of client software differently from An AS can treat these classes of client software differently from
each other, perhaps by allowing access to certain high-value APIs each other, perhaps by allowing access to certain high-value APIs
only to pre-registered known clients, or by requiring an active end- only to pre-registered known clients, or by requiring an active end
user delegation of authority to any client software not pre- user delegation of authority to any client software not pre-
registered. registered.
An AS can also provide warnings and caveats to resource owners during An AS can also provide warnings and caveats to resource owners during
the authorization process, allowing the user to make an informed the authorization process, allowing the user to make an informed
decision regarding the software they are authorizing. For example, decision regarding the software they are authorizing. For example,
if the AS has done vetting of the client software and this specific if the AS has done vetting of the client software and this specific
instance, it can present a different authorization screen compared to instance, it can present a different authorization screen compared to
a client instance that is presenting all of its information at a client instance that is presenting all of its information at
runtime. runtime.
skipping to change at page 122, line 16 skipping to change at page 126, line 27
information it is displaying, allowing the resource owner to make a information it is displaying, allowing the resource owner to make a
more informed delegation decision. For example, an AS can visually more informed delegation decision. For example, an AS can visually
differentiate between a client instance that can be traced back to a differentiate between a client instance that can be traced back to a
specific developer's registration and an instance that has self- specific developer's registration and an instance that has self-
asserted its own key and display information. asserted its own key and display information.
12.14. Interception of Information in the Browser 12.14. Interception of Information in the Browser
Most information passed through the web-browser is susceptible to Most information passed through the web-browser is susceptible to
interception and possible manipulation by elements within the browser interception and possible manipulation by elements within the browser
such as scripts loaded within pages. Information in the URL is such as scripts loaded within pages. Information in the URI is
exposed through browser and server logs, and can also leak to other exposed through browser and server logs, and can also leak to other
parties through HTTP Referrer headers. parties through HTTP Referer headers.
GNAP's design limits the information passed directly through the GNAP's design limits the information passed directly through the
browser, allowing for opaque URLs in most circumstances. For the browser, allowing for opaque URIs in most circumstances. For the
redirect-based interaction finish mechanism, named query parameters redirect-based interaction finish mechanism, named query parameters
are used to carry unguessable opaque values. For these, GNAP are used to carry unguessable opaque values. For these, GNAP
requires creation and validation of a cryptographic hash to protect requires creation and validation of a cryptographic hash to protect
the query parameters added to the URL and associate them with an the query parameters added to the URI and associate them with an
ongoing grant process. The client instance has to properly validate ongoing grant process. The client instance has to properly validate
this hash to prevent an attacker from injecting an interaction this hash to prevent an attacker from injecting an interaction
reference intended for a different AS or client instance. reference intended for a different AS or client instance.
Several interaction start mechanisms use URLs created by the AS and Several interaction start mechanisms use URIs created by the AS and
passed to the client instance. While these URLs are opaque to the passed to the client instance. While these URIs are opaque to the
client instance, it's possible for the AS to include parameters, client instance, it's possible for the AS to include parameters,
paths, and other pieces of information that could leak security data paths, and other pieces of information that could leak security data
or be manipulated by a party in the middle of the transaction. or be manipulated by a party in the middle of the transaction.
12.15. Callback URL Manipulation 12.15. Callback URI Manipulation
The callback URL used in interaction finish mechanisms is defined by The callback URI used in interaction finish mechanisms is defined by
the client instance. This URL is opaque to the AS, but can contain the client instance. This URI is opaque to the AS, but can contain
information relevant to the client instance's operations. In information relevant to the client instance's operations. In
particular, the client instance can include state information to particular, the client instance can include state information to
allow the callback request to be associated with an ongoing grant allow the callback request to be associated with an ongoing grant
request. request.
Since this URL is exposed to the end-user's browser, it is Since this URI is exposed to the end user's browser, it is
susceptible to both logging and manipulation in transit before the susceptible to both logging and manipulation in transit before the
request is made to the client software. As such, a client instance request is made to the client software. As such, a client instance
should never put security-critical or private information into the should never put security-critical or private information into the
callback URL in a cleartext form. For example, if the client callback URI in a cleartext form. For example, if the client
software includes a post-redirect target URL in its callback URL to software includes a post-redirect target URI in its callback URI to
the AS, this target URL could be manipulated by an attacker, creating the AS, this target URI could be manipulated by an attacker, creating
an open redirector at the client. Instead, a client instance can use an open redirector at the client. Instead, a client instance can use
an unguessable identifier into the URL that can then be used by the an unguessable identifier into the URI that can then be used by the
client software to look up the details of the pending request. Since client software to look up the details of the pending request. Since
this approach requires some form of statefulness by the client this approach requires some form of statefulness by the client
software during the redirection process, clients that are not capable software during the redirection process, clients that are not capable
of holding state through a redirect should not use redirect-based of holding state through a redirect should not use redirect-based
interaction mechanisms. interaction mechanisms.
12.16. MTLS Message Integrity 12.16. Redirection Status Codes
As already described in [I-D.ietf-oauth-security-topics], a server
should never use the HTTP 307 status code to redirect a request that
potentially contains user credentials. If an HTTP redirect is used
for such a request, the HTTP status code 303 "See Other" should be
used instead.
The status code 307, as defined in the HTTP standard [RFC7231],
requires the user agent to preserve the method and body of a request,
thus submitting the body of the POST request to the redirect target.
In the HTTP standard [RFC7231], only the status code 303
unambiguously enforces rewriting the HTTP POST request to an HTTP GET
request, which eliminates the POST body from the redirected request.
For all other status codes, including status code 302, user agents
are allowed not to rewrite a POST request into a GET request and thus
to resubmit the body.
The use of status code 307 results in a vulnerability when using the
redirect interaction finish method (Section 3.3.5). With this
method, the AS potentially prompts the RO to enter their credentials
in a form that is then submitted back to the AS (using an HTTP POST
request). The AS checks the credentials and, if successful, may
directly redirect the RO to the client instance's redirect URI. Due
to the use of status code 307, the RO's user agent now transmits the
RO's credentials to the client instance. A malicious client instance
can then use the obtained credentials to impersonate the RO at the
AS.
Redirection away from the initial URI in an interaction session could
also leak information found in that initial URI through the HTTP
Referer header field, which would be sent by the user agent to the
redirect target. To avoid such leakage, a server can first redirect
to an internal interstitial page without any identifying or sensitive
information on the URI before processing the request. When the user
agent is ultimately redirected from this page, no part of the
original interaction URI will be found in the Referrer header.
12.17. MTLS Message Integrity
The MTLS key proofing mechanism (Section 7.3.2) provides a means for The MTLS key proofing mechanism (Section 7.3.2) provides a means for
a client instance to present a key using a certificate the TLS layer. a client instance to present a key using a certificate at the TLS
Since TLS protects the entire HTTP message in transit, verification layer. Since TLS protects the entire HTTP message in transit,
of the TLS client certificate presented with the message provides a verification of the TLS client certificate presented with the message
sufficient binding between the two. However, since TLS is provides a sufficient binding between the two. However, since TLS is
functioning at a separate layer from HTTP, there is no direct functioning at a separate layer from HTTP, there is no direct
connection between the TLS key presentation and the message itself, connection between the TLS key presentation and the message itself,
other than the fact that the message was presented over the TLS other than the fact that the message was presented over the TLS
channel. That is to say, any HTTP message can be presented over the channel. That is to say, any HTTP message can be presented over the
TLS channel in question with the same level of trust. The verifier TLS channel in question with the same level of trust. The verifier
is responsible for ensuring the key in the TLS client certificate is is responsible for ensuring the key in the TLS client certificate is
the one expected for a particular request. For example, if the the one expected for a particular request. For example, if the
request is a grant request (request), the AS needs to compare the TLS request is a grant request (Section 2), the AS needs to compare the
client certificate presented at the TLS layer to the key identified TLS client certificate presented at the TLS layer to the key
in the request body itself (either by value or through a referenced identified in the request body itself (either by value or through a
identifier). referenced identifier).
Furthermore, the prevalence of the TLS-terminating reverse proxy Furthermore, the prevalence of the TLS-terminating reverse proxy
(TTRP) pattern in deployments adds a wrinkle to the situation. In (TTRP) pattern in deployments adds a wrinkle to the situation. In
this common pattern, the TTRP validates the TLS connection and then this common pattern, the TTRP validates the TLS connection and then
forwards the HTTP message contents onward to an internal system for forwards the HTTP message contents onward to an internal system for
processing. The system processing the HTTP message no longer has processing. The system processing the HTTP message no longer has
access to the original TLS connection's information and context. To access to the original TLS connection's information and context. To
compensate for this, the TTRP could inject the TLS client certificate compensate for this, the TTRP could inject the TLS client certificate
into the forwarded request as a header parameter using into the forwarded request as a header parameter using
[I-D.ietf-httpbis-client-cert-field], giving the downstream system [I-D.ietf-httpbis-client-cert-field], giving the downstream system
access to the certificate information. The TTRP has to be trusted to access to the certificate information. The TTRP has to be trusted to
provide accurate certificate information, and the connection between provide accurate certificate information, and the connection between
the TTRP and the downstream system also has to be protected. The the TTRP and the downstream system also has to be protected. The
TTRP could provide some additional assurance, for example, by adding TTRP could provide some additional assurance, for example, by adding
its own signature to the Client-Cert header field using its own signature to the Client-Cert header field using
[I-D.ietf-httpbis-message-signatures]. This signature would be [I-D.ietf-httpbis-message-signatures]. This signature would be
effectively ignored by GNAP but understood by the downstream service effectively ignored by GNAP but understood by the downstream service
as part of its deployment. as part of its deployment.
Additional considerations for different types of deployment patterns Additional considerations for different types of deployment patterns
and key distribution mechanisms for MTLS are found in Section 12.17. and key distribution mechanisms for MTLS are found in Section 12.18.
12.17. MTLS Deployment Patterns 12.18. MTLS Deployment Patterns
GNAP does not specify how a client instance's keys could be made GNAP does not specify how a client instance's keys could be made
known to the AS ahead of time. Public Key Infrastructure (PKI) can known to the AS ahead of time. Public Key Infrastructure (PKI) can
be used to manage the keys used by client instances when calling the be used to manage the keys used by client instances when calling the
AS, allowing the AS to trust a root key from a trusted authority. AS, allowing the AS to trust a root key from a trusted authority.
This method is particularly relevant to the MTLS key proofing method, This method is particularly relevant to the MTLS key proofing method,
where the client instance presents its certificate to the AS as part where the client instance presents its certificate to the AS as part
of the TLS connection. An AS using PKI to validate the MTLS of the TLS connection. An AS using PKI to validate the MTLS
connection would need to ensure that the presented certificate was connection would need to ensure that the presented certificate was
issued by a trusted certificate authority before allowing the issued by a trusted certificate authority before allowing the
skipping to change at page 124, line 29 skipping to change at page 129, line 50
the AS. PKI has historically been difficult to deploy, especially at the AS. PKI has historically been difficult to deploy, especially at
scale, but it remains an appropriate solution for systems where the scale, but it remains an appropriate solution for systems where the
required overhead is not an impediment. required overhead is not an impediment.
MTLS in GNAP need not use a PKI backing, as self-signed certificates MTLS in GNAP need not use a PKI backing, as self-signed certificates
and certificates from untrusted authorities can still be presented as and certificates from untrusted authorities can still be presented as
part of a TLS connection. In this case, the verifier would validate part of a TLS connection. In this case, the verifier would validate
the connection but accept whatever certificate was presented by the the connection but accept whatever certificate was presented by the
client software. This specific certificate would then be bound to client software. This specific certificate would then be bound to
all future connections from that client software by being bound to all future connections from that client software by being bound to
the resulting access tokens. See Section 12.16 for more the resulting access tokens. See Section 12.17 for more
considerations on MTLS as a key proofing mechanism. considerations on MTLS as a key proofing mechanism.
12.18. Interception of Responses from the AS 12.19. Interception of Responses from the AS
Responses from the AS contain information vital to both the security Responses from the AS contain information vital to both the security
and privacy operations of GNAP. This information includes nonces and privacy operations of GNAP. This information includes nonces
used in cryptographic calculations, subject identifiers, assertions, used in cryptographic calculations, subject identifiers, assertions,
public keys, and information about what client software is requesting public keys, and information about what client software is requesting
and was granted. and was granted.
In addition, if bearer tokens are used or keys are issued alongside a In addition, if bearer tokens are used or keys are issued alongside a
bound access token, the response from the AS contains all information bound access token, the response from the AS contains all information
necessary for use of the contained access token. Any party that is necessary for use of the contained access token. Any party that is
capable of viewing such a response, such as an intermediary proxy, capable of viewing such a response, such as an intermediary proxy,
would be able to exfiltrate and use this token. If the access token would be able to exfiltrate and use this token. If the access token
is instead bound to the client instance's presented key, is instead bound to the client instance's presented key,
intermediaries no longer have sufficient information to use the intermediaries no longer have sufficient information to use the
token. They can still, however, gain information about the end user token. They can still, however, gain information about the end user
as well as the actions of the client software. as well as the actions of the client software.
12.19. Key Distribution 12.20. Key Distribution
The keys for client instances could be distributed as part of the The keys for client instances could be distributed as part of the
deployment process of instances of the client software. For example, deployment process of instances of the client software. For example,
an application installation framework could generate a keypair for an application installation framework could generate a keypair for
each copy of client software, then both install it into the client each copy of client software, then both install it into the client
software upon installation and registering that instance with the AS. software upon installation and registering that instance with the AS.
Additionally, it's possible for the AS to generate keys to be used Additionally, it's possible for the AS to generate keys to be used
with access tokens that are separate from the keys used by the client with access tokens that are separate from the keys used by the client
instance to request tokens. In this method, the AS would generate instance to request tokens. In this method, the AS would generate
the asymmetric keypair or symmetric key and return the entire key, the asymmetric keypair or symmetric key and return the entire key,
including all private signing information, to the client instance including all private signing information, to the client instance
alongside the access token itself. This approach would make alongside the access token itself. This approach would make
interception of the return from the token endpoint equivalent to that interception of the return from the token endpoint equivalent to that
of a bearer token, since all information required to use the access of a bearer token, since all information required to use the access
token would be present in the request. token would be present in the request.
12.20. Interaction Finish Modes and Polling 12.21. Interaction Finish Modes and Polling
During the interaction process, the client instance usually hands During the interaction process, the client instance usually hands
control of the user experience over to another component, beit the control of the user experience over to another component, beit the
system browser, another application, or some action the resource system browser, another application, or some action the resource
owner is instructed to take on another device. By using an owner is instructed to take on another device. By using an
interaction finish method, the client instance can be securely interaction finish method, the client instance can be securely
notified by the AS when the interaction is completed and the next notified by the AS when the interaction is completed and the next
phase of the protocol should occur. This process includes phase of the protocol should occur. This process includes
information that the client instance can use to validate the finish information that the client instance can use to validate the finish
call from the AS and prevent some injection, session hijacking, and call from the AS and prevent some injection, session hijacking, and
skipping to change at page 126, line 10 skipping to change at page 131, line 28
separate device. The smart device has to poll because the expected separate device. The smart device has to poll because the expected
behavior is that the interaction will take place on the separate behavior is that the interaction will take place on the separate
device, without a way to return information to the original device's device, without a way to return information to the original device's
context. context.
As such, developers need to weigh the risks of forgoing an As such, developers need to weigh the risks of forgoing an
interaction finish method against the deployment capabilities of the interaction finish method against the deployment capabilities of the
client software and its environment. Due to the increased security, client software and its environment. Due to the increased security,
an interaction finish method should be employed whenever possible. an interaction finish method should be employed whenever possible.
12.21. Storage of Information During Interaction and Continuation 12.22. Session Management for Interaction Finish Methods
When using an interaction finish method such as redirect or push, the
client instance receives an unsolicited HTTP request from an unknown
party. The client instance needs to be able to successfully
associate this incoming request with a specific pending grant request
being managed by the client instance. If the client instance is not
careful and precise about this, an attacker could associate their own
session at the client instance with a stolen interaction response.
The means of preventing this varies by the type of client software
and interaction methods in use. Some common patterns are enumerated
here.
If the end user interacts with the client instance through a web
browser and the redirect interaction finish method is used, the
client instance can ensure that the incoming HTTP request from the
finish method is presented in the same browser session that the grant
request was started in. This technique is particularly useful when
the redirect interaction start mode is used as well, since in many
cases the end user will follow the redirection with the same browser
that they are using to interact with the client instance. The client
instance can then store the relevant pending grant information in the
session, either in the browser storage directly (such as with a
single-page application) or in an associated session store on a back-
end server. In both cases, when the incoming request reaches the
client instance, the session information can be used to ensure that
the same party that started the request is present as the request
finishes.
Ensuring that the same party that started a request is present when
that request finishes can prevent phishing attacks, where an attacker
starts a request at an honest client instance and tricks an honest RO
into authorizing it. For example, if an honest end user (that also
acts as the RO) wants to start a request through a client instance
controlled by the attacker, the attacker can start a request at an
honest client instance and then redirect the honest end user to the
interaction URI from the attackers session with the honest client
instance. If the honest end user then fails to realize that it is
not authorizing the attacker-controlled client instance (with which
it started its request) but the honest client instance when
interacting with the AS, the attacker's session with the honest
client instance would be authorized. This would give the attacker
access to the honest end user's resources that the honest client
instance is authorized to access. However, if after the interaction
the AS redirects the honest end user back to the client instance
whose grant request the end user just authorized, the honest end user
is redirected to the honest client instance. The honest client
instance can then detect that it is not the party that started the
request that is present, since the request at the honest client
instance was started by the attacker, which can prevent the attack.
This is related to Section 12.13, because again the attack can be
prevented by the AS informing the user as much as possible about the
client instance that is to be authorized.
If the end user does not interact with the client instance through a
web browser or the interaction start method does not use the same
browser or device that the end user is interacting through (such as
the launch of a second device through a scannable code or
presentation of a user code) the client instance will not be able to
strongly associate an incoming HTTP request with an established
session with the end user. This is also true when the push
interaction finish method is used, since the HTTP request comes
directly from the interaction component of the AS. In these
circumstances, the client instance can at least ensure that the
incoming HTTP request can be uniquely associated with an ongoing
grant request by making the interaction finish callback URI unique
for the grant when making the interaction request (Section 2.5.2).
Mobile applications and other client instances that generally serve
only a single end user at a time can use this unique incoming URL to
differentiate between a legitimate incoming request and an attacker's
stolen request.
If the client instance does not have the ability to use an
interaction finish method, it can use polling to continue the
request. The tradeoffs of this approach are discussed in
Section 12.21, and if possible, an explicit interaction finish method
should be used instead.
12.23. Storage of Information During Interaction and Continuation
When starting an interactive grant request, a client application has When starting an interactive grant request, a client application has
a number of protocol elements that it needs to manage, including a number of protocol elements that it needs to manage, including
nonces, references, keys, access tokens, and other elements. During nonces, references, keys, access tokens, and other elements. During
the interaction process, the client instance usually hands control of the interaction process, the client instance usually hands control of
the user experience over to another component, beit the system the user experience over to another component, beit the system
browser, another application, or some action the resource owner is browser, another application, or some action the resource owner is
instructed to take on another device. In order for the client instructed to take on another device. In order for the client
instance to make its continuation call, it will need to recall all of instance to make its continuation call, it will need to recall all of
these protocol elements. Usually this means the client instance will these protocol elements. Usually this means the client instance will
need to store these protocol elements in some retrievable fashion. need to store these protocol elements in some retrievable fashion.
If the security protocol elements are stored on the end-user's If the security protocol elements are stored on the end user's
device, such as in browser storage or in local application data device, such as in browser storage or in local application data
stores, capture and exfiltration of this information could allow an stores, capture and exfiltration of this information could allow an
attacker to continue a pending transaction instead of the client attacker to continue a pending transaction instead of the client
instance. Client software can make use of secure storage mechanisms, instance. Client software can make use of secure storage mechanisms,
including hardware-based key and data storage, to prevent such including hardware-based key and data storage, to prevent such
exfiltration. exfiltration.
Note that in GNAP, the client instance has to choose its interaction Note that in GNAP, the client instance has to choose its interaction
finish URL prior to making the first call to the AS. As such, the finish URI prior to making the first call to the AS. As such, the
interaction finish URL will often have a unique identifier for the interaction finish URI will often have a unique identifier for the
ongoing request, allowing the client instance to access the correct ongoing request, allowing the client instance to access the correct
portion of its storage. Since this URL is passed to other parties portion of its storage. Since this URI is passed to other parties
and often used through a browser, this URL should not contain any and often used through a browser, this URI should not contain any
security-sensitive information that would be valuable to an attacker, security-sensitive information that would be valuable to an attacker,
such as any token identifier, nonce, or user information. Instead, a such as any token identifier, nonce, or user information. Instead, a
cryptographically random value is suggested. cryptographically random value is suggested.
12.22. Denial of Service (DoS) through Grant Continuation 12.24. Denial of Service (DoS) through Grant Continuation
When a client instance starts off an interactive process, it will When a client instance starts off an interactive process, it will
eventually need to continue the grant request in a subsequent message eventually need to continue the grant request in a subsequent message
to the AS. It's possible for a naive client implementation to to the AS. It's possible for a naive client implementation to
continuously send continuation requests to the AS while waiting for continuously send continuation requests to the AS while waiting for
approval, especially if no interaction finish method is used. Such approval, especially if no interaction finish method is used. Such
constant requests could overwhelm the AS's ability to respond to both constant requests could overwhelm the AS's ability to respond to both
these and other requests. these and other requests.
To mitigate this for well-behaved client software, the continuation To mitigate this for well-behaved client software, the continuation
skipping to change at page 127, line 20 skipping to change at page 134, line 20
client instance. client instance.
If client software ignores the wait value and makes its continuation If client software ignores the wait value and makes its continuation
calls too quickly, or if the client software assumes the absence of calls too quickly, or if the client software assumes the absence of
the wait values means it should poll immediately, the AS can choose the wait values means it should poll immediately, the AS can choose
to return errors to the offending client instance, including possibly to return errors to the offending client instance, including possibly
canceling the ongoing grant request. With well-meaning client canceling the ongoing grant request. With well-meaning client
software these errors can indicate a need to change the client software these errors can indicate a need to change the client
software's programmed behavior. software's programmed behavior.
12.23. Exhaustion of Random Value Space 12.25. Exhaustion of Random Value Space
Several parts of the GNAP process make use of unguessable randomized Several parts of the GNAP process make use of unguessable randomized
values, such as nonces, tokens, and randomized URLs. Since these values, such as nonces, tokens, and randomized URIs. Since these
values are intended to be unique, a sufficiently powerful attacker values are intended to be unique, a sufficiently powerful attacker
could make a large number of requests to trigger generation of could make a large number of requests to trigger generation of
randomized values in an attempt to exhaust the random number randomized values in an attempt to exhaust the random number
generation space. While this attack is particularly applicable to generation space. While this attack is particularly applicable to
the AS, client software could likewise be targeted by an attacker the AS, client software could likewise be targeted by an attacker
triggering new grant requests against an AS. triggering new grant requests against an AS.
To mitigate this, software can ensure that its random values are To mitigate this, software can ensure that its random values are
chosen from a significantly large pool that exhaustion of that pool chosen from a significantly large pool that exhaustion of that pool
is prohibitive for an attacker. Additionally, the random values can is prohibitive for an attacker. Additionally, the random values can
skipping to change at page 128, line 5 skipping to change at page 135, line 5
For example, the nonces used for interaction finish hash calculation For example, the nonces used for interaction finish hash calculation
need only to be valid while the client instance is waiting for the need only to be valid while the client instance is waiting for the
finish callback and can be functionally expired when the interaction finish callback and can be functionally expired when the interaction
has completed. Similarly, artifacts like access tokens and the has completed. Similarly, artifacts like access tokens and the
interaction reference can be limited to have lifetimes tied to their interaction reference can be limited to have lifetimes tied to their
functional utility. Finally, each different category of artifact functional utility. Finally, each different category of artifact
(nonce, token, reference, identifier, etc.) can be generated from a (nonce, token, reference, identifier, etc.) can be generated from a
separate random pool of values instead of a single global value separate random pool of values instead of a single global value
space. space.
12.24. Front-channel URLs 12.26. Front-channel URIs
Some interaction methods in GNAP make use of URLs accessed through Some interaction methods in GNAP make use of URIs accessed through
the end-user's browser, known collectively as front-channel the end user's browser, known collectively as front-channel
communication. These URLs are most notably present in the redirect communication. These URIs are most notably present in the redirect
interaction start method and the redirect interaction finish mode. interaction start method and the redirect interaction finish mode.
Since these URLs are intended to be given to the end-user, the end Since these URIs are intended to be given to the end user, the end
user and their browser will be subjected to anything hosted at that user and their browser will be subjected to anything hosted at that
URL including viruses, malware, and phishing scams. This kind of URI including viruses, malware, and phishing scams. This kind of
risk is inherent to all redirection-based protocols, including GNAP risk is inherent to all redirection-based protocols, including GNAP
when used in this way. when used in this way.
When talking to a new or unknown AS, a client instance might want to When talking to a new or unknown AS, a client instance might want to
check the URL from the interaction start against a blocklist and warn check the URI from the interaction start against a blocklist and warn
the end-user before redirecting them. Many client instances will the end user before redirecting them. Many client instances will
provide an interstitial message prior to redirection in order to provide an interstitial message prior to redirection in order to
prepare the user for control of the user experience being handed to prepare the user for control of the user experience being handed to
the domain of the AS, and such a method could be used to warn the the domain of the AS, and such a method could be used to warn the
user of potential threats. For instance, a rogue AS impersonating a user of potential threats. For instance, a rogue AS impersonating a
well-known service provider. Client software can also prevent this well-known service provider. Client software can also prevent this
by managing an allowlist of known and trusted AS's. by managing an allowlist of known and trusted AS's.
Alternatively, an attacker could start a GNAP request with a known Alternatively, an attacker could start a GNAP request with a known
and trusted AS but include their own attack site URL as the callback and trusted AS but include their own attack site URI as the callback
for the finish method. The attacker would then send the interaction for the redirect finish method. The attacker would then send the
start URL to the victim and get them to click on it. Since the URL interaction start URI to the victim and get them to click on it.
is at the known AS, the victim is inclined to do so. The victim will Since the URI is at the known AS, the victim is inclined to do so.
then be prompted to approve the attacker's application, and in most The victim will then be prompted to approve the attacker's
circumstances the victim will then be redirected to the attacker's application, and in most circumstances the victim will then be
site whether or not the user approved the request. The AS could redirected to the attacker's site whether or not the user approved
mitigate this partially by using a blocklist and allowlist of the request. The AS could mitigate this partially by using a
interaction finish URLs during the client instance's initial request, blocklist and allowlist of interaction finish URIs during the client
but this approach can be especially difficult if the URL has any instance's initial request, but this approach can be especially
dynamic portion chosen by the client software. The AS can couple difficult if the URI has any dynamic portion chosen by the client
these checks with policies associated with the client instance that software. The AS can couple these checks with policies associated
has been authenticated in the request. If the AS has any doubt about with the client instance that has been authenticated in the request.
the interaction finish URL, the AS can provide an interstitial If the AS has any doubt about the interaction finish URI, the AS can
warning to the end-user before processing the redirect. provide an interstitial warning to the end user before processing the
redirect.
Ultimately, all protocols that use redirect-based communication Ultimately, all protocols that use redirect-based communication
through the user's browser are susceptible to having an attacker try through the user's browser are susceptible to having an attacker try
to co-opt one or more of those URLs in order to harm the user. It is to co-opt one or more of those URIs in order to harm the user. It is
the responsibility of the AS and the client software to provide the responsibility of the AS and the client software to provide
appropriate warnings, education, and mitigation to protect end users. appropriate warnings, education, and mitigation to protect end users.
12.25. Processing Assertions 12.27. Processing Assertions
Identity assertions can be used in GNAP to convey subject Identity assertions can be used in GNAP to convey subject
information, both from the AS to the client instance in a response information, both from the AS to the client instance in a response
(Section 3.4) and from the client instance to the AS in a request (Section 3.4) and from the client instance to the AS in a request
(Section 2.2). In both of these circumstances, when an assertion is (Section 2.2). In both of these circumstances, when an assertion is
passed in GNAP, the receiver of the assertion needs to parse and passed in GNAP, the receiver of the assertion needs to parse and
process the assertion. As assertions are complex artifacts with process the assertion. As assertions are complex artifacts with
their own syntax and security, special care needs to be taken to their own syntax and security, special care needs to be taken to
prevent the assertion values from being used as an attack vector. prevent the assertion values from being used as an attack vector.
skipping to change at page 129, line 35 skipping to change at page 136, line 35
attacked through the use of processing instructions and entity attacked through the use of processing instructions and entity
expansions to cause problems with the processor. Therefore, any expansions to cause problems with the processor. Therefore, any
system capable of processing SAML 2 assertions also needs to have a system capable of processing SAML 2 assertions also needs to have a
secure and correct XML parser. In addition to this, the SAML 2 secure and correct XML parser. In addition to this, the SAML 2
specification uses XML Signatures, which have their own specification uses XML Signatures, which have their own
implementation problems that need to be accounted for. Similar implementation problems that need to be accounted for. Similar
requirements exist for OpenID Connect's ID token, which is based on requirements exist for OpenID Connect's ID token, which is based on
the JSON Web Token (JWT) format and the related JSON Object Signing the JSON Web Token (JWT) format and the related JSON Object Signing
And Encryption (JOSE) cryptography suite. And Encryption (JOSE) cryptography suite.
12.28. Stolen Token Replay
If a client instance can request tokens at multiple AS's, and the
client instance uses the same keys to make its requests across those
different AS's, then it is possible for an attacker to replay a
stolen token issued by an honest AS from a compromised AS, thereby
binding the stolen token to the client instance's key in a different
context. The attacker can manipulate the client instance into using
the stolen token at an RS, particularly at an RS that is expecting a
token from the honest AS. Since the honest AS issued the token and
the client instance presents the token with its expected bound key,
the attack succeeds.
This attack has several preconditions. In this attack, the attacker
does not need access to the client instance's key and cannot use the
stolen token directly at the RS, but the attacker is able to get the
access token value in some fashion. The client instance also needs
to be configured to talk to multiple AS's, including the attacker's
controlled AS. Finally, the client instance needs to be able to be
manipulated by the attacker to call the RS while using a token issued
from the stolen AS. The RS does not need to be compromised or made
to trust the attacker's AS.
To protect against this attack, the client instance can use a
different key for each AS that it talks to. Since the replayed token
will be bound to the key used at the honest AS, the uncompromised RS
will reject the call since the client instance will be using the key
used at the attacker's AS instead with the same token. When the MTLS
key proofing method is used, a client instance can use self-signed
certificates to use a different key for each AS that it talks to, as
discussed in Section 12.18.
Additionally, the client instance can keep a strong association
between the RS and a specific AS that it trusts to issue tokens for
that RS. This strong binding also helps against some forms of AS
mix-up attacks (Section 12.10). Managing this binding is outside the
scope of GNAP core, but it can be managed either as a configuration
element for the client instance or dynamically through discovering
the AS from the RS (Section 9.1).
The details of this attack are available in [HELMSCHMIDT2022] with
additional discussion and considerations.
12.29. Self-contained Stateless Access Tokens
The contents and format of the access token are at the discretion of
the AS, and are opaque to the client instance within GNAP. As
discussed in the companion document,
[I-D.ietf-gnap-resource-servers], the AS and RS can make use of
stateless access tokens with an internal structure and format. These
access tokens allow an RS to validate the token without having to
make any external calls at runtime, allowing for benefits in some
deployments, the discussion of which are outside the scope of this
specification.
However, the use of such self-contained access tokens has an effect
on the ability of the AS to provide certain functionality defined
within this specification. Specifically, since the access token is
self-contained, it is difficult or impossible for an AS to signal to
all RS's within an ecosystem when a specific access token has been
revoked. Therefore, an AS in such an ecosystem should probably not
offer token revocation functionality to client instances, since the
client instance's calls to such an endpoint is effectively
meaningless. However, a client instance calling the token revocation
function will also throw out its copy of the token, so such a placebo
endpoint might not be completely meaningless. Token rotation
similarly difficult because the AS has to revoke the old access token
after a rotation call has been made. If the access tokens are
completely self-contained and non-revocable, this means that there
will be a period of time during which both the old and new access
tokens are valid and usable, which is an increased security risk for
the environment.
These problems can be mitigated by keeping the validity time windows
of self-contained access tokens reasonably short, limiting the time
after a revocation event that a revoked token could be used.
Additionally, the AS could proactively signal to RS's under its
control identifiers for revoked tokens that have yet to expire. This
type of information push would be expected to be relatively small and
infrequent, and its implementation is outside the scope of this
specification.
12.30. Network Problems and Token and Grant Management
If a client instance makes a call to rotate an access token but the
network connection is dropped before the client instance receives the
response with the new access token, the system as a whole can end up
in an inconsistent state, where the AS has already rotated the old
access token and invalidated it, but the client instance only has
access to the invalidated access token and not the newly rotated
token value. If the client instance retries the rotation request, it
would fail because the client is no longer presenting a valid and
current access token. A similar situation can occur during grant
continuation, where the same client instance calls to continue or
update a grant request without successfully receiving the results of
the update.
To combat this, both grant Management (Section 5) and token
management (Section 6) are designed to be idempotent, where
subsequent calls to the same function with the same credentials are
meant to produce the same results. For example, multiple calls to
rotate the same access token need to result in the same rotated token
value.
In practice, an AS can hold on to an old token value for such limited
purposes. For example, to support rotating access tokens over
unreliable networks, the AS receives the initial request to rotate an
access token and creates a new token value and returns it. The AS
also marks the old token value as having been used to create the
newly-rotated token value. If the AS sees the old token value within
a small enough time window, such as a few seconds since the first
rotation attempt, the AS can return the same rotated access token.
Furthermore, once the system has seen the newly-rotated token in use,
the original token can be discarded because the client instance has
proved that it did receive the token. The result of this is a system
that is eventually self-consistent without placing an undue
complexity burden on the client instance.
12.31. Server-side Request Forgery (SSRF)
There are several places within GNAP where a URI can be given to a
party causing it to fetch that URI during normal operation of the
protocol. If an attacker is able to control the value of one of
these URIs within the protocol, the attacker could cause the target
system to execute a request on a URI that is within reach of the
target system but normally unavailable to the attacker. For example,
an attacker sending a URL of http://localhost/admin to cause the
server to access an internal function on itself, or
https://192.168.0.14/ to call a service behind a firewall. Even if
the attacker does not gain access to the results of the call, the
side effects of such requests coming from a trusted host can be
problematic to the security and sanctity of such otherwise unexposed
endpoints.
In GNAP, the most vulnerable place in the core protocol is the
push-based post-interaction finish method (Section 4.2.2), as the
client instance is less trusted than the AS and can use this method
to make the AS call an arbitrary URI. While it is not required by
the protocol, the AS can fetch other client-instance provided URIs
such as the logo image or home page, for verification or privacy-
preserving purposes before displaying them to the resource owner as
part of a consent screen. Furthermore, extensions to GNAP that allow
or require URI fetch could also be similarly susceptible, such as a
system for having the AS fetch a client instance's keys from a
presented URI instead of the client instance presenting the key by
value. Such extensions are outside the scope of this specification,
but any system deploying such an extension would need to be aware of
this issue.
To help mitigate this problem, similar approaches to protecting
parties against malicious redirects (Section 12.26) can be used. For
example, all URIs that can result in a direct request being made by a
party in the protocol can be filtered through an allowlist or
blocklist. For example, an AS that supports the push based
interaction finish can compare the callback URI in the interaction
request to a known URI for a pre-registered client instance, or it
can ensure that the URI is not on a blocklist of sensitive URLs such
as internal network addresses. However, note that because these
types of calls happen outside of the view of human interaction, it is
not usually feasible to provide notification and warning to someone
before the request needs to be executed, as is the case with
redirection URLs. As such, SSRF is somewhat more difficult to manage
at runtime, and systems should generally refuse to fetch a URI if
unsure.
13. Privacy Considerations 13. Privacy Considerations
The privacy considerations in this section are modeled after the list The privacy considerations in this section are modeled after the list
of privacy threats in [RFC6973], "Privacy Considerations for Internet of privacy threats in [RFC6973], "Privacy Considerations for Internet
Protocols", and either explain how these threats are mitigated or Protocols", and either explain how these threats are mitigated or
advise how the threats relate to GNAP. advise how the threats relate to GNAP.
13.1. Surveillance 13.1. Surveillance
Surveillance is the observation or monitoring of an individual's Surveillance is the observation or monitoring of an individual's
skipping to change at page 131, line 6 skipping to change at page 141, line 42
Several parties in the GNAP process are expected to persist data at Several parties in the GNAP process are expected to persist data at
least temporarily, if not semi-permanently, for the normal least temporarily, if not semi-permanently, for the normal
functioning of the system. If compromised, this could lead to functioning of the system. If compromised, this could lead to
exposure of sensitive information. This section documents the exposure of sensitive information. This section documents the
potentially sensitive information each party in GNAP is expected to potentially sensitive information each party in GNAP is expected to
store for normal operation. Naturally it is possible that any party store for normal operation. Naturally it is possible that any party
is storing information for longer than technically necessary of the is storing information for longer than technically necessary of the
protocol mechanics (such as audit logs, etc). protocol mechanics (such as audit logs, etc).
The authorization server is expected to store subject identifiers for The authorization server is expected to store subject identifiers for
user indefinitely, in order to be able to include them in the users indefinitely, in order to be able to include them in the
responses to clients. The authorization server is also expected to responses to clients. The authorization server is also expected to
store client key identifiers associated with display information store client key identifiers associated with display information
about the client such as its name and logo. about the client such as its name and logo.
The client is expected to store its client instance key indefinitely, The client is expected to store its client instance key indefinitely,
in order to authenticate to the authorization server for the normal in order to authenticate to the authorization server for the normal
functioning of the GNAP flows. Additionally, the client will be functioning of the GNAP flows. Additionally, the client will be
temporarily storing artifacts issued by the authorization server temporarily storing artifacts issued by the authorization server
during a flow, and these artifacts SHOULD be discarded by the client during a flow, and these artifacts SHOULD be discarded by the client
when the transaction is complete. when the transaction is complete.
skipping to change at page 133, line 47 skipping to change at page 144, line 23
Richer, J., Parecki, A., and F. Imbault, "Grant Richer, J., Parecki, A., and F. Imbault, "Grant
Negotiation and Authorization Protocol Resource Server Negotiation and Authorization Protocol Resource Server
Connections", Work in Progress, Internet-Draft, draft- Connections", Work in Progress, Internet-Draft, draft-
ietf-gnap-resource-servers-01, 12 July 2021, ietf-gnap-resource-servers-01, 12 July 2021,
<https://www.ietf.org/archive/id/draft-ietf-gnap-resource- <https://www.ietf.org/archive/id/draft-ietf-gnap-resource-
servers-01.txt>. servers-01.txt>.
[I-D.ietf-httpbis-digest-headers] [I-D.ietf-httpbis-digest-headers]
Polli, R. and L. Pardue, "Digest Fields", Work in Polli, R. and L. Pardue, "Digest Fields", Work in
Progress, Internet-Draft, draft-ietf-httpbis-digest- Progress, Internet-Draft, draft-ietf-httpbis-digest-
headers-06, 27 September 2021, headers-07, 16 November 2021,
<https://www.ietf.org/archive/id/draft-ietf-httpbis- <https://www.ietf.org/archive/id/draft-ietf-httpbis-
digest-headers-06.txt>. digest-headers-07.txt>.
[I-D.ietf-httpbis-message-signatures] [I-D.ietf-httpbis-message-signatures]
Backman, A., Richer, J., and M. Sporny, "HTTP Message Backman, A., Richer, J., and M. Sporny, "HTTP Message
Signatures", Work in Progress, Internet-Draft, draft-ietf- Signatures", Work in Progress, Internet-Draft, draft-ietf-
httpbis-message-signatures-06, 13 August 2021, httpbis-message-signatures-09, 6 March 2022,
<https://www.ietf.org/archive/id/draft-ietf-httpbis- <https://www.ietf.org/archive/id/draft-ietf-httpbis-
message-signatures-06.txt>. message-signatures-09.txt>.
[I-D.ietf-oauth-rar] [I-D.ietf-oauth-rar]
Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0
Rich Authorization Requests", Work in Progress, Internet- Rich Authorization Requests", Work in Progress, Internet-
Draft, draft-ietf-oauth-rar-08, 18 October 2021, Draft, draft-ietf-oauth-rar-10, 26 January 2022,
<https://www.ietf.org/archive/id/draft-ietf-oauth-rar- <https://www.ietf.org/archive/id/draft-ietf-oauth-rar-
08.txt>. 10.txt>.
[I-D.ietf-secevent-subject-identifiers] [I-D.ietf-secevent-subject-identifiers]
Backman, A. and M. Scurtescu, "Subject Identifiers for Backman, A. and M. Scurtescu, "Subject Identifiers for
Security Event Tokens", Work in Progress, Internet-Draft, Security Event Tokens", Work in Progress, Internet-Draft,
draft-ietf-secevent-subject-identifiers-08, 24 May 2021, draft-ietf-secevent-subject-identifiers-09, 25 February
<https://www.ietf.org/archive/id/draft-ietf-secevent- 2022, <https://www.ietf.org/archive/id/draft-ietf-
subject-identifiers-08.txt>. secevent-subject-identifiers-09.txt>.
[OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
C. Mortimore, "OpenID Connect Core 1.0 incorporating C. Mortimore, "OpenID Connect Core 1.0 incorporating
errata set 1", November 2014, errata set 1", November 2014,
<https://openid.net/specs/openid-connect-core-1_0.html>. <https://openid.net/specs/openid-connect-core-1_0.html>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", [RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397,
RFC 3230, DOI 10.17487/RFC3230, January 2002, DOI 10.17487/RFC2397, August 1998,
<https://www.rfc-editor.org/info/rfc3230>. <https://www.rfc-editor.org/info/rfc2397>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>.
[RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
September 2009, <https://www.rfc-editor.org/info/rfc5646>. September 2009, <https://www.rfc-editor.org/info/rfc5646>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012, RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/info/rfc6749>. <https://www.rfc-editor.org/info/rfc6749>.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, Framework: Bearer Token Usage", RFC 6750,
DOI 10.17487/RFC6750, October 2012, DOI 10.17487/RFC6750, October 2012,
<https://www.rfc-editor.org/info/rfc6750>. <https://www.rfc-editor.org/info/rfc6750>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014,
<https://www.rfc-editor.org/info/rfc7231>.
[RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
RFC 7234, DOI 10.17487/RFC7234, June 2014, RFC 7234, DOI 10.17487/RFC7234, June 2014,
<https://www.rfc-editor.org/info/rfc7234>. <https://www.rfc-editor.org/info/rfc7234>.
[RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX,
PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468,
April 2015, <https://www.rfc-editor.org/info/rfc7468>. April 2015, <https://www.rfc-editor.org/info/rfc7468>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
skipping to change at page 136, line 5 skipping to change at page 146, line 31
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>.
[RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu,
"Handling Long Lines in Content of Internet-Drafts and "Handling Long Lines in Content of Internet-Drafts and
RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020,
<https://www.rfc-editor.org/info/rfc8792>. <https://www.rfc-editor.org/info/rfc8792>.
14.2. Informative References 14.2. Informative References
[attack-surfaces] [AXELAND2021]
Axeland, Å. and O. Oueidat, "Security Analysis of Attack Axeland, Å. and O. Oueidat, "Security Analysis of Attack
Surfaces on the Grant Negotiation and Authorization Surfaces on the Grant Negotiation and Authorization
Protocol", 2021, Protocol", 2021,
<https://odr.chalmers.se/handle/20.500.12380/304105>. <https://odr.chalmers.se/handle/20.500.12380/304105>.
[HELMSCHMIDT2022]
Helmschmidt, F., "tbd", 2022, <tbd>.
[I-D.ietf-httpbis-client-cert-field] [I-D.ietf-httpbis-client-cert-field]
Campbell, B. and M. Bishop, "Client-Cert HTTP Header Campbell, B. and M. Bishop, "Client-Cert HTTP Header
Field: Conveying Client Certificate Information from TLS Field", Work in Progress, Internet-Draft, draft-ietf-
Terminating Reverse Proxies to Origin Server httpbis-client-cert-field-01, 25 January 2022,
Applications", Work in Progress, Internet-Draft, draft-
ietf-httpbis-client-cert-field-00, 8 June 2021,
<https://www.ietf.org/archive/id/draft-ietf-httpbis-<