SCIM 2.0 Token Search Extension

Abstract

   The SCIM 2.0 Core API defines a simple profile for searching for
   specific resource types using filters and qualifiers in combination
   with the HTTP GET verb.  The Token Search specification defines the
   following additional features:

   o  Specification of search terms within an HTTP POST verb to avoid
      accidental leakage of confidential information via HTTP GET URLs,

   o  An optional result set token enabling clients to page through
      results in a state consistent fashion, and

   o  The ability to search across multiple resource types (endpoints)
      and return one or more resource types.



1.  Introduction

   The SCIM Core API is an application-level, RESTful service for
   provisioning and managing identity data on the web.  The SCIM Core
   API specification[I-D.ietf-scim-api] defines methods for creation,
   modification, retrieval and discovery of resources.  This
   specification extends SCIM Core API capabilities to support extended
   searching operations:

   o  the ability to query for one or more resources using a filter,

   o  the ability to search from any resource endpoint including the
      server root,

   o  the ability to support result sets which provide consistent search
      results across multiple requests,

   o  a POST Search profile which supports searching with parameters not
      included in the URL, and

   o  a token parameter which supports returning stateful paged results.

   [Discuss: This extension specification does not propose any change in
   functionality to the existing GET search functions with the exception
   of making resourceType a searchable filter term and returning
   resourceType in all JSON resource representations]

   [Note: this specification may be optionally combined with the SCIM
   core API spec]

1.1.  Requirements Language

   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].

   Note: For readability and space reasons, some included examples and
   attribute values, and UUID identifiers are shortened.


2.  Search Extension

   The SCIM protocol specifies well known endpoints and HTTP methods for
   managing resources in the core schema.  In SCIM Extended Search, a
   virtual resource known as a "search" is defined.  A "search" is a
   RESTful representation of a search of a set of objects in a SCIM
   Service Provider.  A SCIM extended "search" endpoint can be appended
   to any normal SCIM endpoint in order to define open scope and



Hunt, et al.              Expires June 26, 2013                 [Page 4]

Internet-Draft              SCIM Token Search              December 2012


   specific resource scoped searches.

   SCIM Extended Searches are defined (in ABNF [RFC5234]) as follows:
      SCIMSEARCH   = scimEndpoint [scimSearch] ["/" UUID] ["?" query]

      scimEndpoint = "https://" authority [path-absolute] [scimVers]
                     [scimResType] ["/" UUID]

      scimSearch   = "/.search"

      authority    = [ userinfo "@" ] host [ ":" port ]

      scimVers     = "/V" 1*DIGIT

      scimResType  = "/Users" / "/Groups" / "/" 1*extResChar

      extResChar   = "-" / "." / "_" / DIGIT / ALPHA

                 Figure 1: ABNF for SCIM Search Endpoints

   [Discussion: since a search within a "/Users" endpoint could be
   confused with a resource, do we want to have something more jarring
   like "xsearch" or ".search" (as in well-known urls)?]

   Where:

   scimSearch    Is a special path qualifier that indicates the
                 operation is related to a search.  When used with HTTP
                 GET, scimSearch is OPTIONAL.

   authority, path-absolute, userinfo, host, port  Are defined as per
                 URI Syntax ABNF [RFC3986]

   query         Is any SCIM query term as specified in section 3.2 of
                 the SCIM Core API [I-D.ietf-scim-api].

   scimVers      Is the SCIM Service Provider API version.

   scimResType   Is a SCIM resource type such as "Users", "Groups" or
                 any other schema extended resource supported by the
                 service provider.

   UUID          Identifies a unique SCIM resource or SCIM search result
                 that is retrievable from the SCIM Service Provider (see
                 [RFC4122]).

   Example SCIM Search endpoints include:


Internet-Draft              SCIM Token Search              December 2012


   http://example.com/scim/v2/.search
                 for server-wide searches

   http://example.com/scim/v2/Users/.search
                 for searches of User resources only

   http://example.com/scim/v2/Groups/.search
                 for searches of Group resources only

   http://example.com/scim/v2/
   .search?searchId=607dac9b24a2;startIndex=20
                 to return results from a previously executed query

   Token search is initiated by using either an HTTP POST or HTTP GET
   command (see next sections) to pass search parameters AND by setting
   the parameter "stateful" to "true".  The server responds and returns
   results in a JSON result set along with a searchId token if stateful
   results are available.