idnits 2.17.1 draft-hardt-gnap-advanced-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 7 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (15 August 2020) is 1321 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'Format TBD' is mentioned on line 289, but not defined ** Downref: Normative reference to an Informational RFC: RFC 4949 -- Possible downref: Non-RFC (?) normative reference: ref. 'GNAP' Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Hardt, Ed. 3 Internet-Draft SignIn.Org 4 Intended status: Standards Track 15 August 2020 5 Expires: 16 February 2021 7 The Grant Negotiation and Authorization Protocol - Advanced Features 8 draft-hardt-gnap-advanced-01 10 Abstract 12 TBD 14 Status of This Memo 16 This Internet-Draft is submitted in full conformance with the 17 provisions of BCP 78 and BCP 79. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF). Note that other groups may also distribute 21 working documents as Internet-Drafts. The list of current Internet- 22 Drafts is at https://datatracker.ietf.org/drafts/current/. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 This Internet-Draft will expire on 16 February 2021. 31 Copyright Notice 33 Copyright (c) 2020 IETF Trust and the persons identified as the 34 document authors. All rights reserved. 36 This document is subject to BCP 78 and the IETF Trust's Legal 37 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 38 license-info) in effect on the date of publication of this document. 39 Please review these documents carefully, as they describe your rights 40 and restrictions with respect to this document. Code Components 41 extracted from this document must include Simplified BSD License text 42 as described in Section 4.e of the Trust Legal Provisions and are 43 provided without warranty as described in the Simplified BSD License. 45 Table of Contents 47 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 48 2. Grant Management APIs . . . . . . . . . . . . . . . . . . . . 4 50 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 52 2.1. List Grants . . . . . . . . . . . . . . . . . . . . . . . 4 53 2.2. Update Grant . . . . . . . . . . . . . . . . . . . . . . 4 54 2.3. Delete Grant . . . . . . . . . . . . . . . . . . . . . . 5 55 2.4. Grant Options . . . . . . . . . . . . . . . . . . . . . . 5 56 3. Authorization Management APIs . . . . . . . . . . . . . . . . 5 57 3.1. Update Access . . . . . . . . . . . . . . . . . . . . . . 6 58 3.2. Delete Access . . . . . . . . . . . . . . . . . . . . . . 6 59 3.3. Access Options . . . . . . . . . . . . . . . . . . . . . 6 60 4. Reciprocal Grant . . . . . . . . . . . . . . . . . . . . . . 7 61 5. GS Initiated Grant . . . . . . . . . . . . . . . . . . . . . 8 62 6. User Exists . . . . . . . . . . . . . . . . . . . . . . . . . 9 63 7. Multiple Interactions . . . . . . . . . . . . . . . . . . . . 10 64 8. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 12 65 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 66 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 67 11. Security Considerations . . . . . . . . . . . . . . . . . . . 12 68 12. Normative References . . . . . . . . . . . . . . . . . . . . 12 69 Appendix A. Document History . . . . . . . . . . . . . . . . . . 12 70 A.1. draft-hardt-gnap-advanced-00 . . . . . . . . . . . . . . 12 71 A.2. draft-hardt-gnap-advanced-01 . . . . . . . . . . . . . . 13 72 Appendix B. GS API Table . . . . . . . . . . . . . . . . . . . . 13 73 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 75 1. Introduction 77 This document includes additional features for the Grant Negotiation 78 and Authorization Protocol (GNAP) [GNAP], and presumes familiarity 79 and knowledge of GNAP. 81 *Terminology* 83 This document uses the following terms defined in [GNAP]: 85 * authN 87 * authZ 89 * Access 91 * Access URI 93 * Claim 95 * Grant Client (GC) 97 * Registered Client 99 * Grant 101 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 103 * Grant Server (GS) 105 * Grant URI 107 * Grant Request 109 * Grant Response 111 * GS URI 113 * Interaction 115 * NumericDate 117 * Resource Owner (RO) 119 * Resource Server (RS) 121 * User 123 *Notational Conventions* 125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 126 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 127 specification are to be interpreted as described in [RFC2119]. 129 Certain security-related terms are to be understood in the sense 130 defined in [RFC4949]. These terms include, but are not limited to, 131 "attack", "authentication", "authorization", "certificate", 132 "confidentiality", "credential", "encryption", "identity", "sign", 133 "signature", "trust", "validate", and "verify". 135 Unless otherwise noted, all the protocol parameter names and values 136 are case sensitive. 138 Some protocol parameters are parts of a JSON document, and are 139 referred to in JavaScript notation. For example, foo.bar refers to 140 the "bar" boolean attribute in the "foo" object in the following 141 example JSON document: 143 { 144 "foo" : { 145 "bar": true 146 } 147 } 149 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 151 2. Grant Management APIs 153 In addition to creating and reading a Grant as specified in GNAP The 154 GC MAY list, update, delete, and discover a Grant. 156 2.1. List Grants 158 The GC MAY list the Grants provided to the GC by doing an a GET on 159 the GS URI. The GS MUST respond with a list of Grant URIs [ format 160 TBD] or one of the following errors: 162 * TBD 164 from Error Responses Section 8. 166 2.2. Update Grant 168 The GC updates a Grant by doing an HTTP PUT of a JSON document to the 169 corresponding Grant URI. 171 The JSON document MUST include the following from the [GNAP] Grant 172 Request JSON: 174 * iat 176 * uri set to the Grant URI 178 and MAY include the following from the [GNAP] Grant Request JSON: 180 * user 182 * interaction 184 * authorization or authorizations 186 * claims 188 The GS MUST respond with one of the standard GNAP responses (Grant 189 Response, Interaction Response, Wait Response) or one of the 190 following errors: 192 * TBD 194 from Error Responses Section 8. 196 Following is a non-normative example where the GC wants to update the 197 Grant Request with additional claims: 199 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 201 { 202 "iat" : 15790460234, 203 "uri" : "https://as.example/endpoint/grant/example3", 204 "claims": { 205 "oidc": { 206 "userinfo" : { 207 "email" : { "essential" : true }, 208 "name" : { "essential" : true }, 209 "picture" : null 210 } 211 } 212 } 213 } 215 2.3. Delete Grant 217 The GC deletes a Grant by doing an HTTP DELETE of the corresponding 218 Grant URI. 220 The GS MUST respond with OK 200, or one of the following errors: 222 * TBD 224 from Error Responses Section 8. 226 2.4. Grant Options 228 The GC can get the supported operations for a Grant by doing an HTTP 229 OPTIONS of the corresponding Grant URI. 231 The GS MUST respond with the supported methods 233 [Format TBD] 235 or one of the following errors: 237 * TBD 239 from Error Responses Section 8. 241 3. Authorization Management APIs 243 In addition to reading an Authorization as specified in [GNAP], The 244 GC MAY update, delete, and discover an Authorization. 246 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 248 3.1. Update Access 250 The GC updates an Authorization by doing an HTTP PUT to the 251 corresponding Access URI of the following JSON. All of the following 252 MUST be included. 254 * *iat* - the time of the request as a NumericDate. 256 * *uri* - the Access URI. 258 * *access* - the new access requested per the [GNAP] Grant Request 259 JSON "access" object. 261 The GS MUST respond with a GNAP Access JSON document, or one of the 262 following errors: 264 * TBD 266 from Error Responses Section 8. 268 3.2. Delete Access 270 The GC deletes an Access by doing an HTTP DELETE to the corresponding 271 Access URI. 273 The GS MUST respond with OK 200, or one of the following errors: 275 * TBD 277 from Error Responses Section 8. 279 A GS MAY indicate support for this feature by including the "DELETE" 280 method in the Access URI OPTIONS response. 282 3.3. Access Options 284 The GC can get the supported operations for an Access by doing an 285 HTTP OPTIONS of the corresponding Access URI. 287 The GS MUST respond with the supported methods 289 [Format TBD] 291 or one of the following errors: 293 * TBD 295 from Error Responses Section 8. 297 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 299 4. Reciprocal Grant 301 Party A and Party B both want to obtain a Grant from the other party. 302 Each party will be both Grant Client and Grant Server. This would 303 require two complete GNAP flows with an awkward redirect between 304 them, and the User may have to authenticate multiple times as context 305 is lost. Reciprocal Grant simplifies the User experience. 307 In the following sequence, steps 1 - 7 & 9 are a standard GNAP 308 sequence. 310 Party A Party B 311 +--------+ +--------+ 312 | | | | 313 | Client |--(1)-- Create Grant A ->| GS | 314 | | | | 315 | Client |<--- Interaction ---(2)--| GS | 316 | | Response | | 317 | | | | 318 | Client |--(3)--- Read Grant A -->| GS | +---+ 319 | | | | | U | 320 | Client |--(4)--- Interaction --- | - - - | ----->| s | 321 | | Transfer | | | e | 322 | | | GS |<-(5)->| r | 323 | | | | authN | | 324 | | | GS |<-(6)->| | 325 | | | | authZ | | 326 | Client |<------- Grant A ---(7)--| GS | +---+ 327 | | Response | | 328 | | | | 329 | GS |<- Create Grant B --(8)--| Client | 330 +---+ | | user.reciprocal | | 331 | U | | | | | 332 | s |<------ | - - - | --- Interaction --(9)---| GS | 333 | e | | | Transfer | | 334 | r |<-(10)->| GS | | | 335 | | AuthZ | | | | 336 +---+ | GS |--(11)-- Grant B ------->| Client | 337 | | Response | | 338 +--------+ +--------+ 340 Client = Grant Client 342 1. *Create Grant A* Party A makes a Create Grant request to the 343 Party B GS URI. 345 2. *Interaction Response* Party B returns an interaction response 346 containing the Grant A URI. 348 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 350 3. *Read Grant A* Party A does an HTTP GET of the Grant A URI. 352 4. *Interaction Transfer* Party A transfers User interaction to the 353 Party B. 355 5. *User Authentication* Party B authenticates the User. 357 6. *User Authorization* If required, Party B interacts with the 358 User to determine which identity claims and/or authorizations in 359 the Grant A Request are to be granted. 361 7. *Create GrantB* Party B creates its Grant B Request with 362 user.reciprocal set to the Grant A URI that will be in the step 363 (2) Grant A Response, and sends it with an HTTP POST to the 364 Party A GS URI. This enables Party A to correlate the Grant B 365 Request and its Grant and the User. 367 8. *Grant S Response* Party B responds to Party A's Create Grant A 368 Request with a Grant A Response. 370 9. *Interaction Transfer* Party B redirects the User to the 371 Completion URI at Party A. 373 10. *User Authorization* If required, Party A interacts with the 374 User to determine which identity claims and/or authorizations in 375 Party B's Grant B Request are to be granted. 377 11. *Grant B Response* Party A responds with the Grant B Response. 379 * *reciprocal* - a new attribute of the [GNAP] Request JSON user 380 object. MUST be set to a Grant URI. 382 5. GS Initiated Grant 384 The User is at the GS, and wants to interact with a Registered 385 Client. The GC has previously configured an initiation_uri at the 386 GS, and the Grant it requires. 388 In this sequence, the GS creates a Grant and redirects the User to 389 the GC's initiation_uri passing a Grant URI: 391 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 393 +--------+ +-------+ +------+ 394 | GC | | GS | | User | 395 | | | |<--(1)-->| | 396 | | | | | | 397 | |<----- GS Initiation Redirect --- | - - - | --(2)---| | 398 | (3) | | | | | 399 | verify |--(4)--- Read Grant ------------->| | +------+ 400 | | | | 401 | |<--------- Grant Response --(5)---| | 402 | | | | 403 +--------+ +-------+ 405 1. *User Interaction* The GS interacts with the User to determine 406 the GC and what identity claims and / or authorizations to 407 provide. The GS creates a Grant and corresponding Grant URI. 409 2. *GS Initiated Redirect* The GS redirects the User to the GC's 410 initiation_uri, adding a query parameter with the name 411 "grant_uri" and the value being the URL encoded Grant URI. 413 3. *Client Verification* The GC verifies the Grant URI starts with a 414 GS URI from a GS the GC trusts. 416 4. *Read Grant* The GC does an HTTP GET of the Grant URI. 418 5. *Grant Response* The GS responds with a Grant Response. 420 * *initiation_uri* - a URI at the GC that contains no query or 421 fragment. How the GS learns the GC initiation_uri and require 422 Grant is out of scope of this document. 424 6. User Exists 426 The GC may want to provide a different experience to the User 427 depending on if a User already exists at the GS. By including one or 428 more identifiers in the Grant Request user.identifiers object, and 429 setting user.exists to true, the GS MAY include a user.exists 430 attribute in a GNAP Interaction Response. The value is true if the 431 GS has a user with one or more of the GC provided identifers, and 432 false if not. 434 * *exists* - a new attribute of the "user" object. If present in a 435 GNAP Grant Request, it MUST be set to true. 437 A GS indicates support for this feature by returning the 438 features.user_exists attribute in the GS Options response set to 439 true. 441 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 443 7. Multiple Interactions 445 There are situations where the GC can not, or prefers not, to ask for 446 all identity claims and/or authorizations it requires. 448 In this example sequence, the GC requests an identity claim to 449 determine who the User is. Once the GC learns who the User is, the 450 GC updates the Grant for additional identity claims which the GS 451 prompts the User for and returns to the GC. Once those additional 452 claims are received, the GC updates the Grant with the remaining 453 identity claims required. 455 +--------+ +-------+ 456 | Client | | GS | 457 | |--(1)--- Create Grant ----------->| | 458 | | multi = true | | 459 | | | | 460 | |<--- Interaction Response ---(2)--| | 461 | | multi = true | | 462 | | | | 463 | |--(3)--- Read Grant ------------->| | +------+ 464 | | | | | User | 465 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 466 | | | | | | 467 | | | |<--(5)-->| | 468 | | | | authN | | 469 | |<--------- Grant Response ---(6)--| | | | 470 | (7) | | | | | 471 | eval |--(8)--- Update Grant ----------->| | | | 472 | | multi = true | |<--(9)-->| | 473 | | | | authZ | | 474 | |<--------- Grant Response --(10)--| | | | 475 | | multi = true | | 476 | (11) | | | | | 477 | eval |--(12)-- Update Grant ----------->| | | | 478 | | multi = false | |<--(13)->| | 479 | | | | authZ | | 480 | | | | | | 481 | |<--- Interaction Transfer --(14)- | - - - | --------| | 482 | | | | | | 483 | |<--------- Grant Response --(15)--| | +------+ 484 | | multi = false | | 485 | | | | 486 +--------+ +-------+ 488 Client = Grant Client 490 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 492 1. *Create Grant* The GC creates a Grant Request (CreateGrant) 493 including an identity claim and interaction.global.multi set to 494 true, and sends it with an HTTP POST to the GS GS URI. 496 2. *Interaction Response* The GS sends an Interaction Response 497 containing the Grant URI and an interaction object, and 498 interaction.global.multi set to true. 500 3. *Read Grant* The GC does an HTTP GET of the Grant URI. 502 4. *Interaction Transfer* The GC transfers User interaction to the 503 GS. 505 5. *User Authentication* The GS authenticates the User. 507 6. *Grant Response* The GS responds with a Grant Response including 508 the identity claim from User authentication and 509 interaction.global.multi set to true. 511 7. *Grant Evaluation* The GC queries its User database and does not 512 find a User record matching the identity claim. 514 8. *Update Grant* The GC creates an Update Grant Request 515 Section 2.2 including the initial identity claims required and 516 interaction.global.multi set to true, and sends it with an HTTP 517 PUT to the Grant URI. 519 9. *User AuthN* The GS interacts with the User to determine which 520 identity claims in the Update Grant Request are to be granted. 522 10. *Grant Response* The GS responds with a Grant Response including 523 the identity claims released by the User and 524 interaction.global.multi set to true. 526 11. *Grant Evaluation* The GC evaluates the identity claims in the 527 Grant Response and determines the remaining User identity claim 528 required. 530 12. *Update Grant* The GC creates an Update Grant Request 531 Section 2.2 including the remaining required identity claims and 532 interaction.global.multi set to false, and sends it with an HTTP 533 PUT to the Grant URI. 535 13. *User AuthZ* The GS interacts with the User to determine which 536 identity claims in the Update Grant Request are to be granted. 538 14. *Interaction Transfer* The GS transfers User interaction to the 539 GC. 541 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 543 15. *Grant Response* The GS responds with a Grant Response including 544 the identity claims released by the User and 545 interaction.global.multi set to false. 547 * *multi* - a new boolean attribute of the GNAP interaction.global 548 object. 550 A GS indicates support for this feature by returning the 551 features.interaction_multi attribute in the GS Options response set 552 to true. 554 8. Error Responses 556 * TBD 558 9. Acknowledgments 560 TBD 562 10. IANA Considerations 564 TBD 566 11. Security Considerations 568 TBD 570 12. Normative References 572 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 573 Requirement Levels", BCP 14, RFC 2119, 574 DOI 10.17487/RFC2119, March 1997, 575 . 577 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 578 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 579 . 581 [GNAP] Hardt, D., "The Grant Negotiation and Authorization 582 Protocol", June 2020, 583 . 585 Appendix A. Document History 587 A.1. draft-hardt-gnap-advanced-00 589 * Initial version 591 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 593 A.2. draft-hardt-gnap-advanced-01 595 * renamed verb to method 597 * renamed Authorization to Access 599 * renamed Client to Grant Client (GC) 601 Appendix B. GS API Table 603 Below is a consolidated table of GS APIs from [GNAP] and this 604 document: 606 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 608 +==============+=============+========+=============================+ 609 | request | http method | uri | response | 610 +==============+=============+========+=============================+ 611 | Create Grant | POST | GS URI | interaction, | 612 | | | | wait, or Grant | 613 +--------------+-------------+--------+-----------------------------+ 614 | List Grants | GET | GS URI | Grant list | 615 +--------------+-------------+--------+-----------------------------+ 616 | Verify Grant | PATCH | Grant | Grant | 617 | | | URI | | 618 +--------------+-------------+--------+-----------------------------+ 619 | Read Grant | GET | Grant | wait, or grant | 620 | | | URI | | 621 +--------------+-------------+--------+-----------------------------+ 622 | Update Grant | PUT | Grant | Interaction, | 623 | | | URI | wait, or Grant | 624 +--------------+-------------+--------+-----------------------------+ 625 | Delete Grant | DELETE | Grant | success | 626 | | | URI | | 627 +--------------+-------------+--------+-----------------------------+ 628 | Read Access | GET | Access | Access | 629 | | | URI | | 630 +--------------+-------------+--------+-----------------------------+ 631 | Update | PUT | Access | Access | 632 | Access | | URI | | 633 +--------------+-------------+--------+-----------------------------+ 634 | Delete | DELETE | Access | success | 635 | Access | | URI | | 636 +--------------+-------------+--------+-----------------------------+ 637 | GS Options | OPTIONS | GS URI | metadata | 638 +--------------+-------------+--------+-----------------------------+ 639 | Grant | OPTIONS | Grant | metadata | 640 | Options | | URI | | 641 +--------------+-------------+--------+-----------------------------+ 642 | Access | OPTIONS | Access | metadata | 643 | Options | | URI | | 644 +--------------+-------------+--------+-----------------------------+ 646 Table 1 648 Author's Address 650 Dick Hardt (editor) 651 SignIn.Org 652 United States 654 Email: dick.hardt@gmail.com