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]
