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, . 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