Network Working Group C. McMurtry
Internet Draft Microsoft
Intended status: Proposed Standard April 4, 2016
Expires: October 4, 2016
SCIM Polling Protocol
draft-mcmurtry-scim-polling-01.txt
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), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
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."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html
This Internet-Draft will expire on October 4, 2016.
Copyright Notice
Copyright (c) 2013 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.
McMurtry Expires October 4, 2016 [Page 1]
Internet-Draft SCIM Polling Protocol April 2016
Abstract
This document specifies a protocol by which a System for Cross-Domain
Identity Management Protocol (SCIM) client can poll a SCIM service
provider for the current states of resources that have changed since a
given point in time.
Table of Contents
1. Introduction...................................................2
1.1. Conventions used in this document.........................3
1.2. Definitions...............................................3
2. Polling for Changed Resources..................................3
2.1. Initializing the Change Watermark.........................3
2.2. Filtering the Current States of Resources by the
Change Watermark..........................................5
2.3. Filtering Changes to Resources by the Change Watermark....7
3. Security Considerations........................................8
4. IANA Considerations............................................8
5. References.....................................................9
5.1. Normative References......................................9
1. Introduction
The SCIM protocol [1] is an application-level, REST protocol by which
clients can send identity data to, and request identity data from a
service provider. This document supplements that protocol to permit a
client to query a service provider for any changes to the data that may
have occurred since the client was issued a watermark by the service
provider.
If a SCIM client's representation of some resources is to be kept in sync
with a SCIM service provider's representation of those resources, then one
solution would be for the client to poll the service provider for changes
to its representation of the resources. Another solution would be for the
client to subscribe to notifications of changes published by the service
provider. Because the former solution may be expected to result in
redundant polls, the latter solution may be preferred. However, absent a
tractable way of guaranteeing that any notification that should be
published by the service provider is successfully processed by the client,
the latter solution may not be practical.
McMurtry Expires October 4, 2016 [Page 2]
Internet-Draft SCIM Polling Protocol April 2016
A SCIM client could poll a service provider for changes by filtering
resources by the meta.lastModified attribute, as suggested by Section
3.4.2.2 of the SCIM protocol document [1]. However, that polling solution
does not permit the service provider to control the polling frequency, or
the client to request only attributes that were changed since a given
time.
1.1. Conventions used in this document
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 RFC 2119 [2].
1.2. Definitions
Change Watermark
A SCIM String, as defined in Section 2.3.1 of the SCIM Core Schema
Document [3].
2. Polling for Changed Resources
2.1. Initializing the Change Watermark
The example query below requests the current state of all resources:
GET /Changes
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
The following is an example response to the query above:
McMurtry Expires October 4, 2016 [Page 3]
Internet-Draft SCIM Polling Protocol April 2016
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas":[
"urn:ietf:params:scim:api:messages:2.0:ListResponse",
"urn:ietf:params:scim:schemas:extension:polling:1.0:Changed"],
"totalResults":2,
"changePollingInterval":"PT10M",
"changeWatermark":"8AB6AE592FAF4AEF86B1B73D606A92A7",
"changeWatermarkLifetime":"P1D",
"Resources":[
{
"id":"2819c223-7f76-453a-919d-413861904646",
"userName":"bjensen",
"schemas":[
"urn:ietf:params:scim:schemas:core:2.0:User"]
},
{
"id":"e9e30dba-f08f-4109-8486-d5c6a331660a",
"displayName":"Tour Guides",
"schemas":[
"urn:ietf:params:scim:schemas:core:2.0:Group"]
}
]
}
The list response resource includes the attribute, "changeWatermark,"
which is an extension to the core schema of the resource, in accordance
with Section 3.2 of the SCIM Core Schema Document [3]. The URI
of the schema extension is
"urn:ietf:params:scim:schemas:extension:polling:1.0:Changed". The
variety of types of resources included in the response SHOULD include all
of the types of resources that the service provider supports.
Pagination parameters can be used as specified by Section 3.4.2.4 of the
SCIM Protocol document [1]. A value for the "changeWatermark" attribute
MUST be given on the last page of results, and MUST NOT be given on any
other page.
When the "changeWatermark" attribute is included in a response, the
"changePollingInterval" and "changeWatermarkLifetime" attributes MAY be
included as well. The values of those attributes are durations in the
ISO 8601 format.
McMurtry Expires October 4, 2016 [Page 4]
Internet-Draft SCIM Polling Protocol April 2016
Both the service provider and the client must support the
urn:ietf:params:scim:schemas:extension:polling:1.0:Changed schema
extension if the client is to be able to poll the service provider for
changed resources. The reason is that no attribute included in the the
SCIM Core Schema Document [3] is suitable for a service provider to use
to convey to a client a value, relative to which the client would
late be able to query the service provider for subsequent changes.
If a value of the "changePollingInterval" is included in the response,
then the client SHOULD NOT attempt to filter resources by the change
watermark as described in Section 2.2 below, until the duration specified
by the value of the "changePollingInterval" has elapsed. If the client
attempts to filter resources by the change watermark before the duration
specified by the value of the "changePollingInterval" has elapsed then
the service provider MAY reject the filtering request endpoint by
returning an HTTP response with HTTP status code 429 (Too Many Requests).
If a value of the "changeWatermarkLifetime" is included in the response,
then the client SHOULD attempt to filter resources by the change
watermark as described in Section 2.2 below, before the duration
specified by the value of the "changeWatermarkLifetime" has elapsed. If
the client attempts to filter resources by the change watermark after
the duration specified by the value of the "changeWatermarkLifetime" has
elapsed then the service provider MAY respond as it would if did not
recognize the change watermark as described in Section 2.2 below.
The client MAY control which attributes SHALL be included with returned
resources by using the OPTIONAL parameters provided by Section 3.4.2.5 of
the SCIM Protocol document [1]. That document states that those
parameters MUST be supported by SCIM service providers.
If the attributes to be included with returned resources are not specified
by the client, then the returned resources MUST include the id attribute
defined in Section 3.1 of the SCIM Core Schema Document [3] and SHOULD
include all of the attributes of those resources.
If the service provider does not support polling for changes, then the
service provider SHALL reject any request to the Changes endpoint by
returning an HTTP response with HTTP status code 404 (Not Found).
2.2. Filtering the Current States of Resources by the Change Watermark
The example query below requests the current state of all resources that
have been changed since the change watermark supplied in the filter was
issued:
McMurtry Expires October 4, 2016 [Page 5]
Internet-Draft SCIM Polling Protocol April 2016
GET /Changes?filter=changeWatermark eq "8AB6AE592FAF4AEF86B1B73D606A92A7"
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
The following is an example response to the query above, signifying that
one resource has been added or changed since the change watermark was
issued:
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas":[
"urn:ietf:params:scim:api:messages:2.0:ListResponse",
"urn:ietf:params:scim:schemas:extension:polling:1.0:Changed"],
"totalResults":1,
"changePollingInterval":"PT10M",
"changeWatermark":"ABDA5F9F5B284A198C8D571A706205A1",
"changeWatermarkLifetime":"P1D",
"Resources":[
{
"id":"e9e30dba-f08f-4109-8486-d5c6a331660a",
"displayName":"Local Tour Guides",
"schemas":[
"urn:ietf:params:scim:schemas:core:2.0:Group"]
}
]
}
Here is an example response to the same query above, signifying that no
resources have been changed since the watermark was issued:
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas":[
"urn:ietf:params:scim:api:messages:2.0:ListResponse",
"urn:ietf:params:scim:schemas:extension:polling:1.0:Changed"],
"totalResults":0,
"changePollingInterval":"PT10M",
"changeWatermark":"ABDA5F9F5B284A198C8D571A706205A1",
"changeWatermarkLifetime":"P1D",
"Resources":[
]
}
McMurtry Expires October 4, 2016 [Page 6]
Internet-Draft SCIM Polling Protocol April 2016
If the service provider does not recognize the value of a change watermark
in a query filter then the response from the server SHALL include an
empty value for the "changeWatermark" attribute and an empty array as the
value for the "Resources" attribute. A client receiving that response MAY
proceed to initialize a new change watermark as described in Section 2.1
above. The following is an example of such a response:
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas":[
"urn:ietf:params:scim:api:messages:2.0:ListResponse",
"urn:ietf:params:scim:schemas:extension:polling:1.0:Changed"],
"totalResults":0,
"changeWatermark":"",
"Resources":[
]
}
The client MAY control which attributes SHALL be included with returned
resources by using the OPTIONAL parameters provided by Section 3.4.2.5 of
the SCIM Protocol document [1]. That document states that those
parameters MUST be supported by SCIM service providers.
If the attributes to be included with returned resources are not specified
by the client, then the returned resources MUST include the id attribute
defined in Section 3.1 of the SCIM Core Schema Document [3] and SHOULD
include all of the attributes of those resources.
2.3. Filtering Changes to Resources by the Change Watermark
The example query below requests the current state of all resources that
have been changed since the change watermark supplied in the filter was
issued, and that, in addition to the id attribute, which MUST be included,
only those attributes of which the values have changed since the change
watermark was issued MUST be included with any returned resources:
GET /Changes?filter=changeWatermark eq "8AB6AE592FAF4AEF86B1B73D606A92A7"
and changeDelta eq true
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
If the service provider does not support the changeDelta parameter then
then the service provider SHALL reject any request with that parameter
by returning an HTTP response with HTTP status code 501 (Not Implemented).
McMurtry Expires October 4, 2016 [Page 7]
Internet-Draft SCIM Polling Protocol April 2016
The client MAY further control which attributes SHALL be included with
returned resources by using the OPTIONAL parameters provided by Section
3.4.2.5 of the SCIM Protocol document [1]. That document states that
those parameters MUST be supported by SCIM service providers.
If the attributes to be included with returned resources are not specified
by the client, then the returned resources MUST include the id attribute
defined in Section 3.1 of the SCIM Core Schema Document [3], MUST include
all of the attributes of those resources of which the values have changed
since the change watermark supplied in the request filter was issued and
MUST NOT include any other attributes.
The example query below requests that, for all resources that have
changed since the change watermark supplied in the filter was issued, the
id, userName and externalId attributes MUST be included, the members
attribute must be excluded and any other attributes of which the values
have changed since the change watermark was issued MUST be included:
GET /Changes?filter=changeWatermark eq "8AB6AE592FAF4AEF86B1B73D606A92A7"
and changeDelta eq true&attributes=userName,externalId&
excludedAttributes=members
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
3. Security Considerations
Interactions between SCIM clients and the service providers may contain
personally identifiable information. This document does not provide any
means or guarantee of confidentiality of information passed back in the
service providers' responses. Implementers should refer to section 7.2
of the SCIM Protocol document [1], which specifies that SCIM clients and
service providers MUST require the use of a transport-layer security
mechanism when communicating with SCIM service providers.
4. IANA Considerations
There are no IANA considerations in this document.
McMurtry Expires October 4, 2016 [Page 8]
Internet-Draft SCIM Polling Protocol April 2016
5. References
5.1. Normative References
[1] Drake, T., Mortimore, C., Ansari, M., Grizzle, K., Wahlstroem,
E., "System for Cross-Domain Identity Management:Protocol",
draft-ietf-scim-api-00, August 2012.
[2] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[3] Mortimore, C., Harding, P., Madsen, P., Drake, T., "System for
Cross-Domain Identity Management:Core Schema", draft-ietf-scim-
core-schema-00, August 2012.
[4] International Organization for Standardization, "Data elements and
interchange formats - Information interchange - Representation of
dates and times ", ISO 8601:2004, December 2014, <http://www.iso.org>.
Authors' Addresses
Craig McMurtry
Microsoft Corporation
1 Microsoft Way
Redmond WA 98052 USA
Email: craigmcm@microsoft.com
McMurtry Expires October 4, 2016 [Page 9]
Internet-Draft SCIM Polling Protocol April 2016
McMurtry Expires October 4, 2016 [Page 8]
Internet-Draft SCIM Polling Protocol April 2016