idnits 2.17.1 draft-hardt-gnap-advanced-00.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 36 instances of too long lines in the document, the longest one being 1 character in excess of 72. == 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 (7 June 2020) is 1417 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 276, but not defined ** Downref: Normative reference to an Informational RFC: RFC 4949 -- Possible downref: Non-RFC (?) normative reference: ref. 'GNAP' Summary: 2 errors (**), 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 7 June 2020 5 Expires: 9 December 2020 7 The Grant Negotiation and Authorization Protocol - Advanced Features 8 draft-hardt-gnap-advanced-00 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 9 December 2020. 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 49 2.1. List Grants . . . . . . . . . . . . . . . . . . . . . . . 4 50 2.2. Update Grant . . . . . . . . . . . . . . . . . . . . . . 4 51 2.3. Delete Grant . . . . . . . . . . . . . . . . . . . . . . 5 52 2.4. Grant Options . . . . . . . . . . . . . . . . . . . . . . 5 53 3. Authorization Management APIs . . . . . . . . . . . . . . . . 5 54 3.1. Update Authorization . . . . . . . . . . . . . . . . . . 6 55 3.2. Delete Authorization . . . . . . . . . . . . . . . . . . 6 56 3.3. Authorization Options . . . . . . . . . . . . . . . . . . 6 57 4. Reciprocal Grant . . . . . . . . . . . . . . . . . . . . . . 7 58 5. GS Initiated Grant . . . . . . . . . . . . . . . . . . . . . 8 59 6. User Exists . . . . . . . . . . . . . . . . . . . . . . . . . 9 60 7. Multiple Interactions . . . . . . . . . . . . . . . . . . . . 10 61 8. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 12 62 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 63 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 64 11. Security Considerations . . . . . . . . . . . . . . . . . . . 12 65 12. Normative References . . . . . . . . . . . . . . . . . . . . 12 66 Appendix A. Document History . . . . . . . . . . . . . . . . . . 12 67 A.1. draft-hardt-gnap-advanced-00 . . . . . . . . . . . . . . 12 68 Appendix B. GS API Table . . . . . . . . . . . . . . . . . . . . 12 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 71 1. Introduction 73 This document includes additional features for the Grant Negotiation 74 and Authorization Protocol (GNAP) [GNAP], and presumes familiarity 75 and knowledge of GNAP. 77 *Terminology* 79 This document uses the following terms defined in [GNAP]: 81 * authN 83 * authZ 85 * Authorization 87 * Authorization URI (AZ URI) 89 * Claim 91 * Client 93 * Registered Client 95 * Grant 96 * Grant Server (GS) 98 * Grant URI 100 * Grant Request 102 * Grant Response 104 * GS URI 106 * Interaction 108 * NumericDate 110 * Resource Owner (RO) 112 * Resource Server (RS) 114 * User 116 *Notational Conventions* 118 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 119 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 120 specification are to be interpreted as described in [RFC2119]. 122 Certain security-related terms are to be understood in the sense 123 defined in [RFC4949]. These terms include, but are not limited to, 124 "attack", "authentication", "authorization", "certificate", 125 "confidentiality", "credential", "encryption", "identity", "sign", 126 "signature", "trust", "validate", and "verify". 128 Unless otherwise noted, all the protocol parameter names and values 129 are case sensitive. 131 Some protocol parameters are parts of a JSON document, and are 132 referred to in JavaScript notation. For example, foo.bar refers to 133 the "bar" boolean attribute in the "foo" object in the following 134 example JSON document: 136 { 137 "foo" : { 138 "bar": true 139 } 140 } 142 2. Grant Management APIs 144 In addition to creating and reading a Grant as specified in GNAP The 145 Client MAY list, update, delete, and discover a Grant. 147 2.1. List Grants 149 The Client MAY list the Grants provided to the Client by doing an a 150 GET on the GS URI. The GS MUST respond with a list of Grant URIs [ 151 format TBD] or one of the following errors: 153 * TBD 155 from Error Responses Section 8. 157 2.2. Update Grant 159 The Client updates a Grant by doing an HTTP PUT of a JSON document to 160 the corresponding Grant URI. 162 The JSON document MUST include the following from the [GNAP] Grant 163 Request JSON: 165 * iat 167 * uri set to the Grant URI 169 and MAY include the following from the [GNAP] Grant Request JSON: 171 * user 173 * interaction 175 * authorization or authorizations 177 * claims 179 The GS MUST respond with one of the standard GNAP responses (Grant 180 Response, Interaction Response, Wait Response) or one of the 181 following errors: 183 * TBD 185 from Error Responses Section 8. 187 Following is a non-normative example where the Client wants to update 188 the Grant Request with additional claims: 190 { 191 "iat" : 15790460234, 192 "uri" : "https://as.example/endpoint/grant/example3", 193 "claims": { 194 "oidc": { 195 "userinfo" : { 196 "email" : { "essential" : true }, 197 "name" : { "essential" : true }, 198 "picture" : null 199 } 200 } 201 } 202 } 204 2.3. Delete Grant 206 The Client deletes a Grant by doing an HTTP DELETE of the 207 corresponding Grant URI. 209 The GS MUST respond with OK 200, or one of the following errors: 211 * TBD 213 from Error Responses Section 8. 215 2.4. Grant Options 217 The Client can get the supported operations for a Grant by doing an 218 HTTP OPTIONS of the corresponding Grant URI. 220 The GS MUST respond with the supported methods 222 [Format TBD] 224 or one of the following errors: 226 * TBD 228 from Error Responses Section 8. 230 3. Authorization Management APIs 232 In addition to reading an Authorization as specified in [GNAP], The 233 Client MAY update, delete, and discover an Authorization. 235 3.1. Update Authorization 237 The Client updates an Authorization by doing an HTTP PUT to the 238 corresponding AZ URI of the following JSON. All of the following 239 MUST be included. 241 * *iat* - the time of the request as a NumericDate. 243 * *uri* - the AZ URI. 245 * *authorization* - the new authorization requested per the [GNAP] 246 Grant Request JSON "authorization" object. 248 The GS MUST respond with a GNAP Authorization JSON document, or one 249 of the following errors: 251 * TBD 253 from Error Responses Section 8. 255 3.2. Delete Authorization 257 The Client deletes an Authorization by doing an HTTP DELETE to the 258 corresponding AZ URI. 260 The GS MUST respond with OK 200, or one of the following errors: 262 * TBD 264 from Error Responses Section 8. 266 A GS MAY indicate support for this feature by including the "DELETE" 267 method in the AZ URI OPTIONS response. 269 3.3. Authorization Options 271 The Client can get the supported operations for an Authorization by 272 doing an HTTP OPTIONS of the corresponding AZ URI. 274 The GS MUST respond with the supported methods 276 [Format TBD] 278 or one of the following errors: 280 * TBD 282 from Error Responses Section 8. 284 4. Reciprocal Grant 286 Party A and Party B both want to obtain a Grant from the other party. 287 Each party will be both Client and GS. This would require two 288 complete GNAP flows with an awkward redirect between them, and the 289 User may have to authenticate multiple times as context is lost. 290 Reciprocal Grant simplifies the User experience. 292 In the following sequence, steps 1 - 7 & 9 are a standard GNAP 293 sequence. 295 Party A Party B 296 +--------+ +--------+ 297 | | | | 298 | Client |--(1)-- Create Grant A ->| GS | 299 | | | | 300 | Client |<--- Interaction ---(2)--| GS | 301 | | Response | | 302 | | | | 303 | Client |--(3)--- Read Grant A -->| GS | +---+ 304 | | | | | U | 305 | Client |--(4)--- Interaction --- | - - - | ----->| s | 306 | | Transfer | | | e | 307 | | | GS |<-(5)->| r | 308 | | | | authN | | 309 | | | GS |<-(6)->| | 310 | | | | authZ | | 311 | Client |<------- Grant A ---(7)--| GS | +---+ 312 | | Response | | 313 | | | | 314 | GS |<- Create Grant B --(8)--| Client | 315 +---+ | | user.reciprocal | | 316 | U | | | | | 317 | s |<------ | - - - | --- Interaction --(9)---| GS | 318 | e | | | Transfer | | 319 | r |<-(10)->| GS | | | 320 | | AuthZ | | | | 321 +---+ | GS |--(11)-- Grant B ------->| Client | 322 | | Response | | 323 +--------+ +--------+ 325 1. *Create Grant A* Party A makes a Create Grant request to the 326 Party B GS URI. 328 2. *Interaction Response* Party B returns an interaction response 329 containing the Grant A URI. 331 3. *Read Grant A* Party A does an HTTP GET of the Grant A URI. 333 4. *Interaction Transfer* Party A transfers User interaction to the 334 Party B. 336 5. *User Authentication* Party B authenticates the User. 338 6. *User Authorization* If required, Party B interacts with the 339 User to determine which identity claims and/or authorizations in 340 the Grant A Request are to be granted. 342 7. *Create GrantB* Party B creates its Grant B Request with 343 user.reciprocal set to the Grant A URI that will be in the step 344 (2) Grant A Response, and sends it with an HTTP POST to the 345 Party A GS URI. This enables Party A to correlate the Grant B 346 Request and its Grant and the User. 348 8. *Grant S Response* Party B responds to Party A's Create Grant A 349 Request with a Grant A Response. 351 9. *Interaction Transfer* Party B redirects the User to the 352 Completion URI at Party A. 354 10. *User Authorization* If required, Party A interacts with the 355 User to determine which identity claims and/or authorizations in 356 Party B's Grant B Request are to be granted. 358 11. *Grant B Response* Party A responds with the Grant B Response. 360 * *reciprocal* - a new attribute of the [GNAP] Request JSON user 361 object. MUST be set to a Grant URI. 363 5. GS Initiated Grant 365 The User is at the GS, and wants to interact with a Registered 366 Client. The Client has previously configured an initiation_uri at 367 the GS, and the Grant it requires. 369 In this sequence, the GS creates a Grant and redirects the User to 370 the Client's initiation_uri passing a Grant URI: 372 +--------+ +-------+ +------+ 373 | Client | | GS | | User | 374 | | | |<--(1)-->| | 375 | | | | | | 376 | |<----- GS Initiation Redirect --- | - - - | --(2)---| | 377 | (3) | | | | | 378 | verify |--(4)--- Read Grant ------------->| | +------+ 379 | | | | 380 | |<--------- Grant Response --(5)---| | 381 | | | | 382 +--------+ +-------+ 384 1. *User Interaction* The GS interacts with the User to determine 385 the Client and what identity claims and / or authorizations to 386 provide. The GS creates a Grant and corresponding Grant URI. 388 2. *GS Initiated Redirect* The GS redirects the User to the Client's 389 initiation_uri, adding a query parameter with the name 390 "grant_uri" and the value being the URL encoded Grant URI. 392 3. *Client Verification* The Client verifies the Grant URI starts 393 with a GS URI from a GS the Client trusts. 395 4. *Read Grant* The Client does an HTTP GET of the Grant URI. 397 5. *Grant Response* The GS responds with a Grant Response. 399 * *initiation_uri* - a URI at the Client that contains no query or 400 fragment. How the GS learns the Client initiation_uri and require 401 Grant is out of scope of this document. 403 6. User Exists 405 The Client may want to provide a different experience to the User 406 depending on if a User already exists at the GS. By including one or 407 more identifiers in the Grant Request user.identifiers object, and 408 setting user.exists to true, the GS MAY include a user.exists 409 attribute in a GNAP Interaction Response. The value is true if the 410 GS has a user with one or more of the Client provided identifers, and 411 false if not. 413 * *exists* - a new attribute of the "user" object. If present in a 414 GNAP Grant Request, it MUST be set to true. 416 A GS indicates support for this feature by returning the 417 features.user_exists attribute in the GS Options response set to 418 true. 420 7. Multiple Interactions 422 There are situations where the Client can not, or prefers not, to ask 423 for all identity claims and/or authorizations it requires. 425 In this example sequence, the Client requests an identity claim to 426 determine who the User is. Once the Client learns who the User is, 427 the Client updates the Grant for additional identity claims which the 428 GS prompts the User for and returns to the Client. Once those 429 additional claims are received, the Client updates the Grant with the 430 remaining identity claims required. 432 +--------+ +-------+ 433 | Client | | GS | 434 | |--(1)--- Create Grant ----------->| | 435 | | multi = true | | 436 | | | | 437 | |<--- Interaction Response ---(2)--| | 438 | | multi = true | | 439 | | | | 440 | |--(3)--- Read Grant ------------->| | +------+ 441 | | | | | User | 442 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 443 | | | | | | 444 | | | |<--(5)-->| | 445 | | | | authN | | 446 | |<--------- Grant Response ---(6)--| | | | 447 | (7) | | | | | 448 | eval |--(8)--- Update Grant ----------->| | | | 449 | | multi = true | |<--(9)-->| | 450 | | | | authZ | | 451 | |<--------- Grant Response --(10)--| | | | 452 | | multi = true | | 453 | (11) | | | | | 454 | eval |--(12)-- Update Grant ----------->| | | | 455 | | multi = false | |<--(13)->| | 456 | | | | authZ | | 457 | | | | | | 458 | |<--- Interaction Transfer --(14)- | - - - | --------| | 459 | | | | | | 460 | |<--------- Grant Response --(15)--| | +------+ 461 | | multi = false | | 462 | | | | 463 +--------+ +-------+ 465 1. *Create Grant* The Client creates a Grant Request (CreateGrant) 466 including an identity claim and interaction.global.multi set to 467 true, and sends it with an HTTP POST to the GS GS URI. 469 2. *Interaction Response* The GS sends an Interaction Response 470 containing the Grant URI and an interaction object, and 471 interaction.global.multi set to true. 473 3. *Read Grant* The Client does an HTTP GET of the Grant URI. 475 4. *Interaction Transfer* The Client transfers User interaction to 476 the GS. 478 5. *User Authentication* The GS authenticates the User. 480 6. *Grant Response* The GS responds with a Grant Response including 481 the identity claim from User authentication and 482 interaction.global.multi set to true. 484 7. *Grant Evaluation* The Client queries its User database and does 485 not find a User record matching the identity claim. 487 8. *Update Grant* The Client creates an Update Grant Request 488 Section 2.2 including the initial identity claims required and 489 interaction.global.multi set to true, and sends it with an HTTP 490 PUT to the Grant URI. 492 9. *User AuthN* The GS interacts with the User to determine which 493 identity claims in the Update Grant Request are to be granted. 495 10. *Grant Response* The GS responds with a Grant Response including 496 the identity claims released by the User and 497 interaction.global.multi set to true. 499 11. *Grant Evaluation* The Client evaluates the identity claims in 500 the Grant Response and determines the remaining User identity 501 claim required. 503 12. *Update Grant* The Client creates an Update Grant Request 504 Section 2.2 including the remaining required identity claims and 505 interaction.global.multi set to false, and sends it with an HTTP 506 PUT to the Grant URI. 508 13. *User AuthZ* The GS interacts with the User to determine which 509 identity claims in the Update Grant Request are to be granted. 511 14. *Interaction Transfer* The GS transfers User interaction to the 512 Client. 514 15. *Grant Response* The GS responds with a Grant Response including 515 the identity claims released by the User and 516 interaction.global.multi set to false. 518 * *multi* - a new boolean attribute of the GNAP interaction.global 519 object. 521 A GS indicates support for this feature by returning the 522 features.interaction_multi attribute in the GS Options response set 523 to true. 525 8. Error Responses 527 * TBD 529 9. Acknowledgments 531 TBD 533 10. IANA Considerations 535 TBD 537 11. Security Considerations 539 TBD 541 12. Normative References 543 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 544 Requirement Levels", BCP 14, RFC 2119, 545 DOI 10.17487/RFC2119, March 1997, 546 . 548 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 549 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 550 . 552 [GNAP] Hardt, D., "The Grant Negotiation and Authorization 553 Protocol", June 2020, 554 . 556 Appendix A. Document History 558 A.1. draft-hardt-gnap-advanced-00 560 * Initial version 562 Appendix B. GS API Table 564 Below is a consolidated table of GS APIs from [GNAP] and this 565 document: 567 +--------------+-----------+--------+-----------------------------+ 568 | request | http verb | uri | response | 569 +==============+===========+========+=============================+ 570 | Create Grant | POST | GS URI | interaction, wait, or grant | 571 +--------------+-----------+--------+-----------------------------+ 572 | List Grants | GET | GS URI | grant list | 573 +--------------+-----------+--------+-----------------------------+ 574 | Verify Grant | PATCH | Grant | grant | 575 | | | URI | | 576 +--------------+-----------+--------+-----------------------------+ 577 | Read Grant | GET | Grant | wait, or grant | 578 | | | URI | | 579 +--------------+-----------+--------+-----------------------------+ 580 | Update Grant | PUT | Grant | interaction, wait, or grant | 581 | | | URI | | 582 +--------------+-----------+--------+-----------------------------+ 583 | Delete Grant | DELETE | Grant | success | 584 | | | URI | | 585 +--------------+-----------+--------+-----------------------------+ 586 | Read AuthZ | GET | AZ URI | authorization | 587 +--------------+-----------+--------+-----------------------------+ 588 | Update AuthZ | PUT | AZ URI | authorization | 589 +--------------+-----------+--------+-----------------------------+ 590 | Delete AuthZ | DELETE | AZ URI | success | 591 +--------------+-----------+--------+-----------------------------+ 592 | GS Options | OPTIONS | GS URI | metadata | 593 +--------------+-----------+--------+-----------------------------+ 594 | Grant | OPTIONS | Grant | metadata | 595 | Options | | URI | | 596 +--------------+-----------+--------+-----------------------------+ 597 | AuthZ | OPTIONS | AZ URI | metadata | 598 | Options | | | | 599 +--------------+-----------+--------+-----------------------------+ 601 Table 1 603 Author's Address 605 Dick Hardt (editor) 606 SignIn.Org 607 United States 609 Email: dick.hardt@gmail.com