idnits 2.17.1 draft-ietf-gnap-resource-servers-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (28 April 2021) is 1066 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'BCP195' == Outdated reference: A later version (-20) exists of draft-ietf-gnap-core-protocol-04 ** Downref: Normative reference to an Informational RFC: RFC 8792 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 GNAP J. Richer, Ed. 3 Internet-Draft Bespoke Engineering 4 Intended status: Standards Track A. Parecki 5 Expires: 30 October 2021 Okta 6 F. Imbault 7 acert.io 8 28 April 2021 10 Grant Negotiation and Authorization Protocol Resource Server Connections 11 draft-ietf-gnap-resource-servers-00 13 Abstract 15 GNAP defines a mechanism for delegating authorization to a piece of 16 software, and conveying that delegation to the software. This 17 extension defines methods for resource servers (RS) to communicate 18 with authorization servers (AS) in an interoperable fashion. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on 30 October 2021. 37 Copyright Notice 39 Copyright (c) 2021 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 44 license-info) in effect on the date of publication of this document. 45 Please review these documents carefully, as they describe your rights 46 and restrictions with respect to this document. Code Components 47 extracted from this document must include Simplified BSD License text 48 as described in Section 4.e of the Trust Legal Provisions and are 49 provided without warranty as described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Access Token Formats . . . . . . . . . . . . . . . . . . . . 3 56 3. Resource-Server-Facing API . . . . . . . . . . . . . . . . . 4 57 3.1. RS-facing AS Discovery . . . . . . . . . . . . . . . . . 4 58 3.2. Protecting RS requests to the AS . . . . . . . . . . . . 4 59 3.3. Token Introspection . . . . . . . . . . . . . . . . . . . 5 60 3.4. Registering a Resource Handle . . . . . . . . . . . . . . 6 61 4. Deriving a downstream token . . . . . . . . . . . . . . . . . 8 62 5. Requesting Resources With Insufficient Access . . . . . . . . 10 63 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 64 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 65 8. Security Considerations . . . . . . . . . . . . . . . . . . . 11 66 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 11 67 10. Normative References . . . . . . . . . . . . . . . . . . . . 11 68 Appendix A. Document History . . . . . . . . . . . . . . . . . . 12 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 71 1. Introduction 73 The core GNAP protocol does not define any one specific mechanism for 74 the resource server (RS) to communicate with the authorization server 75 (AS), allowing the connection between these components to be solved 76 orthogonally to the core protocol's concerns. For example, the RS 77 and AS roles could be fulfilled by the same piece of software with 78 common storage, obviating the need for any connecting protocol. 79 However, it is often desirable to have the RS and AS communicate at 80 runtime for a variety of purposes, including allowing the RS to 81 validate and understand the rights and privileges associated with a 82 grant of access represented by an access token issued by (AS), or 83 negotiating the capabilities of either party. These types of 84 connections are particularly useful for connecting an AS and RS from 85 different vendors, allowing interoperable distributed deployments of 86 GNAP-protected systems. 88 This specification defines several means for a RS and AS to 89 communicate these aspects with each other, including structured 90 access tokens and RS-facing APIs. This specification also discusses 91 methods for an RS to derive a downstream token for calling another 92 chained RS as well as a client-facing discovery mechanism that can be 93 used to bootstrap the GNAP process when the client instance does not 94 know which AS protects a given RS. 96 The means of the authorization server issuing the access token to the 97 client instance and the means of the client instance presenting the 98 access token to the resource server are the subject of the GNAP core 99 protocol specification [I-D.ietf-gnap-core-protocol]. 101 1.1. Terminology 103 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 104 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 105 "OPTIONAL" in this document are to be interpreted as described in 106 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 107 capitals, as shown here. 109 This document contains non-normative examples of partial and complete 110 HTTP messages, JSON structures, URLs, query components, keys, and 111 other elements. Some examples use a single trailing backslash '' to 112 indicate line wrapping for long values, as per [RFC8792]. The "\" 113 character and leading spaces on wrapped lines are not part of the 114 value. 116 2. Access Token Formats 118 When the AS issues an access token for use at an RS, the RS needs to 119 have some means of understanding what the access token is for in 120 order to determine how to respond to the request. The core GNAP 121 protocol makes no assumptions or demands on the format or contents of 122 the access token, but such token formats can be the topic of 123 agreements between the AS and RS. 125 Self-contained structured token formats allow for the conveyance of 126 information between the AS and RS without requiring the RS to call 127 the AS at runtime as described in Section 3.3. 129 Some token formats, such as Macaroons and Biscuits, allow for the RS 130 to derive sub-tokens without having to call the AS as described in 131 Section 4. 133 3. Resource-Server-Facing API 135 To facilitate runtime and dynamic connections, the AS can offer an 136 RS-Facing API consisting of one or more of the following optional 137 pieces. 139 * Discovery 141 * Introspection 143 * Token chaining 145 * Resource reference registration 147 3.1. RS-facing AS Discovery 149 A GNAP AS offering RS-facing services can publish its features on a 150 well-known discovery document using the URL ".well-known/gnap-as-rs". 152 This endpoint contains a JSON document [RFC8259] consisting of a 153 single JSON object with any combination of the following optional 154 fields: 156 introspection_endpoint: The URL of the endpoint offering 157 introspection. Section 3.3 159 token_formats_supported: A list of token formats supported by this 160 AS. 162 resource_registration_endpoint: The URL of the endpoint offering 163 resource registration. Section 3.4 165 grant_endpoint: The grant endpoint of the GNAP AS. 167 3.2. Protecting RS requests to the AS 169 Unless otherwise specified, the RS protects its calls to the AS using 170 any of the signature methods defined by GNAP. This signing method 171 MUST cover all of the appropriate portions of the HTTP request 172 message, including any body elements, tokens, or headers required for 173 functionality. 175 The AS MAY require an RS to pre-register its keys or could 176 alternatively allow calls from arbitrary keys, in a trust-on-first- 177 use model. The RS MAY present its keys by reference or by value in 178 the same fashion as a client instance calling the AS in the core 179 protocol of GNAP [I-D.ietf-gnap-core-protocol]. 181 3.3. Token Introspection 183 The AS issues access tokens representing a set of delegated access 184 rights to be used at one or more RSs. The AS can offer an 185 introspection service to allow an RS to validate that a given access 186 token: 188 * has been issued by the AS 190 * has not expired 192 * has not been revoked 194 * is appropriate for the RS identified in the call 196 When the RS receives an access token, it can call the introspection 197 endpoint at the AS to get token information. [[ See issue #115 198 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/115) ]] 200 +--------+ +------+ +------+ 201 | Client |--(1)->| RS | | AS | 202 |Instance| | |--(2)->| | 203 | | | | | | 204 | | | |<-(3)--| | 205 | | | | +------+ 206 | |<-(4)--| | 207 +--------+ +------+ 209 1. The client instance calls the RS with its access token. 211 2. The RS introspects the access token value at the AS. The RS 212 signs the request with its own key (not the client instance's key 213 or the token's key). 215 3. The AS validates the access token value and the client instance's 216 request and returns the introspection response for the token. 218 4. The RS fulfills the request from the client instance. 220 The RS signs the request with its own key and sends the access token 221 as the body of the request. 223 POST /introspect HTTP/1.1 224 Host: server.example.com 225 Content-Type: application/json 226 Detached-JWS: ejy0... 228 { 229 "access_token": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 230 "proof": "httpsig", 231 "resource_server": "7C7C4AZ9KHRS6X63AJAO" 232 } 234 The AS responds with a data structure describing the token's current 235 state and any information the RS would need to validate the token's 236 presentation, such as its intended proofing mechanism and key 237 material. The response MAY include any fields defined in an access 238 token response. 240 HTTP/1.1 200 OK 241 Content-Type: application/json 242 Cache-Control: no-store 244 { 245 "active": true, 246 "access": [ 247 "dolphin-metadata", "some other thing" 248 ], 249 "key": { 250 "proof": "httpsig", 251 "jwk": { 252 "kty": "RSA", 253 "e": "AQAB", 254 "kid": "xyz-1", 255 "alg": "RS256", 256 "n": "kOB5rR4Jv0GMeL...." 257 } 258 } 259 } 261 3.4. Registering a Resource Handle 263 If the RS needs to, it can post a set of resources as described in 264 the Resource Access Rights section of [I-D.ietf-gnap-core-protocol] 265 to the AS's resource registration endpoint. 267 The RS MUST identify itself with its own key and sign the request. 269 POST /resource HTTP/1.1 270 Host: server.example.com 271 Content-Type: application/json 272 Detached-JWS: ejy0... 274 { 275 "access": [ 276 { 277 "actions": [ 278 "read", 279 "write", 280 "dolphin" 281 ], 282 "locations": [ 283 "https://server.example.net/", 284 "https://resource.local/other" 285 ], 286 "datatypes": [ 287 "metadata", 288 "images" 289 ] 290 }, 291 "dolphin-metadata" 292 ], 293 "resource_server": "7C7C4AZ9KHRS6X63AJAO" 295 } 297 The AS responds with a handle appropriate to represent the resources 298 list that the RS presented. 300 HTTP/1.1 200 OK 301 Content-Type: application/json 302 Cache-Control: no-store 304 { 305 "resource_handle": "FWWIKYBQ6U56NL1" 306 } 308 The RS MAY make this handle available as part of a response 309 (Section 5) or as documentation to developers. 311 [[ See issue #117 (https://github.com/ietf-wg-gnap/gnap-core- 312 protocol/issues/117) ]] 314 4. Deriving a downstream token 316 Some architectures require an RS to act as a client instance and use 317 a derived access token for a secondary RS. Since the RS is not the 318 same entity that made the initial grant request, the RS is not 319 capable of referencing or modifying the existing grant. As such, the 320 RS needs to request or generate a new token access token for its use 321 at the secondary RS. This internal secondary token is issued in the 322 context of the incoming access token. 324 While it is possible to use a [token format]{#structure} that allows 325 for the RS to generate its own secondary token, the AS can allow the 326 RS to request this secondary access token using the same process used 327 by the original client instance to request the primary access token. 328 Since the RS is acting as its own client instance from the 329 perspective of GNAP, this process uses the same grant endpoint, 330 request structure, and response structure as a client instance's 331 request. 333 +--------+ +-------+ +------+ +-------+ 334 | Client |--(1)->| RS1 | | AS | | RS2 | 335 |Instance| | |--(2)->| | | | 336 | | | |<-(3)--| | | | 337 | | | | +------+ | | 338 | | | | | | 339 | | | |-----------(4)------->| | 340 | | | |<----------(5)--------| | 341 | |<-(6)--| | | | 342 +--------+ +-------+ +-------+ 344 1. The client instance calls RS1 with an access token. 346 2. RS1 presents that token to the AS to get a derived token for use 347 at RS2. RS1 indicates that it has no ability to interact with 348 the RO. Note that RS1 signs its request with its own key, not 349 the token's key or the client instance's key. 351 3. The AS returns a derived token to RS1 for use at RS2. 353 4. RS1 calls RS2 with the token from (3). 355 5. RS2 fulfills the call from RS1. 357 6. RS1 fulfills the call from the original client instance. 359 If the RS needs to derive a token from one presented to it, it can 360 request one from the AS by making a token request as described in 361 [I-D.ietf-gnap-core-protocol] and presenting the existing access 362 token's value in the "existing_access_token" field. 364 Since the RS is acting as a client instance, the RS MUST identify 365 itself with its own key in the "client" field and sign the request 366 just as any client instance would. 368 [[ See issue #116 (https://github.com/ietf-wg-gnap/gnap-core- 369 protocol/issues/116) ]] 371 POST /tx HTTP/1.1 372 Host: server.example.com 373 Content-Type: application/json 374 Detached-JWS: ejy0... 376 { 377 "access_token": { 378 "access": [ 379 { 380 "actions": [ 381 "read", 382 "write", 383 "dolphin" 384 ], 385 "locations": [ 386 "https://server.example.net/", 387 "https://resource.local/other" 388 ], 389 "datatypes": [ 390 "metadata", 391 "images" 392 ] 393 }, 394 "dolphin-metadata" 395 ] 396 }, 397 "client": "7C7C4AZ9KHRS6X63AJAO", 398 "existing_access_token": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0" 399 } 401 The AS responds with a token for the downstream RS2 as described in 402 [I-D.ietf-gnap-core-protocol]. The downstream RS2 could repeat this 403 process as necessary for calling further RS's. 405 5. Requesting Resources With Insufficient Access 407 If the client instance calls an RS without an access token, or with 408 an invalid access token, the RS MAY respond to the client instance 409 with an authentication header indicating that GNAP needs to be used 410 to access the resource. The address of the GNAP endpoint MUST be 411 sent in the "as_uri" parameter. The RS MAY additionally return a 412 resource reference that the client instance MAY use in its access 413 token request. This resource reference handle SHOULD be sufficient 414 for at least the action the client instance was attempting to take at 415 the RS. The RS MAY use the dynamic resource handle request 416 (Section 3.4) to register a new resource handle, or use a handle that 417 has been pre-configured to represent what the RS is protecting. The 418 content of this handle is opaque to the RS and the client instance in 419 both cases. 421 WWW-Authenticate: \ 422 GNAP as_uri=https://server.example/tx,access=FWWIKYBQ6U56NL1 424 The client instance then makes a call to the "as_uri" as described in 425 [I-D.ietf-gnap-core-protocol], with the value of "access" as one of 426 the members of the "access" array in the "access_token" portion of 427 the request. The client instance MAY request additional resources 428 and other information, and MAY request multiple access tokens. 430 POST /tx HTTP/1.1 431 Host: server.example.com 432 Content-Type: application/json 433 Detached-JWS: ejy0... 435 { 436 "access_token": { 437 "access": [ 438 "FWWIKYBQ6U56NL1", 439 "dolphin-metadata" 440 ] 441 }, 442 "client": "KHRS6X63AJ7C7C4AZ9AO" 443 } 445 [[ See issue #118 (https://github.com/ietf-wg-gnap/gnap-core- 446 protocol/issues/118) ]] 448 6. Acknowledgements 450 (TODO: the ACK section should probably be split between the 451 documents) 453 7. IANA Considerations 455 [[ TBD: There are a lot of items in the document that are expandable 456 through the use of value registries. ]] 458 8. Security Considerations 460 [[ TBD: There are a lot of security considerations to add. ]] 462 All requests have to be over TLS or equivalent as per [BCP195]. Many 463 handles act as shared secrets, though they can be combined with a 464 requirement to provide proof of a key as well. 466 9. Privacy Considerations 468 [[ TBD: There are a lot of privacy considerations to add. ]] 470 When introspection is used, the AS is made aware of a particular 471 token being used at a particular AS, and the AS would not otherwise 472 have insight into this. 474 When the client instance receives information about the protecting AS 475 from an RS, this can be used to derive information about the 476 resources being protected without releasing the resources themselves. 478 10. Normative References 480 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 481 "Recommendations for Secure Use of Transport Layer 482 Security (TLS) and Datagram Transport Layer Security 483 (DTLS)", May 2015, 484 . 486 [I-D.ietf-gnap-core-protocol] 487 Richer, J., Parecki, A., and F. Imbault, "Grant 488 Negotiation and Authorization Protocol", Work in Progress, 489 Internet-Draft, draft-ietf-gnap-core-protocol-04, 22 490 February 2021, . 493 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 494 Requirement Levels", BCP 14, RFC 2119, 495 DOI 10.17487/RFC2119, March 1997, 496 . 498 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 499 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 500 May 2017, . 502 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 503 Interchange Format", STD 90, RFC 8259, 504 DOI 10.17487/RFC8259, December 2017, 505 . 507 [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, 508 "Handling Long Lines in Content of Internet-Drafts and 509 RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, 510 . 512 Appendix A. Document History 514 * -00 516 - Extracted resource server section. 518 Authors' Addresses 520 Justin Richer (editor) 521 Bespoke Engineering 523 Email: ietf@justin.richer.org 524 URI: https://bspk.io/ 526 Aaron Parecki 527 Okta 529 Email: aaron@parecki.com 530 URI: https://aaronparecki.com 532 Fabien Imbault 533 acert.io 535 Email: fabien.imbault@acert.io 536 URI: https://acert.io/