One document matched: draft-hunt-scim-search-00.xml

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type='text/xsl' href='http://xml.resource.org/authoring/rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-hunt-scim-search-00" ipr="trust200902">
  <front>
    <title abbrev="draft-hunt-scim-search">SCIM HTTP SEARCH Method
    Extension</title>

    <author fullname="Phil Hunt" initials="P." role="editor" surname="Hunt">
      <organization abbrev="Oracle">Oracle Corporation</organization>

      <address>
        <email>phil.hunt@yahoo.com</email>
      </address>
    </author>

    <date month="May" year="2015"/>

    <keyword>SCIM</keyword>

    <abstract>
      <t>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.</t>
    </abstract>
  </front>

  <middle>
    <section anchor="intro" title="Introduction and Overview" toc="default">
      <t>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 <xref target="I-D.ietf-scim-core-schema"/>). The SCIM
      Protocol defines methods for creation, modification, deletion, and
      searching of SCIM resources (see <xref
      target="I-D.ietf-scim-api"/>).</t>

      <t>In SCIM Protocol, searching is currently supported using HTTP GET and
      HTTP POST (see section 3.4.2 and 3.4.3 <xref
      target="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 <xref
      target="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 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.</t>

      <t>This draft proposes to use the HTTP SEARCH method defined in <xref
      target="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.]]</t>

      <t>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.</t>

      <section title="Intended Audience" toc="default">
        <t>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.</t>
      </section>

      <section anchor="notat" title="Notational Conventions" toc="default">
        <t>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 <xref
        target="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.</t>

        <t>For purposes of readability examples are not URL encoded.
        Implementers MUST percent encode URLs as described in <xref
        target="RFC3986">Section 2.1 of</xref>.</t>

        <t>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.</t>
      </section>

      <section anchor="defs" title="Definitions" toc="default">
        <t>This specification uses the definitions from <xref
        target="I-D.ietf-scim-core-schema"/>, and <xref
        target="I-D.ietf-scim-api"/>.</t>
      </section>
    </section>

    <section title="Discovery of Search Support">
      <section title="Advertising Support in OPTIONS">
        <t>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.</t>
      </section>

      <section title="The Accept-Search Header">
        <t>As defined in <xref target="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:<figure align="center">
            <artwork>Accept-Search: application/scim+json</artwork>
          </figure></t>
      </section>

      <section title="Service Provider Configuration">
        <t>Clients may discover service provider support for SEARCH by
        querying the service provider configuration as described in Section 5
        and 8.5 of <xref target="I-D.ietf-scim-core-schema"/>. The attribute
        <spanx style="verb">search</spanx> has the following values:<list
            style="hanging">
            <t hangText="supported">A boolean value indicating that the
            required features of this extension are supported.</t>

            <t hangText="stored">A boolean value indicating that stored search
            queries are supported.</t>

            <t hangText="persistent">A boolean value indicating the service
            provider supports persistent search using WebPUSH. [To be
            defined]</t>
          </list></t>
      </section>
    </section>

    <section anchor="searchMethod" title="SEARCH Method">
      <t>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 <xref target="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
      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.</t>

      <t>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.</t>

      <figure anchor="searchRequest" title="Example HTTP SEARCH Request">
        <preamble>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:</preamble>

        <artwork>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
}</artwork>
      </figure>

      <figure align="left" anchor="searchResponse"
              title="Example SEARCH Response">
        <preamble>A SEARCH query response is shown with the first page of
        results. For brevity reasons, only two matches are shown:</preamble>

        <artwork align="center">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"
    },
     ...
  ]
} </artwork>
      </figure>

      <figure anchor="matchRequest"
              title="Example HTTP SEARCH Against A Specific Resource">
        <preamble>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:</preamble>

        <artwork>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
}</artwork>
      </figure>

      <figure align="left" anchor="matchResponse"
              title="Example Successful Matched Response">
        <preamble>A successful response is shown for the match request above
        (see <xref target="matchRequest"/>). </preamble>

        <artwork align="center">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"       
     
    }
  ]
} </artwork>
      </figure>

      <figure align="left" anchor="matchFailResponse"
              title="Example No-Match Response">
        <preamble>The response when no match is made to the request above (see
        <xref target="matchRequest"/>). Note that while the request is
        successful, no match is made, so there are zero results.</preamble>

        <artwork align="center">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":[]
} </artwork>
      </figure>

      <t>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 <xref
      target="RFC7231"/>. [[Editors note: some SCIM service providers might
      return status 501 which indicates the server does not support the
      technology. Discuss]]</t>
    </section>

    <section title="Stored Search Queries">
      <t>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: <spanx
      style="verb">urn:ietf:params:scim:api:messages:2.0:StoredSearch</spanx>.
      The attributes supported for a stored search request are:<list
          style="hanging">
          <t hangText="id">A SCIM id that is the id of a SCIM resource with
          schema of <spanx style="verb">urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest</spanx>.</t>

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

      <t/>

      <section title="Storing A Search">
        <figure anchor="createRequest" title="Stored Search Create Request">
          <preamble>The following is a non-normative example of a client
          creating a stored search query:</preamble>

          <artwork>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\""
}</artwork>
        </figure>

        <figure anchor="createResponse" title="Search Creation Response">
          <preamble>The following is a non-normative example of a stored
          search creation response.</preamble>

          <artwork>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": { ... }
}</artwork>
        </figure>
      </section>

      <section title="Retrieving A Stored Search">
        <figure anchor="getRequest"
                title="Retrieving A Stored Search Using GET">
          <preamble>To retrieve a known stored search, the client does an HTTP
          GET:</preamble>

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

Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8                     </artwork>
        </figure>

        <figure anchor="getResponse" title="Response to GET for Stored Search">
          <preamble>The service provider responds with the stored search
          definition resource (some spacing and "..." added for clarity and
          brevity):</preamble>

          <artwork>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": { ... }
}
</artwork>
        </figure>
      </section>

      <section title="Executing A Stored Search">
        <figure anchor="storedSearchRequest"
                title="Executing A Stored Search with SEARCH">
          <preamble>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 <xref
          target="createResponse"/>).</preamble>

          <artwork>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"
}</artwork>
        </figure>

        <figure anchor="storedSearchResponse"
                title="Example Response to Stored Search Execution">
          <preamble>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.</preamble>

          <artwork>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",
    }
  ]
} </artwork>
        </figure>
      </section>

      <section title="SCIM Schema Extension">
        <t>This section defines the schema extensions necessary for defining
        the store search resources.</t>

        <section title="Search Schema">
          <t>A stored search request has a schemas value of <spanx
          style="verb">urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest</spanx>
          and the attributes defined are identical to those defined in Section
          3.2.3 of <xref target="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
          <xref target="I-D.ietf-scim-core-schema"/>.</t>
        </section>

        <section title="Search Resource Type">
          <t>A stored search has a resource type of <spanx style="verb">Search</spanx>
          with an endpoint of <spanx style="verb">/Searches</spanx>. The value
          of <spanx style="verb">schema</spanx> is <spanx style="verb">urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest</spanx>.
          As present, no schema extensions are defined.</t>

          <figure anchor="searchResourceType"
                  title="Resource Type Representation">
            <preamble>Example representation of a stored search resource
            type:</preamble>

            <artwork>{
  "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"
  }
}</artwork>
          </figure>
        </section>
      </section>
    </section>

    <section anchor="Security" title="Security Considerations" toc="default">
      <t>This specification is an extension of SCIM Protocol and carries the
      same security considerations. See <xref target="I-D.ietf-scim-api"/> and
      <xref target="I-D.ietf-scim-core-schema"/>. This specification is also
      subject to the security considerations in <xref target="RFC7231"/>.</t>

      <t>[[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.]]</t>
    </section>

    <section title="Privacy Considerations">
      <t>This specification is an extension of SCIM Protocol and carries the
      same privacy considerations. See <xref target="I-D.ietf-scim-api"/> and
      <xref target="I-D.ietf-scim-core-schema"/>. </t>

      <t>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.</t>
    </section>

    <section anchor="IANA" title="IANA Considerations">
      <t>[[To be completed: Registration of stored query schema: <spanx
      style="verb">urn:ietf:params:scim:schemas:core:2.0:StoredSearchRequest</spanx>
      and StoredQuery API call <spanx style="verb">urn:ietf:params:scim:api:messages:2.0:StoredSearch</spanx>.]]</t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml' ?>

      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml' ?>

      <?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml'?>

      <?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-scim-core-schema-20.xml'?>

      <?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-scim-api-19.xml'?>

      <?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-snell-search-method-00.xml'?>
    </references>

    <section title="Change Log">
      <t>Draft 00 - PH - Initial Draft</t>
    </section>
  </back>
</rfc>