Internet DRAFT - draft-hunt-scim-search

draft-hunt-scim-search







Network Working Group                                       P. Hunt, Ed.
Internet-Draft                                                    Oracle
Intended status: Standards Track                            May 28, 2015
Expires: November 29, 2015


                   SCIM HTTP SEARCH Method Extension
                       draft-hunt-scim-search-00

Abstract

   The System for Cross-Domain Identity Management (SCIM) specification
   is an HTTP based protocol that makes managing identities in multi-
   domain scenarios easier to support through a standardized service.
   Examples include but are not limited to enterprise to cloud service
   providers, and inter-cloud based scenarios.  This specification
   extends the SCIM Protocol to include support for HTTP SEARCH.

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 http://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 November 29, 2015.

Copyright Notice

   Copyright (c) 2015 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
   (http://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                    Expires November 29, 2015               [Page 1]

Internet-Draft           draft-hunt-scim-search                 May 2015


   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 . . . . . . . . . . . . . . . . . . . .   3
     1.2.  Notational Conventions  . . . . . . . . . . . . . . . . .   3
     1.3.  Definitions . . . . . . . . . . . . . . . . . . . . . . .   4
   2.  Discovery of Search Support . . . . . . . . . . . . . . . . .   4
     2.1.  Advertising Support in OPTIONS  . . . . . . . . . . . . .   4
     2.2.  The Accept-Search Header  . . . . . . . . . . . . . . . .   4
     2.3.  Service Provider Configuration  . . . . . . . . . . . . .   4
   3.  SEARCH Method . . . . . . . . . . . . . . . . . . . . . . . .   4
   4.  Stored Search Queries . . . . . . . . . . . . . . . . . . . .   8
     4.1.  Storing A Search  . . . . . . . . . . . . . . . . . . . .   8
     4.2.  Retrieving A Stored Search  . . . . . . . . . . . . . . .   9
     4.3.  Executing A Stored Search . . . . . . . . . . . . . . . .  10
     4.4.  SCIM Schema Extension . . . . . . . . . . . . . . . . . .  11
       4.4.1.  Search Schema . . . . . . . . . . . . . . . . . . . .  11
       4.4.2.  Search Resource Type  . . . . . . . . . . . . . . . .  11
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  12
   6.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  12
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  13
   8.  Normative References  . . . . . . . . . . . . . . . . . . . .  13
   Appendix A.  Change Log . . . . . . . . . . . . . . . . . . . . .  13
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  13

1.  Introduction and Overview

   The SCIM Protocol 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 [I-D.ietf-scim-core-schema]).  The SCIM
   Protocol defines methods for creation, modification, deletion, and
   searching of SCIM resources (see [I-D.ietf-scim-api]).

   In SCIM Protocol, searching is currently supported using HTTP GET and
   HTTP POST (see section 3.4.2 and 3.4.3 [I-D.ietf-scim-api]).  While a
   common practice, the HTTP GET method of searching causes problems
   with the disclosure of sensitive information through URL leakage (see
   Section 7.5 [I-D.ietf-scim-api]).  In contrast, using HTTP POST has
   the disadvantage of overloading POST to perform another function
   other than creating new SCIM resources.  Further, HTTP POST requires



Hunt                    Expires November 29, 2015               [Page 2]

Internet-Draft           draft-hunt-scim-search                 May 2015


   the client to add special URI path encodings so that a SCIM service
   provider can determine the clients intent to create a resource vs.
   seaching for resources.

   This draft proposes to use the HTTP SEARCH method defined in
   [I-D.snell-search-method] as an improved approach that reduces
   complexity for SCIM clients in the future.  [[Note: the author
   acknowledges that adding a 3rd method does not reduce complexity.
   However one has to acknowledge water under the bridge and the costs
   of transition.  The intent here is to show how SCIM would have been
   simpler had SEARCH been available.]]

   One of the advantages of using HTTP SEARCH is that security control
   layers and gateways can easily differentiate from a general resource
   retrieval (e.g., via HTTP GET), or resource creation (e.g., via HTTP
   POST).  The security system is not required to parse the content of
   the URI or of the body to understand that the request is a search
   operation.

1.1.  Intended Audience

   This document is intended as a guide to 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
   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.







Hunt                    Expires November 29, 2015               [Page 3]

Internet-Draft           draft-hunt-scim-search                 May 2015


1.3.  Definitions

   This specification uses the definitions from
   [I-D.ietf-scim-core-schema], and [I-D.ietf-scim-api].

2.  Discovery of Search Support

2.1.  Advertising Support in OPTIONS

   A server can advertise its support for the SEARCH method by adding it
   to the listing of allowed methods in the "Allow" OPTIONS response
   header defined in HTTP/1.1.  The SEARCH method MAY appear in the
   "Allow" header even if the Accept-Search header is absent, in which
   case the list of allowed patch documents is not advertised.

2.2.  The Accept-Search Header

   As defined in [I-D.snell-search-method], the "Accept-Search" response
   header MAY be used by service providers to directly signal support
   for the SEARCH method while identifying the SCIM content-type.  For
   example:

   Accept-Search: application/scim+json

2.3.  Service Provider Configuration

   Clients may discover service provider support for SEARCH by querying
   the service provider configuration as described in Section 5 and 8.5
   of [I-D.ietf-scim-core-schema].  The attribute "search" has the
   following values:

   supported  A boolean value indicating that the required features of
      this extension are supported.

   stored  A boolean value indicating that stored search queries are
      supported.

   persistent  A boolean value indicating the service provider supports
      persistent search using WebPUSH.  [To be defined]

3.  SEARCH Method

   A SCIM server that supports HTTP SEARCH accepts and processes a
   request whose body is defined by SCIM POST based search (see
   Section 3.4.2 and 3.4.3 of [I-D.ietf-scim-api]).  When using HTTP
   SEARCH, the client SHOULD NOT specify "/.search" as part of the
   request URI.  The remaining content-type, request body and responses
   specifications are identical.  The request path SHALL indicate the



Hunt                    Expires November 29, 2015               [Page 4]

Internet-Draft           draft-hunt-scim-search                 May 2015


   desired search scope.  For example, a search at the service
   provider's root, indicates the client wants to search all resources.
   A search against a specific resource indicates the client wishes to
   search or match against a specific resource.

   Not including the impacts of independent operations by other SCIM
   client with a SCIM service provider, the SCIM SEARCH request is
   considered idempotent.  A repeated search request should reflect the
   same result unless a parameter (e.g., paging) or the underlying data
   has been changed independently by another client.

   The following is a non-normative example of a SCIM HTTP SEARCH
   request.  Note that some data has been removed and spacing added for
   readability:

   SEARCH /Users
   Host: example.com
   Accept: application/scim+json
   Content-Type: application/scim+json
   Authorization: Bearer h480djs93hd8

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
     "attributes": ["displayName", "userName"],
     "filter":
       "displayName sw \"smith\"",
     "startIndex": 1,
     "count": 10
   }

                   Figure 1: Example HTTP SEARCH Request




















Hunt                    Expires November 29, 2015               [Page 5]

Internet-Draft           draft-hunt-scim-search                 May 2015


   A SEARCH query response is shown with the first page of results.  For
   brevity reasons, only two matches are shown:

   HTTP/1.1 200 OK
   Content-Type: application/scim+json
   Location: https://example.com/Users
   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
     "totalResults":100,
     "itemsPerPage":10,
     "startIndex":1,
     "Resources":[
       {
         "id":"2819c223-7f76-413861904646",
         "userName":"jsmith",
         "displayName":"Smith, James"
       },
       {
         "id":"c8596b90-7539-4f20968d1908",
         "userName":"alice123"
         "displayName":"Smith, Alice"
       },
        ...
     ]
   }

                     Figure 2: Example SEARCH Response
























Hunt                    Expires November 29, 2015               [Page 6]

Internet-Draft           draft-hunt-scim-search                 May 2015


   The following is a non-normative example of a SCIM HTTP SEARCH
   request that tests a specific attribute match condition of a SCIM
   resource.  Note that some data has been removed and spacing added for
   readability:

   SEARCH /Users/2819c223-7f76-413861904646
   Host: example.com
   Accept: application/scim+json
   Content-Type: application/scim+json
   Authorization: Bearer h480djs93hd8

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
     "attributes": ["id"],
     "filter":
       "entitlements.value eq \"CRM_User\"",
     "startIndex": 1,
     "count": 10
   }

         Figure 3: Example HTTP SEARCH Against A Specific Resource

   A successful response is shown for the match request above (see
   Figure 3).

   HTTP/1.1 200 OK
   Content-Type: application/scim+json
   Location: https://example.com/Users
   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
     "totalResults":1,
     "itemsPerPage":10,
     "startIndex":1,
     "Resources":[
       {
         "id":"2819c223-7f76-413861904646"

       }
     ]
   }

               Figure 4: Example Successful Matched Response









Hunt                    Expires November 29, 2015               [Page 7]

Internet-Draft           draft-hunt-scim-search                 May 2015


   The response when no match is made to the request above (see
   Figure 3).  Note that while the request is successful, no match is
   made, so there are zero results.

   HTTP/1.1 200 OK
   Content-Type: application/scim+json
   Location: https://example.com/Users
   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
     "totalResults":0,
     "itemsPerPage":10,
     "startIndex":1,
     "Resources":[]
   }

                    Figure 5: Example No-Match Response

   A service provider that receives an HTTP SEARCH request that does not
   support HTTP SEARCH method (this extension) SHOULD return HTTP Status
   405 (Method Not Allowed) as defined in Section 6.5.5 of [RFC7231].
   [[Editors note: some SCIM service providers might return status 501
   which indicates the server does not support the technology.
   Discuss]]

4.  Stored Search Queries

   A SCIM SEARCH service provider MAY support stored queries.  Queries
   that have been stored in the endpoint "Searches" may be referenced by
   id when the body of a search request uses the schemas value of:
   "urn:ietf:params:scim:api:messages:2.0:StoredSearch".  The attributes
   supported for a stored search request are:

   id A SCIM id that is the id of a SCIM resource with schema of
      "urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest".

   $ref  A URI pointing to an HTTP retrievable resource that contains a
      JSON object defined by the schema:
      "urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest".  The
      resource MAY be locally defined or MAY be retrieved from an
      external SCIM service provider.

4.1.  Storing A Search









Hunt                    Expires November 29, 2015               [Page 8]

Internet-Draft           draft-hunt-scim-search                 May 2015


   The following is a non-normative example of a client creating a
   stored search query:

   POST /Searches  HTTP/1.1
   Host: example.com
   Accept: application/scim+json
   Content-Type: application/scim+json
   Authorization: Bearer h480djs93hd8

   {
     "schemas":
       ["urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest"],
     "attributes": ["userName"],
     "filter":
       "entitlements.value eq \"CRM_User\""
   }

                  Figure 6: Stored Search Create Request

   The following is a non-normative example of a stored search creation
   response.

   HTTP/1.1 201 Created
   Content-Type: application/scim+json
   Location:
    https://example.com/v2/Searches/86c25f16-d9dd-4a68-a421-1355aa5ae8f0

   {
     "schemas":
       ["urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest"],
     "id":"86c25f16-d9dd-4a68-a421-1355aa5ae8f0",
     "attributes": ["userName"],
     "filter":
       "entitlements.value eq \"CRM_User\"",
     "meta": { ... }
   }

                    Figure 7: Search Creation Response

4.2.  Retrieving A Stored Search











Hunt                    Expires November 29, 2015               [Page 9]

Internet-Draft           draft-hunt-scim-search                 May 2015


   To retrieve a known stored search, the client does an HTTP GET:

   GET /Searches/86c25f16-d9dd-4a68-a421-1355aa5ae8f0

   Host: example.com
   Accept: application/scim+json
   Authorization: Bearer h480djs93hd8

              Figure 8: Retrieving A Stored Search Using GET

   The service provider responds with the stored search definition
   resource (some spacing and "..." added for clarity and brevity):

   HTTP/1.1 200 OK
   Content-Type: application/scim+json
   Location:
    https://example.com/v2/Searches/86c25f16-d9dd-4a68-a421-1355aa5ae8f0

   {
     "schemas":
       ["urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest"],
     "id":"86c25f16-d9dd-4a68-a421-1355aa5ae8f0",
     "attributes": ["userName"],
     "filter":
       "entitlements.value eq \"CRM_User\"",
     "meta": { ... }
   }

                Figure 9: Response to GET for Stored Search

4.3.  Executing A Stored Search

   The following is an example of a client executing a stored search
   against a specific User resource.  The "id" specified in the request
   is the id of the stored request (see Figure 7).

   SEARCH /Users/2819c223-7f76-413861904646
   Host: example.com
   Accept: application/scim+json
   Content-Type: application/scim+json
   Authorization: Bearer h480djs93hd8

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:StoredSearch"],
     "id":"86c25f16-d9dd-4a68-a421-1355aa5ae8f0"
   }

             Figure 10: Executing A Stored Search with SEARCH



Hunt                    Expires November 29, 2015              [Page 10]

Internet-Draft           draft-hunt-scim-search                 May 2015


   If the resource matches the filter in the stored query, the response
   is returned as defined in the stored request with the attributes
   userName and id.

   HTTP/1.1 200 OK
   Content-Type: application/scim+json
   Location: https://example.com/.search
   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
     "totalResults":1,
     "Resources":[
       {
         "id":"2819c223-7f76-413861904646",
         "userName":"jsmith",
       }
     ]
   }

          Figure 11: Example Response to Stored Search Execution

4.4.  SCIM Schema Extension

   This section defines the schema extensions necessary for defining the
   store search resources.

4.4.1.  Search Schema

   A stored search request has a schemas value of
   "urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest" and the
   attributes defined are identical to those defined in Section 3.2.3 of
   [I-D.ietf-scim-api].  In addition to the SearchRequest attributes, a
   StoredSearchRequest also has the common attributes id, externalid,
   and meta as defined in Section 3.1 of [I-D.ietf-scim-core-schema].

4.4.2.  Search Resource Type

   A stored search has a resource type of "Search" with an endpoint of
   "/Searches".  The value of "schema" is
   "urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest".  As
   present, no schema extensions are defined.











Hunt                    Expires November 29, 2015              [Page 11]

Internet-Draft           draft-hunt-scim-search                 May 2015


   Example representation of a stored search resource type:

   {
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
     "id":"Search",
     "name":"Search",
     "endpoint": "/Searches",
     "description": "User Account",
     "schema":
       "urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest",
     "meta": {
       "location":"https://example.com/v2/ResourceTypes/Search",
       "resourceType": "ResourceType"
     }
   }

                  Figure 12: Resource Type Representation

5.  Security Considerations

   This specification is an extension of SCIM Protocol and carries the
   same security considerations.  See [I-D.ietf-scim-api] and
   [I-D.ietf-scim-core-schema].  This specification is also subject to
   the security considerations in [RFC7231].

   [[Discussion item to be removed prior to publiction: When a search is
   not fully supported it is important that the entire operation fail.
   For example, a gateway that does not support SEARCH shall normally
   fail the request.  Headers for filters were also considered as well
   as a body on GET requests.  Both of these approaches have the
   unwanted effect of misleading the server to return results without
   processing the filter.  It is important that if the request proceeds
   that the filter MUST be present to conform to the clients intent to
   match the result.  For example, a client that is security system that
   is asking if a certain user has a certain attribute condition might
   be mislead into thinking that condition is true if the server fails
   by returning results as a simple GET.]]

6.  Privacy Considerations

   This specification is an extension of SCIM Protocol and carries the
   same privacy considerations.  See [I-D.ietf-scim-api] and
   [I-D.ietf-scim-core-schema].

   In order to improve privacy, SCIM service providers MAY deprecate use
   of filters with the SCIM GET command in favour of the SCIM SEARCH
   command.




Hunt                    Expires November 29, 2015              [Page 12]

Internet-Draft           draft-hunt-scim-search                 May 2015


7.  IANA Considerations

   [[To be completed: Registration of stored query schema:
   "urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest" and
   StoredQuery API call
   "urn:ietf:params:scim:api:messages:2.0:StoredSearch".]]

8.  Normative References

   [I-D.ietf-scim-api]
              Hunt, P., Grizzle, K., Ansari, M., Wahlstroem, E., and C.
              Mortimore, "System for Cross-Domain Identity Management:
              Protocol", draft-ietf-scim-api-19 (work in progress), May
              2015.

   [I-D.ietf-scim-core-schema]
              Hunt, P., Grizzle, K., Wahlstroem, E., and C. Mortimore,
              "System for Cross-Domain Identity Management: Core
              Schema", draft-ietf-scim-core-schema-20 (work in
              progress), May 2015.

   [I-D.snell-search-method]
              Reschke, J., Malhotra, A., and J. Snell, "HTTP SEARCH
              Method", draft-snell-search-method-00 (work in progress),
              April 2015.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66, RFC
              3986, January 2005.

   [RFC7231]  Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Semantics and Content", RFC 7231, June 2014.

Appendix A.  Change Log

   Draft 00 - PH - Initial Draft

Author's Address

   Phil Hunt (editor)
   Oracle Corporation

   Email: phil.hunt@yahoo.com





Hunt                    Expires November 29, 2015              [Page 13]