--- 1/draft-ietf-scim-api-09.txt 2014-09-01 14:14:41.376556454 -0700 +++ 2/draft-ietf-scim-api-10.txt 2014-09-01 14:14:41.500559472 -0700 @@ -1,58 +1,57 @@ Network Working Group P. Hunt, Ed. Internet-Draft Oracle Intended status: Standards Track K. Grizzle -Expires: February 13, 2015 SailPoint +Expires: March 5, 2015 SailPoint M. Ansari Cisco E. Wahlstroem Nexus Technology C. Mortimore Salesforce - August 12, 2014 + September 1, 2014 - System for Cross-Domain Identity Management:Protocol - draft-ietf-scim-api-09 + System for Cross-Domain Identity Management 0;,Protocol + draft-ietf-scim-api-10 Abstract The System for Cross-Domain Identity Management (SCIM) specification - is designed to make managing user identity in multi-domain based - applications and services easier using HTTP Protocol. Examples - include but are not limited to enterprise to cloud service providers, - and inter-cloud based scenarios. The specification suite seeks to - build upon experience with existing schemas and deployments, placing - specific emphasis on simplicity of development and integration, while - applying existing authentication, authorization, and privacy models. - It's intent is to reduce the cost and complexity of user management - operations by providing a common user schema and extension model, as - well as binding documents to provide patterns for exchanging this - schema using standard protocols. In essence, make it fast, cheap, - and easy to move users in to, out of, and around the cloud. + is an HTTP based protocol that makes managing identities in multi- + domain scenarios easier to support through a standardized services. + Examples include but are not limited to enterprise to cloud service + providers, and inter-cloud based scenarios. The specification suite + seeks to build upon experience with existing schemas and deployments, + placing specific emphasis on simplicity of development and + integration, while applying existing authentication, authorization, + and privacy models. SCIM's intent is to reduce the cost and + complexity of user management operations by providing a common user + schema and extension model and a service protocol defined by this + document. 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 February 13, 2015. + This Internet-Draft will expire on March 5, 2015. Copyright Notice Copyright (c) 2014 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 @@ -62,155 +61,170 @@ the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 2. Authentication and Authorization . . . . . . . . . . . . . . 4 - 3. SCIM Protocol . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3. SCIM Protocol . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 6 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 8 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 8 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 8 - 3.2.2. Query Resources . . . . . . . . . . . . . . . . . . . 9 + 3.2.2. Query Resources . . . . . . . . . . . . . . . . . . . 10 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 20 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 23 3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 24 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 26 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 39 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 40 - 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 55 - 3.7. Additional Operation Response Parameters . . . . . . . . 56 - 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 57 + 3.5.1. Circular Reference Processing . . . . . . . . . . . . 42 + 3.5.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 46 + 3.5.3. Response and Error Handling . . . . . . . . . . . . . 49 + 3.5.4. Maximum Operations . . . . . . . . . . . . . . . . . 55 + 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 56 + 3.7. Additional Operation Response Parameters . . . . . . . . 57 + 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 58 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 58 - 3.10. HTTP Status and Error Response Handling . . . . . . . . . 58 - 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 62 - 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 62 - 4. Preparation and Comparison of Internationalized Strings . . . 64 - 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 64 - 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 65 + 3.10. HTTP Status and Error Response Handling . . . . . . . . . 59 + 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 63 + 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 63 + 4. Preparation and Comparison of Internationalized Strings . . . 65 + 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 65 + 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 66 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 66 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 66 - 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 66 - 6.2. Disclosure of Sensitive Information in URIs . . . . . . . 66 - 6.3. HTTP Considerations . . . . . . . . . . . . . . . . . . . 67 - 6.4. Secure Storage and Handling of Sensitive Data . . . . . . 67 - 6.5. Case Insensitive Comparision & International Languages . 68 - 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 68 - 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 68 - 7.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 69 - 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 70 - 8.1. Normative References . . . . . . . . . . . . . . . . . . 70 - 8.2. Informative References . . . . . . . . . . . . . . . . . 71 - Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 72 - Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 72 - Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 72 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 75 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 67 + 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 67 + 6.2. Disclosure of Sensitive Information in URIs . . . . . . . 67 + 6.3. HTTP Considerations . . . . . . . . . . . . . . . . . . . 68 + 6.4. Secure Storage and Handling of Sensitive Data . . . . . . 68 + 6.5. Case Insensitive Comparision & International Languages . 69 + 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69 + 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 69 + 7.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 70 + 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 71 + 8.1. Normative References . . . . . . . . . . . . . . . . . . 71 + 8.2. Informative References . . . . . . . . . . . . . . . . . 72 + Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 73 + Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 73 + Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 73 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 76 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. 1.1. Intended Audience - This document is intended as a guide to SCIM API usage for both SCIM - HTTP service providers and HTTP clients that may provision + 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 + Implementers MUST percent encode URLs as described in Section 2.1 of [RFC3986]. 1.3. Definitions - Base URI: The SCIM HTTP protocol is described in terms of a path - relative to a Base URI. The Base URI MUST NOT contain a query - string as clients may append additional path information and query - parameters as part of forming the request. Example: + Base URI + The SCIM HTTP protocol is described in terms of a path relative to + a Base URI. The Base URI MUST NOT contain a query string as + clients may append additional path information and query + parameters as part of forming the request. The base URI most + often is a URL which most often consists of the "https" protocol + scheme, a domain name and some initial path [RFC3986]. Example: "https://example.com/scim/" For readability, all examples in this document are expressed - assuming the SCIM service root and the server root are the same. - It is expected that SCIM servers may be deployed using any URI - prefix. For example, a SCIM server might be have a prefix of - "https://example.com/", or "https://example.com/scim/ - tenancypath/". Additionally client may also apply a version - number to the server root prefix (see Section 3.11 ). + assuming the SCIM service root and the server root are the same + (no path pre-fix). It is expected that SCIM servers may be + deployed using any URI path prefix. For example, a SCIM server + might be have a prefix of "https://example.com/", or + "https://example.com/scim/tenancypath/". Additionally client may + also apply a version number to the server root prefix (see + Section 3.11 ). 2. Authentication and Authorization - Because SCIM builds on the HTTP protocol, it does not define a scheme - for authentication and authorization. SCIM depends on standard HTTP - authentication schemes. Implementers SHOULD support existing - authentication/authorization schemes. In particular, OAuth2 + Because SCIM builds on the HTTP protocol, it does not itself define a + scheme for authentication and authorization. SCIM depends on + standard HTTP authentication schemes. Implementers SHOULD support + existing authentication/authorization schemes. In particular, OAuth2 [RFC6750] is RECOMMENDED. Appropriate security considerations of the selected authentication and authorization schemes SHOULD be taken. Because this protocol uses HTTP response status codes as the primary means of reporting the result of a request, servers are advised to respond to unauthorized or unauthenticated requests using the 401 response code in accordance with Section 3.1 of [RFC7235]. All examples show an OAuth2 bearer token [RFC6750] (though it is not required) ; e.g., GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 Host: example.com Authorization: Bearer h480djs93hd8 - The context of the request (i.e. the user for whom data is being - requested) MUST be inferred by service providers. + When processing requests, the service provider SHOULD consider the + subject performing the request and whether the action is appropriate + given the subject and the resource affected by the request. The + subject performing the request is usually determined from the + "Authorization" header present in the request. 3. SCIM Protocol - The SCIM protocol specifies well known endpoints and HTTP methods for + The SCIM protocol specifies well-known endpoints and HTTP methods for managing resources defined in the core schema; i.e., "User" and "Group" resources correspond to "/Users" and "/Groups" respectively. Service providers that support extended resources SHOULD define - resource endpoints using the established convention; pluralize the - resource name defined in the extended schema by appending an 's'. - Given there are cases where resource pluralization is ambiguous; - e.g., a resource named "Person" is legitimately "Persons" and - "People" clients SHOULD discover resource endpoints via the - "/ResourceTypes" endpoint. + resource endpoints using the convention of pluralizing the resource + name defined in the extended schema by appending an 's'. Given there + are cases where resource pluralization is ambiguous; e.g., a resource + named "Person" is legitimately "Persons" and "People". Clients + SHOULD discover resource endpoints via the "/ResourceTypes" endpoint. - GET Retrieves one or more complete or partial resources. + GET + Retrieves one or more complete or partial resources. - POST Depending on the endpoint, creates new resources, create a - search request, or may be used to bulk modify resources. + POST + Depending on the endpoint, creates new resources, create a search + request, or may be used to bulk modify resources. - PUT Modifies a resource by replacing existing attributes with a + PUT + Modifies a resource by replacing existing attributes with a specified set of replacement attributes (replace). PUT MUST NOT be used to create new resources. - PATCH Modifies a resource with a set of client specified changes + PATCH + Modifies a resource with a set of client specified changes (partial update). - DELETE Deletes a resource. + DELETE + Deletes a resource. Resource Endpoint Operations Description -------- ---------------- ---------------------- -------------------- User /Users GET (Section 3.2.1), Retrieve, Add, POST (Section 3.1), Modify Users PUT (Section 3.3.1), PATCH (Section 3.3.2), DELETE (Section 3.4) Group /Groups GET (Section 3.2.1), Retrieve, Add, POST (Section 3.1), Modify Groups @@ -1426,21 +1439,21 @@ "path":"members", "value": [ { "display": "James Smith", "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", "value": "08e1d05d...473d93df9210" } ] } ] -] +} The following example shows how to replace all the members of a group with a different members list. Some text removed for readabilty ("..."): PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" @@ -1459,30 +1472,30 @@ "$ref": "https://example.com/v2/Users/2819c223...413861904646", "value": "2819c223-7f76-453a-919d-413861904646" }, { "display": "James Smith", "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", "value": "08e1d05d-121c-4561-8b96-473d93df9210" }] } ] - ] + } 3.3.2.3. Replace Operation The "replace" operation replaces the value at the target location specified by the "path". The operation performs the following functions depending on the target location specified by "path" : o If the "path" parameter is omitted, the target is assumed to be - the resoruce itself. In this case, the "value" attribute SHALL + the resource itself. In this case, the "value" attribute SHALL contain a list of one or more attributes that are to be replaced. o If the target location is a single-value attribute, the attributes value is replaced. o If the target location is a multi-valued attribute and no filter is specified, the attribute and all values are replaced. o If the target location specifies a complex attribute, a set of sub-attributes SHALL be specified in the "value" parameter which @@ -1665,31 +1678,33 @@ "urn:ietf:params:scim:api:messages:2.0:BulkRequest". Bulk responses are identified using the following URI: "urn:ietf:params:scim:api:messages:2.0:BulkResponse". Bulk requests and bulk responses share many attributes. Unless otherwise specified, each attribute below is present in both bulk requests and bulk responses. The following Singular Attribute is defined in addition to the common attributes defined in SCIM core schema. - failOnErrors An Integer specifying the number of errors that the - service provider will accept before the operation is terminated - and an error response is returned. OPTIONAL in a request. Not - valid in a response. + failOnErrors + An Integer specifying the number of errors that the service + provider will accept before the operation is terminated and an + error response is returned. OPTIONAL in a request. Not valid in + a response. The following Complex Multi-valued Attribute is defined in addition to the common attributes defined in core schema. - Operations Defines operations within a bulk job. Each operation - corresponds to a single HTTP request against a resource endpoint. - REQUIRED. + Operations + Defines operations within a bulk job. Each operation corresponds + to a single HTTP request against a resource endpoint. REQUIRED. + Operations has the following sub-attributes: method The HTTP method of the current operation. Possible values are POST, PUT, PATCH or DELETE. REQUIRED. bulkId The transient identifier of a newly created resource, unique within a bulk request and created by the client. The bulkId serves as a surrogate resource id enabling clients to uniquely identify newly created resources in the Response and cross reference new resources in and across operations within a bulk request. REQUIRED when method is POST. @@ -1726,34 +1741,270 @@ returned. The service provider MUST continue performing as many changes as possible and disregard partial failures. The client MAY override this behavior by specifying a value for the "failOnErrors" attribute. The failOnErrors attribute defines the number of errors that the service provider should accept before failing the remaining operations returning the response. To be able to reference a newly created resource the attribute bulkId - MUST be specified when creating new resources. The bulkId is defined - by the client as a surrogate identifier in a POST operation. The - service provider MUST return the same bulkId together with the newly - created resource. The bulkId can then be used by the client to map - the service provider id with the bulkId of the created resource. + MUST be specified when creating new resources. The "bulkId" is + defined by the client as a surrogate identifier in a POST operation + (see Section 3.5.2). The service provider MUST return the same + "bulkId" together with the newly created resource. The "bulkId" can + then be used by the client to map the service provider id with the + "bulkId" of the created resource. A SCIM service provider MAY elect to optimize a sequence operations received (e.g. to improve processing performance). When doing so, the service provider MUST ensure the clients intent is preserved and the same stateful result is achieved as for non-optimized processing. For example, before a "User" can be added to a "Group", they must first be created. Processing these requests out of order, might result in a failure to add the new "User" to the "Group". +3.5.1. Circular Reference Processing + + The service provider MUST try to resolve circular cross references + between resources in a single bulk job but MAY stop after a failed + attempt and instead return the status code 409 Conflict. The + following example exhibits the potential conflict. + + POST /v2/Bulk + Host: example.com + Accept: application/scim+json + Content-Type: application/scim+json + Authorization: Bearer h480djs93hd8 + Content-Length: ... + + { + "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], + "Operations": [ + { + "method": "POST", + "path": "/Groups", + "bulkId": "qwerty", + "data": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + "displayName": "Group A", + "members": [ + { + "type": "Group", + "value": "bulkId:ytrewq" + } + ] + } + }, + { + "method": "POST", + "path": "/Groups", + "bulkId": "ytrewq", + "data": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + "displayName": "Group B", + "members": [ + { + "type": "Group", + "value": "bulkId:qwerty" + } + ] + } + } + ] + } + + If the service provider resolved the above circular references the + following is returned from a subsequent GET request. + + GET /v2/Groups?filter=displayName sw 'Group' + Host: example.com + Accept: application/scim+json + Authorization: Bearer h480djs93hd8 + +HTTP/1.1 200 OK +Content-Type: application/scim+json + +{ + "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], + "totalResults": 2, + "Resources": [ + { + "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + "displayName": "Group A", + "meta": { + "resourceType": "Group", + "created": "2011-08-01T18:29:49.793Z", + "lastModified": "2011-08-01T18:29:51.135Z", + "location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", + "version": "W\/\"mvwNGaxB5SDq074p\"" + }, + "members": [ + { + "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", + "$ref": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", + "type": "Group" + } + ] + }, + { + "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + "displayName": "Group B", + "meta": { + "resourceType": "Group", + "created": "2011-08-01T18:29:50.873Z", + "lastModified": "2011-08-01T18:29:50.873Z", + "location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", + "version": "W\/\"wGB85s2QJMjiNnuI\"" + }, + "members": [ + { + "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", + "$ref": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", + "type": "Group" + } + ] + } + ] +} +3.5.2. BulkdId Temporary Identifiers + + The client can, within one bulk operation, create a new "User", a new + "Group" and add the newly created "User" to the newly created + "Group". In order to add the new "User" to the "Group" the client + must use the surrogate id attribute, "bulkId", to reference the User. + The "bulkId" attribute value must be pre-pended with the literal + "bulkId:"; e.g., if the bulkId is 'qwerty', the value is + "bulkId:qwerty". The service provider MUST replace the string + "bulkId:qwerty" with the permanent resource id once created. + + The following example creates a User with the "userName" 'Alice' and + a "Group" with the "displayName" 'Tour Guides' with Alice as a + member. + + POST /v2/Bulk + Host: example.com + Accept: application/scim+json + Content-Type: application/scim+json + Authorization: Bearer h480djs93hd8 + Content-Length: ... + + { + "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], + "Operations": [ + { + "method": "POST", + "path": "/Users", + "bulkId": "qwerty", + "data": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "Alice" + } + }, + { + "method": "POST", + "path": "/Groups", + "bulkId": "ytrewq", + "data": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + "displayName": "Tour Guides", + "members": [ + { + "type": "User", + "value": "bulkId:qwerty" + } + ] + } + } + ] + } + + The service provider returns the following response: + + A subsequent GET request for the 'Tour Guides' Group ('e9e30dba-f08f- + 4109-8486-d5c6a331660a') returns the following: + +HTTP/1.1 200 OK +Content-Type: application/scim+json +Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a +ETag: W/"lha5bbazU3fNvfe5" + +{ + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", + "displayName": "Tour Guides", + "meta": { + "resourceType": "Group", + "created": "2011-08-01T18:29:49.793Z", + "lastModified": "2011-08-01T20:31:02.315Z", + "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", + "version": "W\/\"lha5bbazU3fNvfe5\"" + }, + "members": [ + { + "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", + "$ref": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", + "type": "User" + } + ] +} + + Extensions that include references to other resources MUST be handled + in the same way by the service provider. The following example uses + the bulkId attribute within the enterprise extension managerId + attribute. + + POST /v2/Bulk + Host: example.com + Accept: application/scim+json + Content-Type: application/scim+json + Authorization: Bearer h480djs93hd8 + Content-Length: ... + + { + "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], + "Operations": [ + { + "method": "POST", + "path": "/Users", + "bulkId": "qwerty", + "data": { + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "Alice" + } + }, + { + "method": "POST", + "path": "/Users", + "bulkId": "ytrewq", + "data": { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User", + "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" + ], + "userName": "Bob", + "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { + "employeeNumber": "11250", + "manager": { + "managerId": "batchId:qwerty", + "displayName": "Alice" + } + } + } + } + ] + } + +3.5.3. Response and Error Handling + The service provider response MUST include the result of all processed operations. A "location" attribute that includes the resource's endpoint MUST be returned for all operations excluding failed POSTs. The status attribute includes information about the success or failure of one operation within the bulk job. The attribute status MUST include the code attribute that holds the HTTP response code that would have been returned if a single HTTP request would have been used. If an error occurred the status MUST also include the description attribute containing a human readable explanation of the error. @@ -1764,21 +2015,21 @@ "status": "400", "response":{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "scimType":"invalidSyntax" "detail":"Request is unparseable, syntactically incorrect, or violates schema.", "status":"400" } The following example shows how to add, update, and remove a user. - The failOnErrors attribute is set to '1' indicating the service + The "failOnErrors" attribute is set to '1' indicating the service provider should return on the first error. The POST operation's bulkId value is set to 'qwerty' enabling the client to match the new User with the returned resource id '92b725cd-9465-4e7d- 8c16-01f8e146b87a'. POST /v2/Bulk Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 @@ -1885,21 +2136,21 @@ "response":{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "scimType":"invalidSyntax" "detail":"Request is unparseable, syntactically incorrect, or violates schema.", "status":"400" } } ] } - If the failOnErrors attribute is not specified or the service + If the "failOnErrors" attribute is not specified or the service provider has not reached the error limit defined by the client the service provider will continue to process all operations. The following is an example in which all operations failed. HTTP/1.1 200 OK Content-Type: application/scim+json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], "Operations": [ @@ -1939,72 +2190,20 @@ "method": "DELETE", "status": "404", "response":{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "detail":"Resource does not exist.", "status":"404" } } ] } - - The client can, within one bulk operation, create a new User, a new - Group and add the newly created User to the newly created Group. In - order to add the new User to the Group the client must use the - surrogate id attribute, bulkId, to reference the User. The bulkId - attribute value must be pre-pended with the literal "bulkId:"; e.g., - if the bulkId is 'qwerty' the value is "bulkId:qwerty". The service - provider MUST replace the string "bulkId:qwerty" with the permanent - resource id once created. - - The following example creates a User with the userName 'Alice' and a - Group with the displayName 'Tour Guides' with Alice as a member. - - POST /v2/Bulk - Host: example.com - Accept: application/scim+json - Content-Type: application/scim+json - Authorization: Bearer h480djs93hd8 - Content-Length: ... - - { - "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], - "Operations": [ - { - "method": "POST", - "path": "/Users", - "bulkId": "qwerty", - "data": { - "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], - "userName": "Alice" - } - }, - { - "method": "POST", - "path": "/Groups", - "bulkId": "ytrewq", - "data": { - "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], - "displayName": "Tour Guides", - "members": [ - { - "type": "User", - "value": "bulkId:qwerty" - } - ] - } - } - ] - } - - The service provider returns the following response. - HTTP/1.1 200 OK Content-Type: application/scim+json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], "Operations": [ { "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", "method": "POST", "bulkId": "qwerty", @@ -2014,202 +2213,22 @@ { "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", "method": "POST", "bulkId": "ytrewq", "version": "W\/\"lha5bbazU3fNvfe5\"", "status": "201" } ] } - A subsequent request for the 'Tour Guides' Group ('e9e30dba-f08f- - 4109-8486-d5c6a331660a') returns the following: - - GET /v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a - Host: example.com - Accept: application/scim+json - Authorization: Bearer h480djs93hd8 - -HTTP/1.1 200 OK -Content-Type: application/scim+json -Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a -ETag: W/"lha5bbazU3fNvfe5" - -{ - "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], - "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", - "displayName": "Tour Guides", - "meta": { - "resourceType": "Group", - "created": "2011-08-01T18:29:49.793Z", - "lastModified": "2011-08-01T20:31:02.315Z", - "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", - "version": "W\/\"lha5bbazU3fNvfe5\"" - }, - "members": [ - { - "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", - "$ref": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", - "type": "User" - } - ] -} - - Extensions that include references to other resources MUST be handled - in the same way by the service provider. The following example uses - the bulkId attribute within the enterprise extension managerId - attribute. - - POST /v2/Bulk - Host: example.com - Accept: application/scim+json - Content-Type: application/scim+json - Authorization: Bearer h480djs93hd8 - Content-Length: ... - - { - "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], - "Operations": [ - { - "method": "POST", - "path": "/Users", - "bulkId": "qwerty", - "data": { - "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], - "userName": "Alice" - } - }, - { - "method": "POST", - "path": "/Users", - "bulkId": "ytrewq", - "data": { - "schemas": [ - "urn:ietf:params:scim:schemas:core:2.0:User", - "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" - ], - "userName": "Bob", - "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { - "employeeNumber": "11250", - "manager": { - "managerId": "batchId:qwerty", - "displayName": "Alice" - } - } - } - } - ] - } - - The service provider MUST try to resolve circular cross references - between resources in a single bulk job but MAY stop after a failed - attempt and instead return the status code 409 Conflict. The - following example exhibits the potential conflict. - - POST /v2/Bulk - Host: example.com - Accept: application/scim+json - Content-Type: application/scim+json - Authorization: Bearer h480djs93hd8 - Content-Length: ... - - { - "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], - "Operations": [ - { - "method": "POST", - "path": "/Groups", - "bulkId": "qwerty", - "data": { - "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], - "displayName": "Group A", - "members": [ - { - "type": "Group", - "value": "bulkId:ytrewq" - } - ] - } - }, - { - "method": "POST", - "path": "/Groups", - "bulkId": "ytrewq", - "data": { - "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], - "displayName": "Group B", - "members": [ - { - "type": "Group", - "value": "bulkId:qwerty" - } - ] - } - } - ] - } - - If the service provider resolved the above circular references the - following is returned from a subsequent GET request. - - GET /v2/Groups?filter=displayName sw 'Group' - Host: example.com - Accept: application/scim+json - Authorization: Bearer h480djs93hd8 - -HTTP/1.1 200 OK -Content-Type: application/scim+json +3.5.4. Maximum Operations -{ - "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], - "totalResults": 2, - "Resources": [ - { - "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", - "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], - "displayName": "Group A", - "meta": { - "resourceType": "Group", - "created": "2011-08-01T18:29:49.793Z", - "lastModified": "2011-08-01T18:29:51.135Z", - "location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", - "version": "W\/\"mvwNGaxB5SDq074p\"" - }, - "members": [ - { - "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", - "$ref": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", - "type": "Group" - } - ] - }, - { - "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", - "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], - "displayName": "Group B", - "meta": { - "resourceType": "Group", - "created": "2011-08-01T18:29:50.873Z", - "lastModified": "2011-08-01T18:29:50.873Z", - "location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", - "version": "W\/\"wGB85s2QJMjiNnuI\"" - }, - "members": [ - { - "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", - "$ref": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", - "type": "Group" - } - ] - } - ] -} The service provider MUST define the maximum number of operations and maximum payload size a client may send in a single request. If either limits are exceeded the service provider MUST return the HTTP response code 413 Request Entity Too Large. The returned response MUST specify the limit exceeded in the body of the error response. The following example the client sent a request exceeding the service provider's max payload size of 1 megabyte. POST /v2/Bulk @@ -2924,21 +2942,21 @@ [I-D.ietf-precis-saslprepbis] Saint-Andre, P. and A. Melnikov, "Preparation and Comparison of Internationalized Strings Representing Usernames and Passwords", draft-ietf-precis-saslprepbis-07 (work in progress), March 2014. [I-D.ietf-scim-core-schema] Grizzle, K., Hunt, P., Wahlstroem, E., and C. Mortimore, "System for Cross-Domain Identity Management: Core - Schema", draft-ietf-scim-core-schema-08 (work in + Schema", draft-ietf-scim-core-schema-09 (work in progress), August 2014. [IANA.Language] Internet Assigned Numbers Authority (IANA), "Language Subtag Registry", 2005. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", @@ -3149,20 +3167,30 @@ Draft 09 - PH - Revisions as follows - Aligned API with new URN namespace per RFC3553 and IETF90 meeting - Clarified URN usage within patch (what schema urn applies) - Made 'path' optional in PATCH for Add and Replace + Draft 10 - PH - Revisions as follows + + Restructuring of Bulk into sub-sections + + General clarifications + + Improved Base URI section + + Authorization section clarifications + Authors' Addresses Phil Hunt (editor) Oracle Corporation Email: phil.hunt@yahoo.com Kelly Grizzle SailPoint