Internet DRAFT - draft-hunt-scim-xsearch
draft-hunt-scim-xsearch
Network Working Group P. Hunt, Ed.
Internet-Draft Oracle
Intended status: Standards Track K. Grizzle
Expires: June 26, 2013 Sailpoint
B. Annestad
UnboundID
M. Ansari
CISCO
D. Olds
VMWare
December 23, 2012
SCIM 2.0 Extended Search
draft-hunt-scim-xsearch-00
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 Extended 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 representation 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.
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."
Hunt, et al. Expires June 26, 2013 [Page 1]
Internet-Draft SCIM Extended Search December 2012
This Internet-Draft will expire on June 26, 2013.
Copyright Notice
Copyright (c) 2012 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
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Hunt, et al. Expires June 26, 2013 [Page 2]
Internet-Draft SCIM Extended Search December 2012
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4
2. Search Extension . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Search Operation Representation . . . . . . . . . . . . . 6
2.2. Filter Processing Across Multiple Resource Types . . . . . 7
2.3. Search Request Using HTTP POST . . . . . . . . . . . . . . 7
2.4. Search Request Using HTTP GET . . . . . . . . . . . . . . 8
2.5. Search Response . . . . . . . . . . . . . . . . . . . . . 9
2.5.1. Server Processing . . . . . . . . . . . . . . . . . . 9
2.5.2. Client Processing . . . . . . . . . . . . . . . . . . 11
2.6. Querying An Existing Result . . . . . . . . . . . . . . . 11
2.7. Abandon/Delete Search Results . . . . . . . . . . . . . . 11
2.8. ServiceProviderConfig Discovery . . . . . . . . . . . . . 12
3. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
5. Security Considerations . . . . . . . . . . . . . . . . . . . 12
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.1. Normative References . . . . . . . . . . . . . . . . . . . 13
6.2. Informative References . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14
Hunt, et al. Expires June 26, 2013 [Page 3]
Internet-Draft SCIM Extended Search December 2012
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 GET command which supports returning results in a paged result
set.
In order to provide the "extended search" features, this
specification defines a new SCIM resource representation known as a
"search". The "search" is a stateful representation of a search
request enabling the client to execute simple operations against the
request such as paging of results in a stateful manner. In addition,
by representing search as an object, the HTTP POST verb may be used
to initiate a search request without risking leakage of confidential
information such as filter term values in URLs.
[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.
Hunt, et al. Expires June 26, 2013 [Page 4]
Internet-Draft SCIM Extended Search December 2012
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
specific resource scoped searches.
SCIM Extended Searches are defined (in ABNF [RFC5234]) as follows:
SCIMSEARCH = scimEndpoint "/.search" ["/" 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.
Hunt, et al. Expires June 26, 2013 [Page 5]
Internet-Draft SCIM Extended Search December 2012
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:
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/a972cc80-4aaf-a89d-607dac9b24a2
to return results from a previously executed query
Extended 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 search result location if
stateful results are available.
2.1. Search Operation Representation
The SCIM Extended Search specification creates a new RESTful state
representation resource known as "search". A "search" resource is a
temporary resource maintained by the SCIM Service Provider
representing the results of a particular query received by a
"/.search" endpoint (see Figure 1). By creating and maintaining a
stateful representation for a period of time, a SCIM client may
reliably page through query results from a service provider in a
stateless fashion.
The search end-point supports the following HTTP command verbs:
GET When used with a "/.search" endpoint and an object
identifier (UUID), HTTP GET retrieves a page of
existing search results represented by a previous GET
or POST request.
When used with a "/.search" endpoint and no object
identifier, HTTP GET generates a new search with the
Hunt, et al. Expires June 26, 2013 [Page 6]
Internet-Draft SCIM Extended Search December 2012
same parameters and arguments as searches as defined in
section 3.2.2.3 of the SCIM Core API which generates a
new search result and returns an initial set of results
along with OPTIONAL location of the stateful search
result set if additional results are available and
stateful results are supported.
POST Enables a client to sent a query to the Service
Provider in JSON form which generates a new search
result and returns an initial set of results along with
OPTIONAL location of the stateful search result set if
additional results are available and stateful results
are supported.
DELETE MAY be used to pro-actively delete a search result set.
PUT and PATCH Not used.
Once a search result identifier has been created, a client may peform
GET requests against the result's location to return additional
result pages. The search resource representation responds to
pagination commands as defined in section 3.2.2.3 of the SCIM Core
API.
[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?]
2.2. Filter Processing Across Multiple Resource Types
When the SCIM Extended Search specification is supported, Filtering,
as defined in the SCIM Core API, section 3.2.2.1 is REQUIRED.
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.
2.3. Search Request Using HTTP POST
To create a new search result set, clients send an HTTP POST request
to the desired SCIM resource endpoint (see Figure 1). The body of
the POST request MAY include any of the parameters as defined in
Hunt, et al. Expires June 26, 2013 [Page 7]
Internet-Draft SCIM Extended Search December 2012
section 3.2 of the SCIM Core API.
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
Section 2.5.1.
After receiving a HTTP POST request, a response is returned as
specified in Section 2.5.
The following example shows an HTTP POST Search request with search
parameters attributes, filter, and count included:
HOST /.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
}
Figure 2: Example POST Search Request
[TBD - are there any cases for persistent searches?]
[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]
2.4. Search Request Using HTTP GET
When an HTTP GET request is made against a search endpoint (see
Figure 1) a new search result is created. The parameters and
arguments are as defined in section 3.2 of the SCIM Core API.
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
Section 2.5.1.
Hunt, et al. Expires June 26, 2013 [Page 8]
Internet-Draft SCIM Extended Search December 2012
After receiving an HTTP GET request, a response is returned as
specified in Section 2.5.
The following example is the HTTP GET equivalent of the example shown
in Figure 2.
GET /.search?attributes="displayName,username"
&filter=displayName sw "smith"&count=10
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8
Figure 3: Example GET Search Request
2.5. Search Response
2.5.1. Server Processing
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.
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'.
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.
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.
Regardless of the number of resources returned or the search
endpoint, the server SHALL include the following meta attributes with
each resource JSON structure:
location the permenant location URI of the returned object
Hunt, et al. Expires June 26, 2013 [Page 9]
Internet-Draft SCIM Extended Search December 2012
resourceType a string (scimResType) representing the type of
resource returned (e.g. "User", "Group").
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.
HTTP/1.1 201 Created
Content-Type: application/json
Location: https://example.com/.search/2a7229cc-d9dc-4153-131dc0667e20
{
"totalResults":100,
"itemsPerPage":10,
"startIndex":1,
"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"
},
...
]
}
Figure 4: Example POST Search Response
[Discuss: Instead of returning a location identifier for paging, how
about using a "token" for paging?]
Hunt, et al. Expires June 26, 2013 [Page 10]
Internet-Draft SCIM Extended Search December 2012
2.5.2. Client Processing
If the initial search response has status 201 and a Location header
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 Section 2.6. 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.
2.6. Querying An Existing Result
A SCIM client MAY request additional results after an initial search
request has been returned with a status 201 and an HTTP Location
header. The client requests additional pages by using the
'startIndex', and 'count' parameters.
SCIM clients SHOULD NOT expect that search results will be maintained
indefinitely and SHOULD request additional results in a reasonable
time frame.
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.
GET /v2/.search/2a7229cc-d9dc-4153-131dc0667e20
?startIndex=11&count=10
HOST: example.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer h480djs93hd8
Figure 5: Example Consistent Paged Result Set Query Request
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.
2.7. Abandon/Delete Search Results
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 to the location returned in
the original POST search response. Upon receiving a DELETE request,
the server SHALL respond with status 200 (OK) if the search request
Hunt, et al. Expires June 26, 2013 [Page 11]
Internet-Draft SCIM Extended Search December 2012
was deleted or status 404 (NOT FOUND) if the result has already been
deleted or otherwise expired.
DELETE /Users/.search/64b6efd7-4dbc-ab3a-af38dad71493
Host: example.com
Authorization: Bearer h480djs93hd8
HTTP/1.1 200 OK
Figure 6: Cancelling Search Results Set
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).
2.8. ServiceProviderConfig Discovery
[TBD]
ServiceProviderConfig will require a new set of "search" attributes
that indicate what is supported. For example:
o root search
o post search
o stateful paged search results
3. Acknowledgements
[TBD]
4. IANA Considerations
This memo includes no request to IANA.
5. Security Considerations
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:
Hunt, et al. Expires June 26, 2013 [Page 12]
Internet-Draft SCIM Extended Search December 2012
o limiting which clients may use extended search,
o limiting the number of extended searches any client MAY execute in
a session or HTTP connection,
o encourage clients to delete search results using the HTTP DELETE
command in order to free resources,
o limiting the time a search result is retained, and
o purging unused or expired search results.
[Others TBD]
6. References
6.1. Normative References
[I-D.ietf-scim-api]
Drake, T., Mortimore, C., Ansari, M., Grizzle, K., and E.
Wahlstroem, "System for Cross-Domain Identity Management:
Protocol", draft-ietf-scim-api-00 (work in progress),
August 2012.
[I-D.ietf-scim-core-schema]
Mortimore, C., Harding, P., Madsen, P., and T. Drake,
"System for Cross-Domain Identity Management: Core
Schema", draft-ietf-scim-core-schema-00 (work in
progress), August 2012.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
Unique IDentifier (UUID) URN Namespace", RFC 4122,
July 2005.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
Hunt, et al. Expires June 26, 2013 [Page 13]
Internet-Draft SCIM Extended Search December 2012
6.2. Informative References
[I-D.narten-iana-considerations-rfc2434bis]
Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", March 2008.
Authors' Addresses
Phil Hunt (editor)
Oracle
Email: phil.hunt@yahoo.com
Kelly Grizzle
Sailpoint
Bjorn Aannestad
UnboundID
Morteza Ansari
CISCO
Dale Olds
VMWare
Hunt, et al. Expires June 26, 2013 [Page 14]
