idnits 2.17.1 draft-hunt-scim-search-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 (May 28, 2015) is 3255 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) == Outdated reference: A later version (-22) exists of draft-ietf-scim-core-schema-20 == Outdated reference: A later version (-02) exists of draft-snell-search-method-00 -- Possible downref: Normative reference to a draft: ref. 'I-D.snell-search-method' ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Hunt, Ed. 3 Internet-Draft Oracle 4 Intended status: Standards Track May 28, 2015 5 Expires: November 29, 2015 7 SCIM HTTP SEARCH Method Extension 8 draft-hunt-scim-search-00 10 Abstract 12 The System for Cross-Domain Identity Management (SCIM) specification 13 is an HTTP based protocol that makes managing identities in multi- 14 domain scenarios easier to support through a standardized service. 15 Examples include but are not limited to enterprise to cloud service 16 providers, and inter-cloud based scenarios. This specification 17 extends the SCIM Protocol to include support for HTTP SEARCH. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on November 29, 2015. 36 Copyright Notice 38 Copyright (c) 2015 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 2 54 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3 55 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3 56 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 57 2. Discovery of Search Support . . . . . . . . . . . . . . . . . 4 58 2.1. Advertising Support in OPTIONS . . . . . . . . . . . . . 4 59 2.2. The Accept-Search Header . . . . . . . . . . . . . . . . 4 60 2.3. Service Provider Configuration . . . . . . . . . . . . . 4 61 3. SEARCH Method . . . . . . . . . . . . . . . . . . . . . . . . 4 62 4. Stored Search Queries . . . . . . . . . . . . . . . . . . . . 8 63 4.1. Storing A Search . . . . . . . . . . . . . . . . . . . . 8 64 4.2. Retrieving A Stored Search . . . . . . . . . . . . . . . 9 65 4.3. Executing A Stored Search . . . . . . . . . . . . . . . . 10 66 4.4. SCIM Schema Extension . . . . . . . . . . . . . . . . . . 11 67 4.4.1. Search Schema . . . . . . . . . . . . . . . . . . . . 11 68 4.4.2. Search Resource Type . . . . . . . . . . . . . . . . 11 69 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 70 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 12 71 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 72 8. Normative References . . . . . . . . . . . . . . . . . . . . 13 73 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 13 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 76 1. Introduction and Overview 78 The SCIM Protocol is an application-level HTTP protocol for 79 provisioning and managing identity data on the web and in cross- 80 domain environments such as enterprise to cloud, or inter-cloud 81 scenarios. The protocol supports creation, modification, retrieval, 82 and discovery of core identity resources such as Users and Groups, as 83 well as custom resources and resource extensions. The definition of 84 resources, attributes, and overall schema are defined in the SCIM 85 Core Schema document (see [I-D.ietf-scim-core-schema]). The SCIM 86 Protocol defines methods for creation, modification, deletion, and 87 searching of SCIM resources (see [I-D.ietf-scim-api]). 89 In SCIM Protocol, searching is currently supported using HTTP GET and 90 HTTP POST (see section 3.4.2 and 3.4.3 [I-D.ietf-scim-api]). While a 91 common practice, the HTTP GET method of searching causes problems 92 with the disclosure of sensitive information through URL leakage (see 93 Section 7.5 [I-D.ietf-scim-api]). In contrast, using HTTP POST has 94 the disadvantage of overloading POST to perform another function 95 other than creating new SCIM resources. Further, HTTP POST requires 96 the client to add special URI path encodings so that a SCIM service 97 provider can determine the clients intent to create a resource vs. 98 seaching for resources. 100 This draft proposes to use the HTTP SEARCH method defined in 101 [I-D.snell-search-method] as an improved approach that reduces 102 complexity for SCIM clients in the future. [[Note: the author 103 acknowledges that adding a 3rd method does not reduce complexity. 104 However one has to acknowledge water under the bridge and the costs 105 of transition. The intent here is to show how SCIM would have been 106 simpler had SEARCH been available.]] 108 One of the advantages of using HTTP SEARCH is that security control 109 layers and gateways can easily differentiate from a general resource 110 retrieval (e.g., via HTTP GET), or resource creation (e.g., via HTTP 111 POST). The security system is not required to parse the content of 112 the URI or of the body to understand that the request is a search 113 operation. 115 1.1. Intended Audience 117 This document is intended as a guide to SCIM protocol usage for both 118 SCIM HTTP service providers and HTTP clients who may provision 119 information to service providers or retrieve information from them. 121 1.2. Notational Conventions 123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 125 document are to be interpreted as described in [RFC2119]. These 126 keywords are capitalized when used to unambiguously specify 127 requirements of the protocol or application features and behavior 128 that affect the interoperability and security of implementations. 129 When these words are not capitalized, they are meant in their 130 natural-language sense. 132 For purposes of readability examples are not URL encoded. 133 Implementers MUST percent encode URLs as described in Section 2.1 of 134 [RFC3986]. 136 Throughout this documents all figures may contain spaces and extra 137 line-wrapping for readability and space limitations. Similarly, some 138 URI's contained within examples, have been shortened for space and 139 readability reasons. 141 1.3. Definitions 143 This specification uses the definitions from 144 [I-D.ietf-scim-core-schema], and [I-D.ietf-scim-api]. 146 2. Discovery of Search Support 148 2.1. Advertising Support in OPTIONS 150 A server can advertise its support for the SEARCH method by adding it 151 to the listing of allowed methods in the "Allow" OPTIONS response 152 header defined in HTTP/1.1. The SEARCH method MAY appear in the 153 "Allow" header even if the Accept-Search header is absent, in which 154 case the list of allowed patch documents is not advertised. 156 2.2. The Accept-Search Header 158 As defined in [I-D.snell-search-method], the "Accept-Search" response 159 header MAY be used by service providers to directly signal support 160 for the SEARCH method while identifying the SCIM content-type. For 161 example: 163 Accept-Search: application/scim+json 165 2.3. Service Provider Configuration 167 Clients may discover service provider support for SEARCH by querying 168 the service provider configuration as described in Section 5 and 8.5 169 of [I-D.ietf-scim-core-schema]. The attribute "search" has the 170 following values: 172 supported A boolean value indicating that the required features of 173 this extension are supported. 175 stored A boolean value indicating that stored search queries are 176 supported. 178 persistent A boolean value indicating the service provider supports 179 persistent search using WebPUSH. [To be defined] 181 3. SEARCH Method 183 A SCIM server that supports HTTP SEARCH accepts and processes a 184 request whose body is defined by SCIM POST based search (see 185 Section 3.4.2 and 3.4.3 of [I-D.ietf-scim-api]). When using HTTP 186 SEARCH, the client SHOULD NOT specify "/.search" as part of the 187 request URI. The remaining content-type, request body and responses 188 specifications are identical. The request path SHALL indicate the 189 desired search scope. For example, a search at the service 190 provider's root, indicates the client wants to search all resources. 191 A search against a specific resource indicates the client wishes to 192 search or match against a specific resource. 194 Not including the impacts of independent operations by other SCIM 195 client with a SCIM service provider, the SCIM SEARCH request is 196 considered idempotent. A repeated search request should reflect the 197 same result unless a parameter (e.g., paging) or the underlying data 198 has been changed independently by another client. 200 The following is a non-normative example of a SCIM HTTP SEARCH 201 request. Note that some data has been removed and spacing added for 202 readability: 204 SEARCH /Users 205 Host: example.com 206 Accept: application/scim+json 207 Content-Type: application/scim+json 208 Authorization: Bearer h480djs93hd8 210 { 211 "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], 212 "attributes": ["displayName", "userName"], 213 "filter": 214 "displayName sw \"smith\"", 215 "startIndex": 1, 216 "count": 10 217 } 219 Figure 1: Example HTTP SEARCH Request 221 A SEARCH query response is shown with the first page of results. For 222 brevity reasons, only two matches are shown: 224 HTTP/1.1 200 OK 225 Content-Type: application/scim+json 226 Location: https://example.com/Users 227 { 228 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 229 "totalResults":100, 230 "itemsPerPage":10, 231 "startIndex":1, 232 "Resources":[ 233 { 234 "id":"2819c223-7f76-413861904646", 235 "userName":"jsmith", 236 "displayName":"Smith, James" 237 }, 238 { 239 "id":"c8596b90-7539-4f20968d1908", 240 "userName":"alice123" 241 "displayName":"Smith, Alice" 242 }, 243 ... 244 ] 245 } 247 Figure 2: Example SEARCH Response 249 The following is a non-normative example of a SCIM HTTP SEARCH 250 request that tests a specific attribute match condition of a SCIM 251 resource. Note that some data has been removed and spacing added for 252 readability: 254 SEARCH /Users/2819c223-7f76-413861904646 255 Host: example.com 256 Accept: application/scim+json 257 Content-Type: application/scim+json 258 Authorization: Bearer h480djs93hd8 260 { 261 "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], 262 "attributes": ["id"], 263 "filter": 264 "entitlements.value eq \"CRM_User\"", 265 "startIndex": 1, 266 "count": 10 267 } 269 Figure 3: Example HTTP SEARCH Against A Specific Resource 271 A successful response is shown for the match request above (see 272 Figure 3). 274 HTTP/1.1 200 OK 275 Content-Type: application/scim+json 276 Location: https://example.com/Users 277 { 278 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 279 "totalResults":1, 280 "itemsPerPage":10, 281 "startIndex":1, 282 "Resources":[ 283 { 284 "id":"2819c223-7f76-413861904646" 286 } 287 ] 288 } 290 Figure 4: Example Successful Matched Response 292 The response when no match is made to the request above (see 293 Figure 3). Note that while the request is successful, no match is 294 made, so there are zero results. 296 HTTP/1.1 200 OK 297 Content-Type: application/scim+json 298 Location: https://example.com/Users 299 { 300 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 301 "totalResults":0, 302 "itemsPerPage":10, 303 "startIndex":1, 304 "Resources":[] 305 } 307 Figure 5: Example No-Match Response 309 A service provider that receives an HTTP SEARCH request that does not 310 support HTTP SEARCH method (this extension) SHOULD return HTTP Status 311 405 (Method Not Allowed) as defined in Section 6.5.5 of [RFC7231]. 312 [[Editors note: some SCIM service providers might return status 501 313 which indicates the server does not support the technology. 314 Discuss]] 316 4. Stored Search Queries 318 A SCIM SEARCH service provider MAY support stored queries. Queries 319 that have been stored in the endpoint "Searches" may be referenced by 320 id when the body of a search request uses the schemas value of: 321 "urn:ietf:params:scim:api:messages:2.0:StoredSearch". The attributes 322 supported for a stored search request are: 324 id A SCIM id that is the id of a SCIM resource with schema of 325 "urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest". 327 $ref A URI pointing to an HTTP retrievable resource that contains a 328 JSON object defined by the schema: 329 "urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest". The 330 resource MAY be locally defined or MAY be retrieved from an 331 external SCIM service provider. 333 4.1. Storing A Search 334 The following is a non-normative example of a client creating a 335 stored search query: 337 POST /Searches HTTP/1.1 338 Host: example.com 339 Accept: application/scim+json 340 Content-Type: application/scim+json 341 Authorization: Bearer h480djs93hd8 343 { 344 "schemas": 345 ["urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest"], 346 "attributes": ["userName"], 347 "filter": 348 "entitlements.value eq \"CRM_User\"" 349 } 351 Figure 6: Stored Search Create Request 353 The following is a non-normative example of a stored search creation 354 response. 356 HTTP/1.1 201 Created 357 Content-Type: application/scim+json 358 Location: 359 https://example.com/v2/Searches/86c25f16-d9dd-4a68-a421-1355aa5ae8f0 361 { 362 "schemas": 363 ["urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest"], 364 "id":"86c25f16-d9dd-4a68-a421-1355aa5ae8f0", 365 "attributes": ["userName"], 366 "filter": 367 "entitlements.value eq \"CRM_User\"", 368 "meta": { ... } 369 } 371 Figure 7: Search Creation Response 373 4.2. Retrieving A Stored Search 374 To retrieve a known stored search, the client does an HTTP GET: 376 GET /Searches/86c25f16-d9dd-4a68-a421-1355aa5ae8f0 378 Host: example.com 379 Accept: application/scim+json 380 Authorization: Bearer h480djs93hd8 382 Figure 8: Retrieving A Stored Search Using GET 384 The service provider responds with the stored search definition 385 resource (some spacing and "..." added for clarity and brevity): 387 HTTP/1.1 200 OK 388 Content-Type: application/scim+json 389 Location: 390 https://example.com/v2/Searches/86c25f16-d9dd-4a68-a421-1355aa5ae8f0 392 { 393 "schemas": 394 ["urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest"], 395 "id":"86c25f16-d9dd-4a68-a421-1355aa5ae8f0", 396 "attributes": ["userName"], 397 "filter": 398 "entitlements.value eq \"CRM_User\"", 399 "meta": { ... } 400 } 402 Figure 9: Response to GET for Stored Search 404 4.3. Executing A Stored Search 406 The following is an example of a client executing a stored search 407 against a specific User resource. The "id" specified in the request 408 is the id of the stored request (see Figure 7). 410 SEARCH /Users/2819c223-7f76-413861904646 411 Host: example.com 412 Accept: application/scim+json 413 Content-Type: application/scim+json 414 Authorization: Bearer h480djs93hd8 416 { 417 "schemas": ["urn:ietf:params:scim:api:messages:2.0:StoredSearch"], 418 "id":"86c25f16-d9dd-4a68-a421-1355aa5ae8f0" 419 } 421 Figure 10: Executing A Stored Search with SEARCH 423 If the resource matches the filter in the stored query, the response 424 is returned as defined in the stored request with the attributes 425 userName and id. 427 HTTP/1.1 200 OK 428 Content-Type: application/scim+json 429 Location: https://example.com/.search 430 { 431 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 432 "totalResults":1, 433 "Resources":[ 434 { 435 "id":"2819c223-7f76-413861904646", 436 "userName":"jsmith", 437 } 438 ] 439 } 441 Figure 11: Example Response to Stored Search Execution 443 4.4. SCIM Schema Extension 445 This section defines the schema extensions necessary for defining the 446 store search resources. 448 4.4.1. Search Schema 450 A stored search request has a schemas value of 451 "urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest" and the 452 attributes defined are identical to those defined in Section 3.2.3 of 453 [I-D.ietf-scim-api]. In addition to the SearchRequest attributes, a 454 StoredSearchRequest also has the common attributes id, externalid, 455 and meta as defined in Section 3.1 of [I-D.ietf-scim-core-schema]. 457 4.4.2. Search Resource Type 459 A stored search has a resource type of "Search" with an endpoint of 460 "/Searches". The value of "schema" is 461 "urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest". As 462 present, no schema extensions are defined. 464 Example representation of a stored search resource type: 466 { 467 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"], 468 "id":"Search", 469 "name":"Search", 470 "endpoint": "/Searches", 471 "description": "User Account", 472 "schema": 473 "urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest", 474 "meta": { 475 "location":"https://example.com/v2/ResourceTypes/Search", 476 "resourceType": "ResourceType" 477 } 478 } 480 Figure 12: Resource Type Representation 482 5. Security Considerations 484 This specification is an extension of SCIM Protocol and carries the 485 same security considerations. See [I-D.ietf-scim-api] and 486 [I-D.ietf-scim-core-schema]. This specification is also subject to 487 the security considerations in [RFC7231]. 489 [[Discussion item to be removed prior to publiction: When a search is 490 not fully supported it is important that the entire operation fail. 491 For example, a gateway that does not support SEARCH shall normally 492 fail the request. Headers for filters were also considered as well 493 as a body on GET requests. Both of these approaches have the 494 unwanted effect of misleading the server to return results without 495 processing the filter. It is important that if the request proceeds 496 that the filter MUST be present to conform to the clients intent to 497 match the result. For example, a client that is security system that 498 is asking if a certain user has a certain attribute condition might 499 be mislead into thinking that condition is true if the server fails 500 by returning results as a simple GET.]] 502 6. Privacy Considerations 504 This specification is an extension of SCIM Protocol and carries the 505 same privacy considerations. See [I-D.ietf-scim-api] and 506 [I-D.ietf-scim-core-schema]. 508 In order to improve privacy, SCIM service providers MAY deprecate use 509 of filters with the SCIM GET command in favour of the SCIM SEARCH 510 command. 512 7. IANA Considerations 514 [[To be completed: Registration of stored query schema: 515 "urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest" and 516 StoredQuery API call 517 "urn:ietf:params:scim:api:messages:2.0:StoredSearch".]] 519 8. Normative References 521 [I-D.ietf-scim-api] 522 Hunt, P., Grizzle, K., Ansari, M., Wahlstroem, E., and C. 523 Mortimore, "System for Cross-Domain Identity Management: 524 Protocol", draft-ietf-scim-api-19 (work in progress), May 525 2015. 527 [I-D.ietf-scim-core-schema] 528 Hunt, P., Grizzle, K., Wahlstroem, E., and C. Mortimore, 529 "System for Cross-Domain Identity Management: Core 530 Schema", draft-ietf-scim-core-schema-20 (work in 531 progress), May 2015. 533 [I-D.snell-search-method] 534 Reschke, J., Malhotra, A., and J. Snell, "HTTP SEARCH 535 Method", draft-snell-search-method-00 (work in progress), 536 April 2015. 538 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 539 Requirement Levels", BCP 14, RFC 2119, March 1997. 541 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 542 Resource Identifier (URI): Generic Syntax", STD 66, RFC 543 3986, January 2005. 545 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 546 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 548 Appendix A. Change Log 550 Draft 00 - PH - Initial Draft 552 Author's Address 554 Phil Hunt (editor) 555 Oracle Corporation 557 Email: phil.hunt@yahoo.com