One document matched: draft-hunt-scim-tokensearch-00.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!-- This template is for creating an Internet Draft using xml2rfc,
which is available here: http://xml.resource.org. -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!-- One method to get references from the online citation libraries.
There has to be one entity for each item to be referenced.
An alternate method (rfc include) is described in the references. -->
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">
<!ENTITY RFC3552 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3552.xml">
<!ENTITY I-D.narten-iana-considerations-rfc2434bis SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.narten-iana-considerations-rfc2434bis.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!-- For a complete list and description of processing instructions (PIs),
please see http://xml.resource.org/authoring/README.html. -->
<!-- Below are generally applicable Processing Instructions (PIs) that most I-Ds might want to use.
(Here they are set differently than their defaults in xml2rfc v1.32) -->
<?rfc strict="yes" ?>
<!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc tocdepth="4"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<!-- control vertical white space
(using these PIs as follows is recommended by the RFC Editor) -->
<?rfc compact="yes" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?>
<!-- keep one blank line between list items -->
<!-- end of list of popular I-D processing instructions -->
<rfc category="std" docName="draft-hunt-scim-tokensearch-00" ipr="trust200902">
<!-- category values: std, bcp, info, exp, and historic
ipr values: full3667, noModification3667, noDerivatives3667
you can add the attributes updates="NNNN" and obsoletes="NNNN"
they will automatically be output with "(if approved)" -->
<!-- ***** FRONT MATTER ***** -->
<front>
<!-- The abbreviated title is used in the page header - it is only necessary if the
full title is longer than 39 characters -->
<title abbrev="SCIM Token Search">SCIM 2.0 Token Search Extension</title>
<!-- add 'role="editor"' below for the editors if appropriate -->
<!-- Another author who claims to be an editor -->
<author fullname="Phil Hunt" initials="P." role="editor" surname="Hunt">
<organization>Oracle</organization>
<address>
<email>phil.hunt@yahoo.com</email>
</address>
</author>
<author fullname="Kelly Grizzle" initials="K." surname="Grizzle">
<organization>Sailpoint</organization>
</author>
<author fullname="Bjorn Aannestad" initials="B." surname="Annestad">
<organization>UnboundID</organization>
</author>
<author fullname="Morteza Ansari" initials="M." surname="Ansari">
<organization>CISCO</organization>
</author>
<author fullname="Dale Olds" initials="D." surname="Olds">
<organization>VMWare</organization>
</author>
<date month="December" year="2012"/>
<!-- If the month and year are both specified and are the current ones, xml2rfc will fill
in the current day for you. If only the current year is specified, xml2rfc will fill
in the current day and month for you. If the year is not the current one, it is
necessary to specify at least a month (xml2rfc assumes day="1" if not specified for the
purpose of calculating the expiry date). With drafts it is normally sufficient to
specify just the year. -->
<!-- Meta-data Declarations -->
<area>Apps</area>
<workgroup>Network Working Group</workgroup>
<!-- WG name at the upperleft corner of the doc,
IETF is fine for individual submissions.
If this element is not present, the default is "Network Working Group",
which is used by the RFC Editor as a nod to the history of the IETF. -->
<keyword>SCIM</keyword>
<keyword>Search</keyword>
<!-- Keywords will be incorporated into HTML output
files in a meta tag but they have no effect on text or nroff
output. If you submit your draft to the RFC Editor, the
keywords will be used for the search engine. -->
<abstract>
<t>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:<list style="symbols">
<t>Specification of search terms within an HTTP POST verb to avoid
accidental leakage of confidential information via HTTP GET
URLs,</t>
<t>An optional result set token enabling clients to page through
results in a state consistent fashion, and</t>
<t>The ability to search across multiple resource types (endpoints)
and return one or more resource types.</t>
</list></t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>The SCIM Core API is an application-level, RESTful service for
provisioning and managing identity data on the web. The SCIM Core API
specification<xref target="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:<list style="symbols">
<t>the ability to query for one or more resources using a
filter,</t>
<t>the ability to search from any resource endpoint including the
server root,</t>
<t>the ability to support result sets which provide consistent
search results across multiple requests,</t>
<t>a POST Search profile which supports searching with parameters
not included in the URL, and</t>
<t>a token parameter which supports returning stateful paged
results.</t>
</list></t>
<t>[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]</t>
<t>[Note: this specification may be optionally combined with the SCIM
core API spec]</t>
<section title="Requirements Language">
<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"/>.</t>
<t>Note: For readability and space reasons, some included examples and
attribute values, and UUID identifiers are shortened.</t>
</section>
</section>
<section anchor="API" title="Search Extension">
<t>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 specific resource
scoped searches.</t>
<t>SCIM Extended Searches are defined (in <xref
target="RFC5234">ABNF</xref>) as follows:</t>
<figure align="center" anchor="searchEndpoints"
title="ABNF for SCIM Search Endpoints">
<artwork type="abnf">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</artwork>
</figure>
<t>[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)?]</t>
<t>Where:<list hangIndent="14" style="hanging">
<t hangText="scimSearch">Is a special path qualifier that indicates
the operation is related to a search. When used with HTTP GET,
scimSearch is OPTIONAL.</t>
<t hangText="authority, path-absolute, userinfo, host, port">Are
defined as per <xref target="RFC3986">URI Syntax ABNF</xref></t>
<t hangText="query">Is any SCIM query term as specified in section
3.2 of the SCIM Core API <xref target="I-D.ietf-scim-api"/>.</t>
<t hangText="scimVers">Is the SCIM Service Provider API version.</t>
<t hangText="scimResType">Is a SCIM resource type such as "Users",
"Groups" or any other schema extended resource supported by the
service provider.</t>
<t hangText="UUID">Identifies a unique SCIM resource or SCIM search
result that is retrievable from the SCIM Service Provider (see <xref
target="RFC4122"/>).</t>
</list></t>
<t anchor="exampleEndpoints">Example SCIM Search endpoints include:<list
counter="endpts" hangIndent="14" style="hanging">
<t hangText="http://example.com/scim/v2/.search"><vspace
blankLines="0"/> for server-wide searches</t>
<t hangText="http://example.com/scim/v2/Users/.search"><vspace
blankLines="0"/>for searches of User resources only</t>
<t hangText="http://example.com/scim/v2/Groups/.search"><vspace
blankLines="0"/>for searches of Group resources only</t>
<t
hangText="http://example.com/scim/v2/.search?searchId=607dac9b24a2;startIndex=20"><vspace
blankLines="0"/>to return results from a previously executed
query</t>
</list></t>
<t>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.</t>
<section title="Search Tokens">
<t>From the clients perspective, as with any HTTP is a stateless
protocol. When performing searches requiring several pages of results
to be returned, there is always the possibility to have inconsistent
results should the underlying data change between requests. SCIM
Service Providers MAY optionally maintain a stateful representation of
search results that may be accessed by the client using a token.</t>
<t>Once a search result "searchId" token has been created, a client
may peform GET requests using the parameter "searchId" and
"startIndex" to return additional result pages. Any other parameters
and path are IGNORED when "searchId" is present. The searchId token
allows the service provider to respond with consistent stateful
results, using pagination commands as defined in section 3.2.2.3 of
the SCIM Core API.</t>
<t>[Discussion: Can an existing search result be used in combination
with a new search or ordering request to sub-search within an existing
set of results? E.g. would it make sense to allow a PUT against an
existing search result?]</t>
</section>
<section title="Filter Processing Across Multiple Resource Types">
<t>When the SCIM Extended Search specification is supported,
Filtering, as defined in the SCIM Core API, section 3.2.2.1 is
REQUIRED.</t>
<t>When processing search operations across endpoints that MAY include
more than one SCIM resource type (e.g. a search from the server root
endpoint), filters MUST be processed in the same fashion as outlined
in 3.2.2.1 of the SCIM Core API. For filtered attributes that are not
part of a particular resource type, the service provider SHALL treat
the attribute as if there is no attribute value. For example, a
presence or equality filter for an undefined attribute evaluates as
FALSE.</t>
</section>
<section title="Search Request Using HTTP POST">
<t>To create a new search result set, clients send an HTTP POST
request to the desired SCIM resource endpoint (see <xref
target="searchEndpoints"/>). The body of the POST request MAY include
any of the parameters as defined in section 3.2 of the SCIM Core
API.</t>
<t>An additional parameter "stateful" MAY be set to "true" in order to
request stateful results from the server. Note that the presence of
this parameter DOES NOT require that the server produce a stateful
result set. Detection of stateful results is described in <xref
target="responseProcessing"/>.</t>
<t>After receiving a HTTP POST request, a response is returned as
specified in <xref target="searchResponse"/>.</t>
<figure align="left" alt="POST Example" anchor="POSTExample"
title="Example POST Search Request">
<preamble>The following example shows an HTTP POST Search request
with search parameters attributes, filter, and count
included:</preamble>
<artwork align="center" height="13">POST /.search
Host: example.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer h480djs93hd8
Content-Length: ...
{
"schemas": ["urn:scim:schemas:core:1.0"],
"attributes":["displayName","username"],
"filter":"displayName sw \"smith\"",
"stateful":"true",
"count":10
}</artwork>
</figure>
<t>[TBD - are there any cases for persistent searches?]</t>
<t>[TBD - should there be additional options to control where result
state is maintained, lifetime, etc. Controls wheter subsequent gets
cause re-queries or whether result set consistency is maintained for
the life of the result set]</t>
</section>
<section title="Search Request Using HTTP GET">
<t>When an HTTP GET request is made against a search endpoint (see
<xref target="searchEndpoints"/>) a new search result is created. The
parameters and arguments are as defined in section 3.2 of the SCIM
Core API.</t>
<t>An additional parameter "stateful" MAY be set to "true" in order to
request stateful results from the server. Note that the presence of
this parameter DOES NOT require that the server produce a stateful
result set. Detection of stateful results is described in <xref
target="responseProcessing"/>.</t>
<t>After receiving an HTTP GET request, a response is returned as
specified in <xref target="searchResponse"/>.</t>
<figure align="left" anchor="GETExample"
title="Example GET Search Request">
<preamble>The following example is the HTTP GET equivalent of the
example shown in <xref target="POSTExample"/>.</preamble>
<artwork align="center">GET /.search?attributes="displayName,username"
&filter=displayName sw "smith"&count=10&stateful="true"
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8</artwork>
</figure>
</section>
<section anchor="searchResponse" title="Search Response">
<section anchor="responseProcessing" title="Server Processing">
<t>If, on receiving a search request, only a single resource is
matched, the server SHALL respond with an HTTP status code of 200
and include the single JSON formatted search result in the body of
the response as specified in the SCIM Core API.</t>
<t>If multiple resources are to be returned in a single response,
the server SHALL respond with an HTTP status code of 200 and a body
containing an array of "Resources" in a JSON structure up to the
default server limit OR the number of records specified in SCIM
pagination parameter 'count'.</t>
<t>If more results are available than returned and the client
request included the parameter "stateful" whose value is "true",
Service Providers MAY support stateful paged results by returning an
HTTP status code of 201 and include an attribute "searchId"
specifying a token that MAY be used to obtain additional results in
a stateful manner.</t>
<t>If the client DID NOT specify "stateful" as "true", OR Servers
NOT supporting stateful results MUST return an HTTP status of 200
and a page of results as per the normal HTTP GET request of the SCIM
Core API.</t>
<t>[Is it more appropriate in token mode for status 200 to be
returned?]</t>
<t>Regardless of the number of resources returned or the search
endpoint, the server SHALL include the following meta attributes
with each resource JSON structure:<list hangIndent="14"
style="hanging">
<t hangText="location">the permenant location URI of the
returned object</t>
<t hangText="resourceType">a string (scimResType) representing
the type of resource returned (e.g. "User", "Group").</t>
</list></t>
<figure align="left" anchor="ExampleResponse"
title="Example POST Search Response">
<preamble>A search response is shown with the first page of
results. For brevity reasons, only two matches are shown: one User
and one Group. A status of 201 and a location header is returned
with the result set identifier indicating more results are
available in stateful representation. A subsequent GET to the
location allows multiple pages of results to be returned while
preserving the original result set using a search session
identifier. As described in section 3.2.2.3, the response includes
pagination response attributes: itemsPerPage, totalResults, and
startIndex.</preamble>
<artwork align="center">HTTP/1.1 201 Created
Content-Type: application/json
Location: https://example.com/.search
{
"totalResults":100,
"itemsPerPage":10,
"startIndex":1,
"searchId":"131dc0667e20"
"schemas":["urn:scim:schemas:core:1.0"],
"Resources":[
{
"meta":{
"location":
"https://example.com/Users/2819c223-7f76-413861904646",
"resourceType":"User",
"lastModified": ...
}
"username":"jsmith",
"displayName":"Smith, James"
},
{
"meta":{
"location":
"https://example.com/Groups/c8596b90-7539-4f20968d1908",
"resourceType":"Group",
"lastModified": ...
}
"displayName":"Smith Family"
},
...
]
} </artwork>
</figure>
<t>[Discuss: Instead of returning a location identifier for paging,
how about using a "token" for paging?]</t>
</section>
<section title="Client Processing">
<t>If the initial search response has status 201 and a "searchId"
attribute is present, SCIM clients MAY obtain additional page
results in a stateful fashion using the SCIM Core API "startIndex"
pagination parameter as described in the following <xref
target="statefulResults"/>. Alternatively, SCIM clients MAY ignore
the stateful results location, and request additional paged results
as per the normal SCIM Core API stateless functionality which causes
new results to be generated with each page request.</t>
</section>
</section>
<section anchor="statefulResults" title="Querying An Existing Result">
<t>A SCIM client MAY request additional results after an initial
search request has been returned with a status 201 and a "searchId"
token has been provided. The client requests additional pages by using
the "searchId" parameter which is set to the provided token value,
along with "startIndex" and "count" parameters.</t>
<t>SCIM clients SHOULD NOT expect that search results will be
maintained indefinitely and SHOULD request additional results in a
reasonable time frame.</t>
<figure align="left" anchor="ExamplePage"
title="Example Consistent Paged Result Set Query Request">
<preamble>In the code example below, a request is made to return
results starting with the 11th item in the result set identified by
the identifier 2a7229cc-d9dc-4153-131dc0667e20. The identifier is
used to ensure consistent results in the event the underlying data
has changed since the original query was posted.</preamble>
<artwork align="center">GET /v2/.search?startIndex=11&count=10
&searchId=2a7229cc-d9dc-4153-131dc0667e20
HOST: example.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer h480djs93hd8</artwork>
</figure>
<t>After all results have been returned, OR after a reasonable period,
the Service Provider MAY automatically delete the result set. A
subsequent attempt to retrieve results from a deleted result set SHALL
return an HTTP/1.1 404 NOT FOUND error.</t>
</section>
<section title="Abandoning Search Results">
<t>If a client decides not to retrieve all results in a stateful
search, a client SHOULD inform the Service Provider that it is
finished with a result set by issuing an HTTP DELETE with the searchId
token provided as a parameter to the endpoint where the original
search was requested. Upon receiving a DELETE request, the server
SHALL respond with status 200 (OK) if the search request was deleted
or status 404 (NOT FOUND) if the result has already been deleted or
otherwise expired.</t>
<figure align="left" anchor="ExampleCancel"
title="Cancelling Search Results Set">
<artwork align="center">DELETE /Users/.search?searchId=64b6efd7-6598-4dbc-ab3a-af38dad71493
Host: example.com
Authorization: Bearer h480djs93hd8
HTTP/1.1 200 OK</artwork>
</figure>
<t>Servers MAY choose to automatically expire search results after all
results have been returned or after a period of time in which no
additional requests have been received for the search result. Upon
automatically expiring a search result, any further request to return
a result or delete a result SHOULD return a status of 404 (NOT
FOUND).</t>
</section>
<section title="ServiceProviderConfig Discovery">
<t>[TBD]</t>
<t>ServiceProviderConfig will require a new set of "search" attributes
that indicate what is supported. For example:<list style="symbols">
<t>root search</t>
<t>post search</t>
<t>stateful paged search results</t>
</list></t>
</section>
</section>
<section anchor="Acknowledgements" title="Acknowledgements">
<t>[TBD]</t>
</section>
<!-- Possibly a 'Contributors' section ... -->
<section anchor="IANA" title="IANA Considerations">
<t>This memo includes no request to IANA.</t>
</section>
<section anchor="Security" title="Security Considerations">
<t>Implementers should consider that the creation of search results can
lead to depletion of server resources creating a vector for
denial-of-service attacks. Implementers and deploiyers should take
appropriate counter measures such as:<list style="symbols">
<t>limiting which clients may use extended search,</t>
<t>limiting the number of extended searches any client MAY execute
in a session or HTTP connection,</t>
<t>encourage clients to delete search results using the HTTP DELETE
command in order to free resources,</t>
<t>limiting the time a search result is retained, and</t>
<t>purging unused or expired search results.</t>
</list></t>
<t>[Others TBD]</t>
</section>
</middle>
<!-- *****BACK MATTER ***** -->
<back>
<!-- References split into informative and normative -->
<!-- There are 2 ways to insert reference entries from the citation libraries:
1. define an ENTITY at the top, and use "ampersand character"RFC2629; here (as shown)
2. simply use a PI "less than character"?rfc include="reference.RFC.2119.xml"?> here
(for I-Ds: include="reference.I-D.narten-iana-considerations-rfc2434bis.xml")
Both are cited textually in the same manner: by using xref elements.
If you use the PI option, xml2rfc will, by default, try to find included files in the same
directory as the including file. You can also define the XML_LIBRARY environment variable
with a value containing a set of directories to search. These can be either in the local
filing system or remote ones accessed by http (http://domain/dir/... ).-->
<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/bibxml3/reference.I-D.draft-ietf-scim-api-00.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-scim-core-schema-00.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml'?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.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.4122.xml'?>
&RFC2119;
</references>
<references title="Informative References">
<!-- Here we use entities that we defined at the beginning. -->
&I-D.narten-iana-considerations-rfc2434bis;
<!-- A reference written by by an organization not a person. -->
</references>
<!-- Change Log
v00 2006-03-15 EBD Initial version
v01 2006-04-03 EBD Moved PI location back to position 1 -
v3.1 of XMLmind is better with them at this location.
v02 2007-03-07 AH removed extraneous nested_list attribute,
other minor corrections
v03 2007-03-09 EBD Added comments on null IANA sections and fixed heading capitalization.
Modified comments around figure to reflect non-implementation of
figure indent control. Put in reference using anchor="DOMINATION".
Fixed up the date specification comments to reflect current truth.
v04 2007-03-09 AH Major changes: shortened discussion of PIs,
added discussion of rfc include.
v05 2007-03-10 EBD Added preamble to C program example to tell about ABNF and alternative
images. Removed meta-characters from comments (causes problems). -->
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 07:14:37 |