Internet DRAFT - draft-hunt-scim-mv-paging

draft-hunt-scim-mv-paging







Network Working Group                                       P. Hunt, Ed.
Internet-Draft                                                 G. Wilson
Intended status: Standards Track                                  Oracle
Expires: February 8, 2020                                 August 7, 2019


              SCIM Protocol: Multi-Value Paging Extension
                      draft-hunt-scim-mv-paging-00

Abstract

   The System for Cross-Domain Identity Management (SCIM) specifications
   define a profile of HTTP protocol and a schema that enable managing
   identities in cross-domain scenarios.  This specification extends
   SCIM protocol resource retrieval and query functions to enable paging
   of SCIM resources that contain large complex multi-valued attributes
   such as SCIM Groups.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on February 8, 2020.

Copyright Notice

   Copyright (c) 2019 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of




Hunt & Wilson           Expires February 8, 2020                [Page 1]

Internet-Draft          draft-hunt-scim-mv-paging            August 2019


   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction and Overview . . . . . . . . . . . . . . . . . .   2
     1.1.  Intended Audience . . . . . . . . . . . . . . . . . . . .   2
     1.2.  Notational Conventions  . . . . . . . . . . . . . . . . .   2
     1.3.  Definitions . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Multi-Value Paging Extension  . . . . . . . . . . . . . . . .   3
   3.  Service Provider Configuration Feature Discovery  . . . . . .   9
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .  10
   5.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  10
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  10
   7.  Normative References  . . . . . . . . . . . . . . . . . . . .  10
   Appendix A.  Acknowledgments  . . . . . . . . . . . . . . . . . .  10
   Appendix B.  Change Log . . . . . . . . . . . . . . . . . . . . .  10
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  11

1.  Introduction and Overview

   SCIM Protocol [RFC7644] is an application-level, HTTP protocol for
   provisioning and managing identity data on the web and in cross-
   domain environments such as enterprise to cloud, or inter-cloud
   scenarios.  The protocol supports creation, modification, retrieval,
   and discovery of core identity resources such as Users and Groups, as
   well as custom resources and resource extensions.

   The definition of resources, attributes, and overall schema are
   defined in the SCIM Core Schema document (see [RFC7643]).

   This specification extends SCIM resource retrieval and query
   functions to enable paging of SCIM resources that may contain
   attributes with large numbers of values.  For example, a SCIM Group
   may contain thousands or millions of members.

1.1.  Intended Audience

   This document is intended as a guide to extend SCIM protocol usage
   for both SCIM HTTP service providers and HTTP clients who may
   provision information to service providers or retrieve information
   from them.

1.2.  Notational Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].  These



Hunt & Wilson           Expires February 8, 2020                [Page 2]

Internet-Draft          draft-hunt-scim-mv-paging            August 2019


   keywords are capitalized when used to unambiguously specify
   requirements of the protocol or application features and behavior
   that affect the interoperability and security of implementations.
   When these words are not capitalized, they are meant in their
   natural-language sense.

   For purposes of readability examples are not URL encoded.
   Implementers MUST percent encode URLs as described in Section 2.1 of
   [RFC3986].

   Throughout this documents all figures may contain spaces and extra
   line-wrapping for readability and space limitations.  Similarly, some
   URI's contained within examples, have been shortened for space and
   readability reasons.

1.3.  Definitions

   This specification uses the definitions from the SCIM Schema
   Specification [RFC7643] and the SCIM Protocol Specification
   [RFC7644].

2.  Multi-Value Paging Extension

   Detecting the availability of multi-valued attribute paging extension
   is covered in Section 3.

   When supported, returned values for multi-valued attributes can be
   filtered or paged using filters and/or paging parameters appended to
   attributes specified in the SCIM "attributes" parameter.  Attributes
   listed in the attributes parameter MAY be appended with value
   qualifiers using square brackets("[ ]") that contains a "valFilter"
   (see Figure 1 [RFC7644]), paging parameters (see Section 3.9
   [RFC7644]), or a combination of both separated by the "&" character.

   In order to qualify specific attributes without changing the default
   list of attributes returned for a query, an asterix "*" MAY be used
   in the attributes parameter to indicate the default set of attributes
   is to be returned in addition to any specific attributes listed.  For
   example: "attributes=*,members[type eq "user"]" specifies all default
   attributes are to be returned and only values of "members" which have
   "type" set to "user".

   When an attribute has a multi-value filter or paging qualifier, the
   service provider SHALL include additional "meta" sub-attributes (see
   Section 3.1 of [RFC7643]).  The name of the multi-valued attribute
   plus the String "cnt" is used to indicate the count of attribute
   values available expressed as an Integer (see Section 2.3.4 of
   [RFC7643]).  When a "valFilter" expression is used, the number SHALL



Hunt & Wilson           Expires February 8, 2020                [Page 3]

Internet-Draft          draft-hunt-scim-mv-paging            August 2019


   indicate the total number of matches that may be returned based on
   the filter.  When no filter expression is specified, the number SHALL
   indicate the total number of values.  For an example, see
   "emails.cnt" inFigure 2.  This count indicates that there is only one
   value with "type" equal to "work ".

   When "startIndex" is used as an attribute paging qualifier and the
   value is greater than the number of values, the server SHALL omit the
   attribute from the result to indicate no values exist at that index.

   In the following example, a user is returned, but only "work" emails
   are to be returned.

   GET /Users/2819c223-7f76-453a-919d-413861904646?
     attributes=*,emails[type eq \"work\"]
   Host: example.com
   Accept: application/scim+json
   Authorization: Bearer h480djs93hd8

         Figure 1: Using a filter to return only work email values































Hunt & Wilson           Expires February 8, 2020                [Page 4]

Internet-Draft          draft-hunt-scim-mv-paging            August 2019


   The service provider responds with:

   HTTP/1.1 200 OK
   Content-Type: application/scim+json
   Location:
     https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
   ETag: W/"f250dd84f0671c3"

   {
     "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
     "id":"2819c223-7f76-453a-919d-413861904646",
     "externalId":"bjensen",
     "meta":{
       "resourceType":"User",
       "created":"2011-08-01T18:29:49.793Z",
       "lastModified":"2011-08-01T18:29:49.793Z",
       "location":
   "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
       "version":"W\/\"f250dd84f0671c3\"",
       "emails.cnt":1
     },
     "name":{
       "formatted":"Ms. Barbara J Jensen III",
       "familyName":"Jensen",
       "givenName":"Barbara"
     },
     "userName":"bjensen",
     "phoneNumbers":[
       {
         "value":"555-555-8377",
         "type":"work"
       }
     ],
     "emails":[
       {
         "value":"bjensen@example.com",
         "type":"work"
       }
     ]
   }

             Figure 2: Response with filtered emails attribute









Hunt & Wilson           Expires February 8, 2020                [Page 5]

Internet-Draft          draft-hunt-scim-mv-paging            August 2019


   In the following example, all Groups are searched and only Groups
   whose name starts with "Group" are selected.  Additionally, the
   members attribute values are filtered return only member values with
   "type" equal to "groups" (as in sub-groups) returning only the first
   5 values using the attributes paging qualifying parameters.

  GET /v2/Groups?filter=displayName sw 'Group'&attributes=*,members[type
      eq \"Group\"&count=5&startIndex=1]
  Host: example.com
  Accept: application/scim+json
  Authorization: Bearer h480djs93hd8

       Figure 3: Querying multiple groups with attribute qualifiers

   The server responds with 2 matched resources.  The first resource
   only has one Group member value, while the second resource has 7
   member values and has been limited to the first 5 members per the
   "count" paging parameter .

   HTTP/1.1 200 OK
   Content-Type: application/scim+json

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
     "totalResults": 2,
     "Resources": [
       {
         "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
         "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
         "displayName": "Group A",
         "meta": {
           "resourceType": "Group",
           "created": "2011-08-01T18:29:49.793Z",
           "lastModified": "2011-08-01T18:29:51.135Z",
           "location":
   "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
           "version": "W\/\"mvwNGaxB5SDq074p\"",
           "members.cnt":1
         },
         "members": [
           {
             "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
             "$ref":
   "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
             "type": "Group"
           }
         ]
       },



Hunt & Wilson           Expires February 8, 2020                [Page 6]

Internet-Draft          draft-hunt-scim-mv-paging            August 2019


       {
         "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
         "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
         "displayName": "Group B",
         "meta": {
           "resourceType": "Group",
           "created": "2011-08-01T18:29:50.873Z",
           "lastModified": "2011-08-01T18:29:50.873Z",
           "location":
   "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
           "version": "W\/\"wGB85s2QJMjiNnuI\"",
           "members.cnt":7
         },
         "members": [
           {
             "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
             "$ref":
   "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
             "type": "Group"
           }
           {
             "value": "596ec090-2f66-4d3e-ad4c-68d9ac05ad53",
             "$ref":
   "https://example.com/v2/Groups/596ec090-2f66-4d3e-ad4c-68d9ac05ad53",
             "type": "Group"
           }
           {
             "value": "aaf4c421-ceba-4ce0-a119-3d62418f5f9f",
             "$ref":
   "https://example.com/v2/Groups/aaf4c421-ceba-4ce0-a119-3d62418f5f9f",
             "type": "Group"
           }
           {
             "value": "58b64358-82e7-4a77-a8eb-9c6d644f9752",
             "$ref":
   "https://example.com/v2/Groups/58b64358-82e7-4a77-a8eb-9c6d644f9752",
             "type": "Group"
           }
           {
             "value": "3e32ee8c-246c-42ab-a750-2c2e84d57f1f",
             "$ref":
   "https://example.com/v2/Groups/3e32ee8c-246c-42ab-a750-2c2e84d57f1f",
             "type": "Group"
           }
         ]
       }
     ]
   }



Hunt & Wilson           Expires February 8, 2020                [Page 7]

Internet-Draft          draft-hunt-scim-mv-paging            August 2019


     Figure 4: Returning multiple results with paged attribute values

   In Figure 3 the client may observe that the number of matches
   available for the second Group (whose "id" is
   "6c5bb468-14b2-4183-baf2-06d523e03bd3") is 7.  In Figure 4, the
   client may return the second page, by repeating the query with
   "startIndex" set to 6.

   In the following example, paging of member values of a specific group
   is requested.

GET /v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3?attributes=*,members[type
                  eq \"Group\"&count=5&startIndex=6]
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8

   Figure 5: Query returning the second page of values for an attribute

































Hunt & Wilson           Expires February 8, 2020                [Page 8]

Internet-Draft          draft-hunt-scim-mv-paging            August 2019


   HTTP/1.1 200 OK
   Content-Type: application/scim+json
   Location:
    https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
   ETag: W/"lha5bbazU3fNvfe5"

   {
     "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3",

     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
     "displayName": "Group B",
     "meta": {
       "resourceType": "Group",
       "created": "2011-08-01T18:29:50.873Z",
       "lastModified": "2011-08-01T18:29:50.873Z",
       "location":
   "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
       "version": "W\/\"wGB85s2QJMjiNnuI\"",
       "members.cnt":7
     },

     "members": [
       {
         "value": "596ec090-2f66-4d3e-ad4c-68d9ac05ad53",
         "$ref":
   "https://example.com/v2/Groups/596ec090-2f66-4d3e-ad4c-68d9ac05ad53",
         "type": "Group"
       }
       {
         "value": "2e6afed5-282d-4563-83dc-9ef7183b0003",
         "$ref":
   "https://example.com/v2/Groups/2e6afed5-282d-4563-83dc-9ef7183b0003",
         "type": "Group"
       }
     ]
   }

      Figure 6: Returning the second page of values for an attribute

3.  Service Provider Configuration Feature Discovery

   Multi-value paging support may be determined by querying the
   "/ServiceProviderConfig" endpoint and looking up the Boolean
   attribute "mvpaging" indicating support for multi-valued paging.







Hunt & Wilson           Expires February 8, 2020                [Page 9]

Internet-Draft          draft-hunt-scim-mv-paging            August 2019


4.  Security Considerations

   To be completed

5.  Privacy Considerations

   To be completed.

6.  IANA Considerations

   No IANA considerations.

7.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, DOI 10.17487/RFC3986, January 2005,
              <https://www.rfc-editor.org/info/rfc3986>.

   [RFC7643]  Hunt, P., Ed., Grizzle, K., Wahlstroem, E., and C.
              Mortimore, "System for Cross-domain Identity Management:
              Core Schema", RFC 7643, DOI 10.17487/RFC7643, September
              2015, <https://www.rfc-editor.org/info/rfc7643>.

   [RFC7644]  Hunt, P., Ed., Grizzle, K., Ansari, M., Wahlstroem, E.,
              and C. Mortimore, "System for Cross-domain Identity
              Management: Protocol", RFC 7644, DOI 10.17487/RFC7644,
              September 2015, <https://www.rfc-editor.org/info/rfc7644>.

Appendix A.  Acknowledgments

   The editors would like to acknowledge the contribution and work of
   the past draft editors:

Appendix B.  Change Log

   [[This section to be removed prior to publication as an RFC]]

   Draft 00 - PH - Initial draft







Hunt & Wilson           Expires February 8, 2020               [Page 10]

Internet-Draft          draft-hunt-scim-mv-paging            August 2019


Authors' Addresses

   Phil Hunt (editor)
   Oracle Corporation

   Email: phil.hunt@yahoo.com


   Gregg Wilson
   Oracle Corporation

   Email: gregg.wilson@oracle.com







































Hunt & Wilson           Expires February 8, 2020               [Page 11]