idnits 2.17.1 draft-hunt-scim-mv-paging-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 is 1 instance of too long lines in the document, the longest one being 5 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 7, 2019) is 1717 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) No issues found here. Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Hunt, Ed. 3 Internet-Draft G. Wilson 4 Intended status: Standards Track Oracle 5 Expires: February 8, 2020 August 7, 2019 7 SCIM Protocol: Multi-Value Paging Extension 8 draft-hunt-scim-mv-paging-00 10 Abstract 12 The System for Cross-Domain Identity Management (SCIM) specifications 13 define a profile of HTTP protocol and a schema that enable managing 14 identities in cross-domain scenarios. This specification extends 15 SCIM protocol resource retrieval and query functions to enable paging 16 of SCIM resources that contain large complex multi-valued attributes 17 such as SCIM Groups. 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 https://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 February 8, 2020. 36 Copyright Notice 38 Copyright (c) 2019 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 (https://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 . . . . . . . . . . . . . . . . . . . . 2 55 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 2 56 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Multi-Value Paging Extension . . . . . . . . . . . . . . . . 3 58 3. Service Provider Configuration Feature Discovery . . . . . . 9 59 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 60 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 10 61 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 62 7. Normative References . . . . . . . . . . . . . . . . . . . . 10 63 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 10 64 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 10 65 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 67 1. Introduction and Overview 69 SCIM Protocol [RFC7644] is an application-level, HTTP protocol for 70 provisioning and managing identity data on the web and in cross- 71 domain environments such as enterprise to cloud, or inter-cloud 72 scenarios. The protocol supports creation, modification, retrieval, 73 and discovery of core identity resources such as Users and Groups, as 74 well as custom resources and resource extensions. 76 The definition of resources, attributes, and overall schema are 77 defined in the SCIM Core Schema document (see [RFC7643]). 79 This specification extends SCIM resource retrieval and query 80 functions to enable paging of SCIM resources that may contain 81 attributes with large numbers of values. For example, a SCIM Group 82 may contain thousands or millions of members. 84 1.1. Intended Audience 86 This document is intended as a guide to extend SCIM protocol usage 87 for both SCIM HTTP service providers and HTTP clients who may 88 provision information to service providers or retrieve information 89 from them. 91 1.2. Notational Conventions 93 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 94 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 95 document are to be interpreted as described in [RFC2119]. These 96 keywords are capitalized when used to unambiguously specify 97 requirements of the protocol or application features and behavior 98 that affect the interoperability and security of implementations. 99 When these words are not capitalized, they are meant in their 100 natural-language sense. 102 For purposes of readability examples are not URL encoded. 103 Implementers MUST percent encode URLs as described in Section 2.1 of 104 [RFC3986]. 106 Throughout this documents all figures may contain spaces and extra 107 line-wrapping for readability and space limitations. Similarly, some 108 URI's contained within examples, have been shortened for space and 109 readability reasons. 111 1.3. Definitions 113 This specification uses the definitions from the SCIM Schema 114 Specification [RFC7643] and the SCIM Protocol Specification 115 [RFC7644]. 117 2. Multi-Value Paging Extension 119 Detecting the availability of multi-valued attribute paging extension 120 is covered in Section 3. 122 When supported, returned values for multi-valued attributes can be 123 filtered or paged using filters and/or paging parameters appended to 124 attributes specified in the SCIM "attributes" parameter. Attributes 125 listed in the attributes parameter MAY be appended with value 126 qualifiers using square brackets("[ ]") that contains a "valFilter" 127 (see Figure 1 [RFC7644]), paging parameters (see Section 3.9 128 [RFC7644]), or a combination of both separated by the "&" character. 130 In order to qualify specific attributes without changing the default 131 list of attributes returned for a query, an asterix "*" MAY be used 132 in the attributes parameter to indicate the default set of attributes 133 is to be returned in addition to any specific attributes listed. For 134 example: "attributes=*,members[type eq "user"]" specifies all default 135 attributes are to be returned and only values of "members" which have 136 "type" set to "user". 138 When an attribute has a multi-value filter or paging qualifier, the 139 service provider SHALL include additional "meta" sub-attributes (see 140 Section 3.1 of [RFC7643]). The name of the multi-valued attribute 141 plus the String "cnt" is used to indicate the count of attribute 142 values available expressed as an Integer (see Section 2.3.4 of 143 [RFC7643]). When a "valFilter" expression is used, the number SHALL 144 indicate the total number of matches that may be returned based on 145 the filter. When no filter expression is specified, the number SHALL 146 indicate the total number of values. For an example, see 147 "emails.cnt" inFigure 2. This count indicates that there is only one 148 value with "type" equal to "work ". 150 When "startIndex" is used as an attribute paging qualifier and the 151 value is greater than the number of values, the server SHALL omit the 152 attribute from the result to indicate no values exist at that index. 154 In the following example, a user is returned, but only "work" emails 155 are to be returned. 157 GET /Users/2819c223-7f76-453a-919d-413861904646? 158 attributes=*,emails[type eq \"work\"] 159 Host: example.com 160 Accept: application/scim+json 161 Authorization: Bearer h480djs93hd8 163 Figure 1: Using a filter to return only work email values 165 The service provider responds with: 167 HTTP/1.1 200 OK 168 Content-Type: application/scim+json 169 Location: 170 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 171 ETag: W/"f250dd84f0671c3" 173 { 174 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 175 "id":"2819c223-7f76-453a-919d-413861904646", 176 "externalId":"bjensen", 177 "meta":{ 178 "resourceType":"User", 179 "created":"2011-08-01T18:29:49.793Z", 180 "lastModified":"2011-08-01T18:29:49.793Z", 181 "location": 182 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 183 "version":"W\/\"f250dd84f0671c3\"", 184 "emails.cnt":1 185 }, 186 "name":{ 187 "formatted":"Ms. Barbara J Jensen III", 188 "familyName":"Jensen", 189 "givenName":"Barbara" 190 }, 191 "userName":"bjensen", 192 "phoneNumbers":[ 193 { 194 "value":"555-555-8377", 195 "type":"work" 196 } 197 ], 198 "emails":[ 199 { 200 "value":"bjensen@example.com", 201 "type":"work" 202 } 203 ] 204 } 206 Figure 2: Response with filtered emails attribute 208 In the following example, all Groups are searched and only Groups 209 whose name starts with "Group" are selected. Additionally, the 210 members attribute values are filtered return only member values with 211 "type" equal to "groups" (as in sub-groups) returning only the first 212 5 values using the attributes paging qualifying parameters. 214 GET /v2/Groups?filter=displayName sw 'Group'&attributes=*,members[type 215 eq \"Group\"&count=5&startIndex=1] 216 Host: example.com 217 Accept: application/scim+json 218 Authorization: Bearer h480djs93hd8 220 Figure 3: Querying multiple groups with attribute qualifiers 222 The server responds with 2 matched resources. The first resource 223 only has one Group member value, while the second resource has 7 224 member values and has been limited to the first 5 members per the 225 "count" paging parameter . 227 HTTP/1.1 200 OK 228 Content-Type: application/scim+json 230 { 231 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 232 "totalResults": 2, 233 "Resources": [ 234 { 235 "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 236 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 237 "displayName": "Group A", 238 "meta": { 239 "resourceType": "Group", 240 "created": "2011-08-01T18:29:49.793Z", 241 "lastModified": "2011-08-01T18:29:51.135Z", 242 "location": 243 "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 244 "version": "W\/\"mvwNGaxB5SDq074p\"", 245 "members.cnt":1 246 }, 247 "members": [ 248 { 249 "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 250 "$ref": 251 "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 252 "type": "Group" 253 } 254 ] 255 }, 256 { 257 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 258 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 259 "displayName": "Group B", 260 "meta": { 261 "resourceType": "Group", 262 "created": "2011-08-01T18:29:50.873Z", 263 "lastModified": "2011-08-01T18:29:50.873Z", 264 "location": 265 "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 266 "version": "W\/\"wGB85s2QJMjiNnuI\"", 267 "members.cnt":7 268 }, 269 "members": [ 270 { 271 "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 272 "$ref": 273 "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 274 "type": "Group" 275 } 276 { 277 "value": "596ec090-2f66-4d3e-ad4c-68d9ac05ad53", 278 "$ref": 279 "https://example.com/v2/Groups/596ec090-2f66-4d3e-ad4c-68d9ac05ad53", 280 "type": "Group" 281 } 282 { 283 "value": "aaf4c421-ceba-4ce0-a119-3d62418f5f9f", 284 "$ref": 285 "https://example.com/v2/Groups/aaf4c421-ceba-4ce0-a119-3d62418f5f9f", 286 "type": "Group" 287 } 288 { 289 "value": "58b64358-82e7-4a77-a8eb-9c6d644f9752", 290 "$ref": 291 "https://example.com/v2/Groups/58b64358-82e7-4a77-a8eb-9c6d644f9752", 292 "type": "Group" 293 } 294 { 295 "value": "3e32ee8c-246c-42ab-a750-2c2e84d57f1f", 296 "$ref": 297 "https://example.com/v2/Groups/3e32ee8c-246c-42ab-a750-2c2e84d57f1f", 298 "type": "Group" 299 } 300 ] 301 } 302 ] 303 } 304 Figure 4: Returning multiple results with paged attribute values 306 In Figure 3 the client may observe that the number of matches 307 available for the second Group (whose "id" is 308 "6c5bb468-14b2-4183-baf2-06d523e03bd3") is 7. In Figure 4, the 309 client may return the second page, by repeating the query with 310 "startIndex" set to 6. 312 In the following example, paging of member values of a specific group 313 is requested. 315 GET /v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3?attributes=*,members[type 316 eq \"Group\"&count=5&startIndex=6] 317 Host: example.com 318 Accept: application/scim+json 319 Authorization: Bearer h480djs93hd8 321 Figure 5: Query returning the second page of values for an attribute 322 HTTP/1.1 200 OK 323 Content-Type: application/scim+json 324 Location: 325 https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 326 ETag: W/"lha5bbazU3fNvfe5" 328 { 329 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 331 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 332 "displayName": "Group B", 333 "meta": { 334 "resourceType": "Group", 335 "created": "2011-08-01T18:29:50.873Z", 336 "lastModified": "2011-08-01T18:29:50.873Z", 337 "location": 338 "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 339 "version": "W\/\"wGB85s2QJMjiNnuI\"", 340 "members.cnt":7 341 }, 343 "members": [ 344 { 345 "value": "596ec090-2f66-4d3e-ad4c-68d9ac05ad53", 346 "$ref": 347 "https://example.com/v2/Groups/596ec090-2f66-4d3e-ad4c-68d9ac05ad53", 348 "type": "Group" 349 } 350 { 351 "value": "2e6afed5-282d-4563-83dc-9ef7183b0003", 352 "$ref": 353 "https://example.com/v2/Groups/2e6afed5-282d-4563-83dc-9ef7183b0003", 354 "type": "Group" 355 } 356 ] 357 } 359 Figure 6: Returning the second page of values for an attribute 361 3. Service Provider Configuration Feature Discovery 363 Multi-value paging support may be determined by querying the 364 "/ServiceProviderConfig" endpoint and looking up the Boolean 365 attribute "mvpaging" indicating support for multi-valued paging. 367 4. Security Considerations 369 To be completed 371 5. Privacy Considerations 373 To be completed. 375 6. IANA Considerations 377 No IANA considerations. 379 7. Normative References 381 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 382 Requirement Levels", BCP 14, RFC 2119, 383 DOI 10.17487/RFC2119, March 1997, 384 . 386 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 387 Resource Identifier (URI): Generic Syntax", STD 66, 388 RFC 3986, DOI 10.17487/RFC3986, January 2005, 389 . 391 [RFC7643] Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C. 392 Mortimore, "System for Cross-domain Identity Management: 393 Core Schema", RFC 7643, DOI 10.17487/RFC7643, September 394 2015, . 396 [RFC7644] Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E., 397 and C. Mortimore, "System for Cross-domain Identity 398 Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, 399 September 2015, . 401 Appendix A. Acknowledgments 403 The editors would like to acknowledge the contribution and work of 404 the past draft editors: 406 Appendix B. Change Log 408 [[This section to be removed prior to publication as an RFC]] 410 Draft 00 - PH - Initial draft 412 Authors' Addresses 414 Phil Hunt (editor) 415 Oracle Corporation 417 Email: phil.hunt@yahoo.com 419 Gregg Wilson 420 Oracle Corporation 422 Email: gregg.wilson@oracle.com