idnits 2.17.1 draft-ietf-scim-api-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 38 instances of too long lines in the document, the longest one being 25 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: +------------+----------------------------+-------------------------+ | Parameter | Description | Default | +------------+----------------------------+-------------------------+ | startIndex | The 1-based index of the | 1 | | | first query result. A | | | | value less than 1 SHALL be | | | | interpreted as 1. | | | count | Non-negative Integer. | None. When specified | | | Specifies the desired | the service provider | | | maximum number of query | MUST not return more | | | results per page; e.g., | results than specified | | | 10. A negative value SHALL | though MAY return fewer | | | be interpreted as "0". A | results. If | | | value of "0" indicates no | unspecified, the | | | resource results are to be | maximum number of | | | returned except for | results is set by the | | | "totalResults". | service provider. | +------------+----------------------------+-------------------------+ == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: Each operation against an attribute MUST be compatible with the attribute's mutability and schema as defined in the Attribute Types Section of [I-D.ietf-scim-core-schema]. For example, a client MAY NOT modify an attribute that has mutability "readOnly" or "immutable". However, a client MAY "add" a value to an "immutable" attribute if the attribute had no previous value. An operation that is not compatibile with an attribute's mutability or schema SHALL return the appropriate HTTP response status code and a JSON detail error response as defined in Section 3.10. -- The document date (September 1, 2014) is 3519 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC2616' is defined on line 2965, but no explicit reference was found in the text == Unused Reference: 'RFC3454' is defined on line 2969, but no explicit reference was found in the text == Unused Reference: 'RFC2277' is defined on line 3025, but no explicit reference was found in the text == Outdated reference: A later version (-18) exists of draft-ietf-precis-saslprepbis-07 == Outdated reference: A later version (-22) exists of draft-ietf-scim-core-schema-09 ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 3454 (Obsoleted by RFC 7564) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7233 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) == Outdated reference: A later version (-23) exists of draft-ietf-precis-framework-17 Summary: 10 errors (**), 0 flaws (~~), 9 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Hunt, Ed. 3 Internet-Draft Oracle 4 Intended status: Standards Track K. Grizzle 5 Expires: March 5, 2015 SailPoint 6 M. Ansari 7 Cisco 8 E. Wahlstroem 9 Nexus Technology 10 C. Mortimore 11 Salesforce 12 September 1, 2014 14 System for Cross-Domain Identity Management 0;,Protocol 15 draft-ietf-scim-api-10 17 Abstract 19 The System for Cross-Domain Identity Management (SCIM) specification 20 is an HTTP based protocol that makes managing identities in multi- 21 domain scenarios easier to support through a standardized services. 22 Examples include but are not limited to enterprise to cloud service 23 providers, and inter-cloud based scenarios. The specification suite 24 seeks to build upon experience with existing schemas and deployments, 25 placing specific emphasis on simplicity of development and 26 integration, while applying existing authentication, authorization, 27 and privacy models. SCIM's intent is to reduce the cost and 28 complexity of user management operations by providing a common user 29 schema and extension model and a service protocol defined by this 30 document. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on March 5, 2015. 49 Copyright Notice 51 Copyright (c) 2014 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 67 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3 68 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3 69 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 70 2. Authentication and Authorization . . . . . . . . . . . . . . 4 71 3. SCIM Protocol . . . . . . . . . . . . . . . . . . . . . . . . 5 72 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 6 73 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 8 74 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 8 75 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 8 76 3.2.2. Query Resources . . . . . . . . . . . . . . . . . . . 10 77 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 20 78 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 23 79 3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 24 80 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 26 81 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 39 82 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 40 83 3.5.1. Circular Reference Processing . . . . . . . . . . . . 42 84 3.5.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 46 85 3.5.3. Response and Error Handling . . . . . . . . . . . . . 49 86 3.5.4. Maximum Operations . . . . . . . . . . . . . . . . . 55 87 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 56 88 3.7. Additional Operation Response Parameters . . . . . . . . 57 89 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 58 90 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 58 91 3.10. HTTP Status and Error Response Handling . . . . . . . . . 59 92 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 63 93 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 63 94 4. Preparation and Comparison of Internationalized Strings . . . 65 95 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 65 96 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 66 97 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 66 98 6. Security Considerations . . . . . . . . . . . . . . . . . . . 67 99 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 67 100 6.2. Disclosure of Sensitive Information in URIs . . . . . . . 67 101 6.3. HTTP Considerations . . . . . . . . . . . . . . . . . . . 68 102 6.4. Secure Storage and Handling of Sensitive Data . . . . . . 68 103 6.5. Case Insensitive Comparision & International Languages . 69 104 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69 105 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 69 106 7.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 70 107 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 71 108 8.1. Normative References . . . . . . . . . . . . . . . . . . 71 109 8.2. Informative References . . . . . . . . . . . . . . . . . 72 110 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 73 111 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 73 112 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 73 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 76 115 1. Introduction and Overview 117 The SCIM Protocol is an application-level, HTTP protocol for 118 provisioning and managing identity data on the web and in cross- 119 domain environments such as enterprise to cloud, or inter-cloud 120 scenarios. The protocol supports creation, modification, retrieval, 121 and discovery of core identity resources such as Users and Groups, as 122 well as custom resources and resource extensions. 124 1.1. Intended Audience 126 This document is intended as a guide to SCIM protocol usage for both 127 SCIM HTTP service providers and HTTP clients who may provision 128 information to service providers or retrieve information from them. 130 1.2. Notational Conventions 132 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 133 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 134 document are to be interpreted as described in [RFC2119]. These 135 keywords are capitalized when used to unambiguously specify 136 requirements of the protocol or application features and behavior 137 that affect the interoperability and security of implementations. 138 When these words are not capitalized, they are meant in their 139 natural-language sense. 141 For purposes of readability examples are not URL encoded. 142 Implementers MUST percent encode URLs as described in Section 2.1 of 143 [RFC3986]. 145 1.3. Definitions 147 Base URI 148 The SCIM HTTP protocol is described in terms of a path relative to 149 a Base URI. The Base URI MUST NOT contain a query string as 150 clients may append additional path information and query 151 parameters as part of forming the request. The base URI most 152 often is a URL which most often consists of the "https" protocol 153 scheme, a domain name and some initial path [RFC3986]. Example: 154 "https://example.com/scim/" 156 For readability, all examples in this document are expressed 157 assuming the SCIM service root and the server root are the same 158 (no path pre-fix). It is expected that SCIM servers may be 159 deployed using any URI path prefix. For example, a SCIM server 160 might be have a prefix of "https://example.com/", or 161 "https://example.com/scim/tenancypath/". Additionally client may 162 also apply a version number to the server root prefix (see 163 Section 3.11 ). 165 2. Authentication and Authorization 167 Because SCIM builds on the HTTP protocol, it does not itself define a 168 scheme for authentication and authorization. SCIM depends on 169 standard HTTP authentication schemes. Implementers SHOULD support 170 existing authentication/authorization schemes. In particular, OAuth2 171 [RFC6750] is RECOMMENDED. Appropriate security considerations of the 172 selected authentication and authorization schemes SHOULD be taken. 173 Because this protocol uses HTTP response status codes as the primary 174 means of reporting the result of a request, servers are advised to 175 respond to unauthorized or unauthenticated requests using the 401 176 response code in accordance with Section 3.1 of [RFC7235]. 178 All examples show an OAuth2 bearer token [RFC6750] (though it is not 179 required); e.g., 181 GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 182 Host: example.com 183 Authorization: Bearer h480djs93hd8 185 When processing requests, the service provider SHOULD consider the 186 subject performing the request and whether the action is appropriate 187 given the subject and the resource affected by the request. The 188 subject performing the request is usually determined from the 189 "Authorization" header present in the request. 191 3. SCIM Protocol 193 The SCIM protocol specifies well-known endpoints and HTTP methods for 194 managing resources defined in the core schema; i.e., "User" and 195 "Group" resources correspond to "/Users" and "/Groups" respectively. 196 Service providers that support extended resources SHOULD define 197 resource endpoints using the convention of pluralizing the resource 198 name defined in the extended schema by appending an 's'. Given there 199 are cases where resource pluralization is ambiguous; e.g., a resource 200 named "Person" is legitimately "Persons" and "People". Clients 201 SHOULD discover resource endpoints via the "/ResourceTypes" endpoint. 203 GET 204 Retrieves one or more complete or partial resources. 206 POST 207 Depending on the endpoint, creates new resources, create a search 208 request, or may be used to bulk modify resources. 210 PUT 211 Modifies a resource by replacing existing attributes with a 212 specified set of replacement attributes (replace). PUT MUST NOT 213 be used to create new resources. 215 PATCH 216 Modifies a resource with a set of client specified changes 217 (partial update). 219 DELETE 220 Deletes a resource. 222 Resource Endpoint Operations Description 223 -------- ---------------- ---------------------- -------------------- 224 User /Users GET (Section 3.2.1), Retrieve, Add, 225 POST (Section 3.1), Modify Users 226 PUT (Section 3.3.1), 227 PATCH (Section 3.3.2), 228 DELETE (Section 3.4) 229 Group /Groups GET (Section 3.2.1), Retrieve, Add, 230 POST (Section 3.1), Modify Groups 231 PUT (Section 3.3.1), 232 PATCH (Section 3.3.2), 233 DELETE (Section 3.4) 234 Service /ServiceProvider GET (Section 3.2.1) Retrieve service 235 Provider Configs provider's 236 Config configuration 237 Resource /ResourceTypes GET (Section 3.2.1) Retrieve supported 238 Type resource types 239 Schema /Schemas GET (Section 3.2.1) Retrieve one or more 240 supported schemas. 241 Bulk /Bulk POST (Section 3.5) Bulk updates to one 242 or more resources 243 Search [prefix]/.search POST (Section 3.2.3) Search from system 244 root or within a 245 resource endpoint 246 for one or more 247 resource types using 248 POST. 250 Table 1: Defined endpoints 252 All requests to the service provider are made via HTTP Methods as per 253 Section 4.3 [RFC7231] on a URL derived from the Base URL. Responses 254 are returned in the body of the HTTP response, formatted as JSON. 255 Error status codes SHOULD be transmitted via the HTTP status code of 256 the response (if possible), and SHOULD also be specified in the body 257 of the response (see Section 3.10). 259 3.1. Creating Resources 261 To create new resources, clients send HTTP POST requests to the 262 resource endpoint such as: "/Users" or "/Groups". 264 Attributes in the request body, whose mutability is "readOnly", SHALL 265 be ignored. 267 Attributes whose mutability is "readWrite", that are omitted from the 268 request body, MAY be assumed to be not asserted by the client. The 269 service provider MAY assign a default value to non-asserted 270 attributes in the final resource representation. Service providers 271 MAY take into account whether a client has access to, or understands, 272 all of the resource's attributes when deciding whether non-asserted 273 attributes SHALL be defaulted. Clients that intend to override 274 server defaulted attributes, MAY specify "null" for a single-valued 275 attribute or an empty array "[]" for a multi-valued attribute to 276 clear all values. 278 When the service provider successfully creates the new resource, an 279 HTTP response SHALL be returned with HTTP status "201" ("Created"). 280 The response body SHOULD contain the service provider's 281 representation of the newly created resource. The URI of the created 282 resource SHALL included in the HTTP "Location" header and in JSON 283 resource representation under the attribute "meta.location". Since 284 the server is free to alter and/or ignore POSTed content, returning 285 the full representation can be useful to the client, enabling it to 286 correlate the client and server views of the new resource. 288 If the service provider determines creation of the requested resource 289 conflicts with existing resources; e.g., a "User" resource with a 290 duplicate "userName", the service provider MUST return an HTTP Status 291 409, with "scimType" error code of "uniqueness" as per Section 3.10. 293 Below, in the following example, a client sends a POST request 294 containing a "User" to the "/Users" endpoint. 296 POST /Users HTTP/1.1 297 Host: example.com 298 Accept: application/scim+json 299 Content-Type: application/scim+json 300 Authorization: Bearer h480djs93hd8 301 Content-Length: ... 303 { 304 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 305 "userName":"bjensen", 306 "externalId":"bjensen", 307 "name":{ 308 "formatted":"Ms. Barbara J Jensen III", 309 "familyName":"Jensen", 310 "givenName":"Barbara" 311 } 312 } 314 In response to the example request above, the server signals a 315 successful creation with an HTTP status code 201 (Created) and 316 returns a representation of the resource created. 318 HTTP/1.1 201 Created 319 Content-Type: application/scim+json 320 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 321 ETag: W/"e180ee84f0671b1" 323 { 324 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 325 "id":"2819c223-7f76-453a-919d-413861904646", 326 "externalId":"bjensen", 327 "meta":{ 328 "resourceType":"User", 329 "created":"2011-08-01T21:32:44.882Z", 330 "lastModified":"2011-08-01T21:32:44.882Z", 331 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 332 "version":"W\/\"e180ee84f0671b1\"" 333 }, 334 "name":{ 335 "formatted":"Ms. Barbara J Jensen III", 336 "familyName":"Jensen", 337 "givenName":"Barbara" 338 }, 339 "userName":"bjensen" 340 } 342 3.1.1. Resource Types 344 When adding a resource to a specific endpoint, the meta attribute 345 "resourceType" SHALL be set by the HTTP service provider to the 346 corresponding resource type for the endpoint. For example, "/Users" 347 will set "resourceType" to "User", and "/Groups" will set 348 "resourceType" to "Group". 350 3.2. Retrieving Resources 352 Resources are retrieved via opaque, unique URLs or via Query. The 353 attributes returned are defined in the server's attribute schema (see 354 Section 10 [I-D.ietf-scim-core-schema]) and request parameters (see 355 Section 3.7). By default, resource attributes returned in a response 356 are those whose schema "returned" setting is "always" or "default". 358 3.2.1. Retrieving a known Resource 360 To retrieve a known resource, clients send GET requests to the 361 resource endpoint; e.g., "/Users/{id}" or "/Groups/{id}", or 362 "/Schemas/{id}". 364 If the resource exists the server responds with HTTP Status code 200 365 (OK) and includes the result in the body of the response. 367 The below example retrieves a single User via the "/Users" endpoint. 369 GET /Users/2819c223-7f76-453a-919d-413861904646 370 Host: example.com 371 Accept: application/scim+json 372 Authorization: Bearer h480djs93hd8 374 The server responds with: 376 HTTP/1.1 200 OK 377 Content-Type: application/scim+json 378 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 379 ETag: W/"f250dd84f0671c3" 381 { 382 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 383 "id":"2819c223-7f76-453a-919d-413861904646", 384 "externalId":"bjensen", 385 "meta":{ 386 "resourceType":"User", 387 "created":"2011-08-01T18:29:49.793Z", 388 "lastModified":"2011-08-01T18:29:49.793Z", 389 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 390 "version":"W\/\"f250dd84f0671c3\"" 391 }, 392 "name":{ 393 "formatted":"Ms. Barbara J Jensen III", 394 "familyName":"Jensen", 395 "givenName":"Barbara" 396 }, 397 "userName":"bjensen", 398 "phoneNumbers":[ 399 { 400 "value":"555-555-8377", 401 "type":"work" 402 } 403 ], 404 "emails":[ 405 { 406 "value":"bjensen@example.com", 407 "type":"work" 408 } 409 ] 410 } 411 3.2.2. Query Resources 413 The SCIM protocol defines a standard set of query parameters that can 414 be used to filter, sort, and paginate to return zero or more 415 resources in a query response. Queries MAY be made against a single 416 resource or a resource type endpoint (e.g. "/Users"). SCIM service 417 providers MAY support additional query parameters not specified here 418 and SHOULD ignore any query parameters they do not recognize. 420 Responses MUST be identified using the following URI: 421 "urn:ietf:params:scim:api:messages:2.0:ListResponse". The following 422 attributes are defined for responses: 424 totalResults The total number of results returned by the list or 425 query operation. This may not be equal to the number of elements 426 in the resources attribute of the list response if pagination 427 (Section 3.2.2.4) is requested. REQUIRED. 429 Resources A multi-valued list of complex objects containing the 430 requested resources. This may be a subset of the full set of 431 resources if pagination (Section 3.2.2.4) is requested. REQUIRED 432 if "totalResults" is non-zero. 434 startIndex The 1-based index of the first result in the current set 435 of list results. REQUIRED when partial results returned due to 436 pagination. 438 itemsPerPage The number of resources returned in a list response 439 page. REQUIRED when partial results returned due to pagination. 441 A query that does not return any matches SHALL return success (HTTP 442 Status 200) with "totalResults" set to a value of 0. 444 The query example below requests the userName for all Users: 446 GET /Users?attributes=userName 447 Host: example.com 448 Accept: application/scim+json 449 Authorization: Bearer h480djs93hd8 450 The following is an example response to the query above: 452 HTTP/1.1 200 OK 453 Content-Type: application/scim+json 455 { 456 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 457 "totalResults":2, 458 "Resources":[ 459 { 460 "userName":"bjensen" 461 }, 462 { 463 "userName":"jsmith" 464 } 465 ] 466 } 468 3.2.2.1. Query Endpoints 470 Queries MAY be performed against a SCIM resource object, a resource 471 type endpoint, or a SCIM server root. For example: 473 "/Users/{id}" 475 "/Users" 477 "/Groups" 479 A query against a server root indicates that ALL resources within the 480 server SHALL be included subject to filtering. A filter expression 481 using "meta.resourceType" MAY be used to restrict results to one or 482 more specific resource types (to exclude others). For example: 484 filter=(meta.resourceType eq User) or (meta.resourceType eq Group) 486 If a SCIM service provider determines that too many results would be 487 returned (e.g. because a client queried a resource type endpoint or 488 the server base URI), the server SHALL reject the request by 489 returning an HTTP response with "status" 400 and json attribute 490 "scimType" set to "tooMany" (see Table 8). 492 When processing query operations across endpoints that include more 493 than one SCIM resource type (e.g. a query from the server root 494 endpoint), filters MUST be processed as outlined in Section 3.2.2.2. 495 For filtered attributes that are not part of a particular resource 496 type, the service provider SHALL treat the attribute as if there is 497 no attribute value. For example, a presence or equality filter for 498 an undefined attribute evaluates as FALSE. 500 3.2.2.2. Filtering 502 Filtering is an OPTIONAL parameter for SCIM service providers. 503 Clients MAY discover service provider filter capabilities by looking 504 at the "filter" attribute of the "ServiceProviderConfig" (see 505 Section 8 [I-D.ietf-scim-core-schema]). Clients MAY request a subset 506 of resources by specifying the "filter" query parameter containing a 507 filter expression. When specified only those resources matching the 508 filter expression SHALL be returned. The expression language that is 509 used in the filter parameter supports references to attributes and 510 literals. 512 Attribute names and attribute operators used in filters are case 513 insensitive. For example, the following two expressions will 514 evaluate to the same logical value: 516 filter=userName Eq "john" 518 filter=Username eq "john" 520 The filter parameter MUST contain at least one valid Boolean 521 expression. Each expression MUST contain an attribute name followed 522 by an attribute operator and optional value. Multiple expressions 523 MAY be combined using the two logical operators. Furthermore 524 expressions can be grouped together using "()". 526 The operators supported in the expression are listed in the following 527 table. 529 +----------+-------------+------------------------------------------+ 530 | Operator | Description | Behavior | 531 +----------+-------------+------------------------------------------+ 532 | eq | equal | The attribute and operator values must | 533 | | | be identical for a match. | 534 | ne | not equal | The attribute and operator values are | 535 | | | not identical. | 536 | co | contains | The entire operator value must be a | 537 | | | substring of the attribute value for a | 538 | | | match. | 539 | sw | starts with | The entire operator value must be a | 540 | | | substring of the attribute value, | 541 | | | starting at the beginning of the | 542 | | | attribute value. This criterion is | 543 | | | satisfied if the two strings are | 544 | | | identical. | 545 | ew | ends with | The entire operator value must be a | 546 | | | substring of the attribute value, | 547 | | | matching at the end of the attribute | 548 | | | value. This criterion is satisfied if | 549 | | | the two strings are identical. | 550 | pr | present | If the attribute has a non-empty or non- | 551 | | (has value) | null value, or if it contains a non- | 552 | | | empty node for complex attributes there | 553 | | | is a match. | 554 | gt | greater | If the attribute value is greater than | 555 | | than | operator value, there is a match. The | 556 | | | actual comparison is dependent on the | 557 | | | attribute type. For string attribute | 558 | | | types, this is a lexicographical | 559 | | | comparison and for DateTime types, it is | 560 | | | a chronological comparison. For Integer | 561 | | | attributes it is a comparison by numeric | 562 | | | value. Boolean and Binary attributes | 563 | | | SHALL cause a failed response (HTTP | 564 | | | Status 400) with scimType of | 565 | | | invlaidFiler. | 566 | ge | greater | If the attribute value is greater than | 567 | | than or | or equal to the operator value, there is | 568 | | equal | a match. The actual comparison is | 569 | | | dependent on the attribute type. For | 570 | | | string attribute types, this is a | 571 | | | lexicographical comparison and for | 572 | | | DateTime types, it is a chronological | 573 | | | comparison. For Integer attributes it is | 574 | | | a comparison by numeric value. Boolean | 575 | | | and Binary attributes SHALL cause a | 576 | | | failed response (HTTP Status 400) with | 577 | | | scimType of invlaidFiler. | 578 | lt | less than | If the attribute value is less than | 579 | | | operator value, there is a match. The | 580 | | | actual comparison is dependent on the | 581 | | | attribute type. For string attribute | 582 | | | types, this is a lexicographical | 583 | | | comparison and for DateTime types, it is | 584 | | | a chronological comparison. For Integer | 585 | | | attributes it is a comparison by numeric | 586 | | | value. Boolean and Binary attributes | 587 | | | SHALL cause a failed response (HTTP | 588 | | | Status 400) with scimType of | 589 | | | invlaidFiler. | 590 | le | less than | If the attribute value is less than or | 591 | | or equal | equal to the operator value, there is a | 592 | | | match. The actual comparison is | 593 | | | dependent on the attribute type. For | 594 | | | string attribute types, this is a | 595 | | | lexicographical comparison and for | 596 | | | DateTime types, it is a chronological | 597 | | | comparison. For Integer attributes it is | 598 | | | a comparison by numeric value. Boolean | 599 | | | and Binary attributes SHALL cause a | 600 | | | failed response (HTTP Status 400) with | 601 | | | scimType of invlaidFiler. | 602 +----------+-------------+------------------------------------------+ 604 Table 2: Attribute Operators 606 +----------+-------------+------------------------------------------+ 607 | Operator | Description | Behavior | 608 +----------+-------------+------------------------------------------+ 609 | and | Logical And | The filter is only a match if both | 610 | | | expressions evaluate to true. | 611 | or | Logical or | The filter is a match if either | 612 | | | expression evaluates to true. | 613 | not | Not | The filter is a match if the expression | 614 | | function | evaluates to false. | 615 +----------+-------------+------------------------------------------+ 617 Table 3: Logical Operators 619 +----------+-------------+------------------------------------------+ 620 | Operator | Description | Behavior | 621 +----------+-------------+------------------------------------------+ 622 | ( ) | Precedence | Boolean expressions may be grouped using | 623 | | grouping | parentheses to change the standard order | 624 | | | of operations; i.e., evaluate OR logical | 625 | | | operators before logical AND operators. | 626 | [ ] | Complex | Service providers MAY support complex | 627 | | attribute | filters where expressions MUST be | 628 | | filter | applied to the same value of a parent | 629 | | grouping | attribute specified immediately before | 630 | | | the left square bracket ("["). The | 631 | | | expression within square brackets ("[" | 632 | | | and "]") MUST be a valid filter | 633 | | | expression based upon sub-attributes of | 634 | | | the parent attribute. Nested expressions | 635 | | | MAY be used. See examples below. | 636 +----------+-------------+------------------------------------------+ 638 Table 4: Grouping Operators 640 SCIM filters MUST conform to the following ABNF rules as per 641 [RFC5234] below: 643 FILTER = attrExp / logExp / valuePath / *1"not" "(" FILTER ")" 645 valuePath = attrPath "[" FILTER "]" 646 ; FILTER uses sub-attribs of a parent attrPath 648 ATTRNAME = ALPHA *(nameChar) 650 nameChar = "-" / "_" / DIGIT / ALPHA 652 attrPath = [URI ":"] ATTRNAME *1subAttr 653 ; SCIM attribute name 654 ; URI is SCIM "schema" URI 656 subAttr = "." ATTRNAME 657 ; a sub-attribute of a complex attribute 659 attrExp = (attrPath SP "pr") / 660 (attrPath SP compareOp SP compValue) 662 compValue = false / null / true / number / string 663 ; rules from JSON (RFC7159) 665 compareOp = "eq" / "ne" / "co" / 666 "sw" / "ew" / 667 "gt" / "lt" / 668 "ge" / "le" 670 logExp = FILTER ("and" / "or") FILTER 672 Figure 1: ABNF Specification of SCIM Filters 674 In the above ABNF, the "compValue" (comparison value) rule is built 675 on JSON Data Interchange format ABNF rules as specified in [RFC7159], 676 "DIGIT" and "ALPHA" are defined per Appendix B.1 of [RFC5234] and, 677 "URI" is defined per Appendix A of [RFC3986]. 679 Filters MUST be evaluated using standard order of operations 680 [Order-Operations]. Attribute operators have the highest precedence, 681 followed by the grouping operator (i.e, parentheses), followed by the 682 logical AND operator, followed by the logical OR operator. 684 If the specified attribute in a filter expression is a multi-valued 685 attribute, the resource MUST match if any of the instances of the 686 given attribute match the specified criterion; e.g. if a User has 687 multiple emails values, only one has to match for the entire User to 688 match. For complex attributes, a fully qualified Sub-Attribute MUST 689 be specified using standard attribute notation (Section 3.8). For 690 example, to filter by userName the parameter value is userName and to 691 filter by first name, the parameter value is name.givenName. 693 Providers MAY support additional filter operations if they choose. 694 Providers MUST decline to filter results if the specified filter 695 operation is not recognized and return a HTTP 400 error with an 696 appropriate human readable response. For example, if a client 697 specified an unsupported operator named 'regex' the service provider 698 should specify an error response description identifying the client 699 error; e.g., 'The operator 'regex' is not supported.' 701 String type attributes are case insensitive by default unless the 702 attribute type is defined as case exact. Attribute comparison 703 operators 'eq', 'co', and 'sw' MUST perform caseIgnore matching for 704 all string attributes unless the attribute is defined as case exact. 705 By default all string attributes are case insensitive. 707 Clients MAY query by schema or schema extensions by using a filter 708 expression including the "schemas" attribute. 710 The following are examples of valid filters. Some attributes (e.g. 711 rooms and rooms.number) are hypothetical extensions and are not part 712 of SCIM core schema: 714 filter=userName eq "bjensen" 716 filter=name.familyName co "O'Malley" 718 filter=userName sw "J" 720 filter=title pr 722 filter=meta.lastModified gt "2011-05-13T04:42:34Z" 724 filter=meta.lastModified ge "2011-05-13T04:42:34Z" 726 filter=meta.lastModified lt "2011-05-13T04:42:34Z" 728 filter=meta.lastModified le "2011-05-13T04:42:34Z" 730 filter=title pr and userType eq "Employee" 732 filter=title pr or userType eq "Intern" 734 filter=schemas eq "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" 736 filter=userType eq "Employee" and (emails co "example.com" or emails 737 co "example.org") 739 filter=userType ne "Employee" and not (emails co "example.com" or 740 emails co "example.org") 742 filter=userType eq "Employee" and (emails.type eq "work") 744 filter=userType eq "Employee" and emails[type eq "work" and 745 value co "@example.com"] 747 filter=emails[type eq "work" and value co "@example.com"] or 748 ims[type eq "xmpp" and value co "@foo.com"] 750 filter=addresses[state eq "CA" and rooms[type eq "bedroom" and 751 number gt 2]] 753 Figure 2: Example Filters 755 3.2.2.3. Sorting 757 Sort is OPTIONAL. Sorting allows clients to specify the order in 758 which resources are returned by specifying a combination of sortBy 759 and sortOrder URL parameters. 761 sortBy: The sortBy parameter specifies the attribute whose value 762 SHALL be used to order the returned responses. If the sortBy 763 attribute corresponds to a singular attribute, resources are 764 sorted according to that attribute's value; if it's a multi-valued 765 attribute, resources are sorted by the value of the primary 766 attribute (see Section 2.2 [I-D.ietf-scim-core-schema]), if any, 767 or else the first value in the list, if any. If the attribute is 768 complex the attribute name must be a path to a sub-attribute in 769 standard attribute notation (Section 3.8) ; e.g., 770 "sortBy=name.givenName". For all attribute types, if there is no 771 data for the specified "sortBy" value they are sorted via the 772 "sortOrder" parameter; i.e., they are ordered last if ascending 773 and first if descending. 775 sortOrder: The order in which the sortBy parameter is applied. 776 Allowed values are "ascending" and "descending". If a value for 777 sortBy is provided and no sortOrder is specified, the sortOrder 778 SHALL default to ascending. String type attributes are case 779 insensitive by default unless the attribute type is defined as a 780 case exact string. "sortOrder" MUST sort according to the 781 attribute type; i.e., for case insensitive attributes, sort the 782 result using case insensitive, unicode alphabetic sort order, with 783 no specific locale implied and for case exact attribute types, 784 sort the result using case sensitive, Unicode alphabetic sort 785 order. 787 3.2.2.4. Pagination 789 Pagination parameters can be used together to "page through" large 790 numbers of resources so as not to overwhelm the client or service 791 provider. Pagination is not session based hence clients SHOULD never 792 assume repeatable results. For example, a request for a list of 10 793 resources beginning with a startIndex of 1 may return different 794 results when repeated as a resource in the original result could be 795 deleted or new ones could be added in-between requests. Pagination 796 parameters and general behavior are derived from the OpenSearch 797 Protocol [OpenSearch]. 799 The following table describes the URL pagination parameters. 801 +------------+----------------------------+-------------------------+ 802 | Parameter | Description | Default | 803 +------------+----------------------------+-------------------------+ 804 | startIndex | The 1-based index of the | 1 | 805 | | first query result. A | | 806 | | value less than 1 SHALL be | | 807 | | interpreted as 1. | | 808 | count | Non-negative Integer. | None. When specified | 809 | | Specifies the desired | the service provider | 810 | | maximum number of query | MUST not return more | 811 | | results per page; e.g., | results than specified | 812 | | 10. A negative value SHALL | though MAY return fewer | 813 | | be interpreted as "0". A | results. If | 814 | | value of "0" indicates no | unspecified, the | 815 | | resource results are to be | maximum number of | 816 | | returned except for | results is set by the | 817 | | "totalResults". | service provider. | 818 +------------+----------------------------+-------------------------+ 820 Table 5: Pagination Request parameters 822 The following table describes the query response pagination 823 attributes specified by the service provider. 825 +--------------+----------------------------------------------------+ 826 | Element | Description | 827 +--------------+----------------------------------------------------+ 828 | itemsPerPage | Non-negative Integer. Specifies the number of | 829 | | query results returned in a query response page; | 830 | | e.g., 10. | 831 | totalResults | Non-negative Integer. Specifies the total number | 832 | | of results matching the client query; e.g., 1000. | 833 | startIndex | The 1-based index of the first result in the | 834 | | current set of query results; e.g., 1. | 835 +--------------+----------------------------------------------------+ 837 Table 6: Pagination Response Elements 839 For example, to retrieve the first 10 Users set the startIndex to 1 840 and the count to 10: 842 GET /Users?startIndex=1&count=10 843 Host: example.com 844 Accept: application/scim+json 845 Authorization: Bearer h480djs93hd8 846 The response to the query above returns metadata regarding paging 847 similar to the following example (actual resources removed for 848 brevity): 850 { 851 "totalResults":100, 852 "itemsPerPage":10, 853 "startIndex":1, 854 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 855 "Resources":[{ 856 ... 857 }] 858 } 860 Given the example above, to continue paging set the startIndex to 11 861 and re-fetch; i.e., /Users?startIndex=11&count=10 863 3.2.2.5. Attributes 865 The following attributes control which attributes SHALL be returned 866 with a returned resource. SCIM clients MAY use up to one of these 867 two OPTIONAL parameters which MUST be supported by SCIM service 868 providers: 870 attributes A multi-valued list of strings indicating the names of 871 resource attributes to return in the response overriding the set 872 of attributes that would be returned by default. Attribute names 873 MUST be in standard.attribute notation (Section 3.8) form. See 874 additional retrieval query parameters (Section 3.7). 876 excludedAttributes A multi-valued list of strings indicating the 877 names of resource attributes to be removed from the default set of 878 attributes to return. This parameter SHALL have no effect on 879 attributes whose schema "returned" setting is "always" see Server 880 Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in 881 standard attribute notation (Section 3.8) form. See additional 882 retrieval query parameters (Section 3.7). 884 3.2.3. Querying Resources Using HTTP POST 886 Clients MAY execute queries without passing parameters on the URL by 887 using the HTTP POST verb combined with the '/.search' path extension. 888 The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL 889 be used to indicate the HTTP POST verb is intended to be a query 890 operation. 892 To create a new query result set, a SCIM client sends an HTTP POST 893 request to the desired SCIM resource endpoint (ending in '/.search'). 895 The body of the POST request MAY include any of the parameters as 896 defined in Section 3.2.2. 898 Query requests MUST be identified using the following URI: 899 'urn:ietf:params:scim:api:messages:2.0:SearchRequest'. The following 900 attributes are defined for query requests: 902 attributes A multi-valued list of strings indicating the names of 903 resource attributes to return in the response overriding the set 904 of attributes that would be returned by default. Attribute names 905 MUST be in standard attribute notation (Section 3.8) form. See 906 additional retrieval query parameters (Section 3.7). OPTIONAL. 908 excludedAttributes A multi-valued list of strings indicating the 909 names of resource attributes to be removed from the default set of 910 attributes to return. This parameter SHALL have no effect on 911 attributes whose schema "returned" setting is "always" see Server 912 Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in 913 standard attribute notation (Section 3.8) form. See additional 914 retrieval query parameters (Section 3.7). OPTIONAL. 916 filter The filter string used to request a subset of resources. The 917 filter string MUST be a valid filter (Section 3.2.2.2) expression. 918 OPTIONAL. 920 sortBy A string indicating the attribute whose value SHALL be used 921 to order the returned responses. The sortBy attribute MUST be in 922 standard attribute notation (Section 3.8) form. See sorting 923 (Section 3.2.2.3). OPTIONAL. 925 sortOrder A string indicating the order in which the sortBy 926 parameter is applied. Allowed values are "ascending" and 927 "descending". See sorting (Section 3.2.2.3). OPTIONAL. 929 startIndex An integer indicating the 1-based index of the first 930 query result. See pagination (Section 3.2.2.4). OPTIONAL. 932 count An integer indicating the desired maximum number of query 933 results per page. See pagination (Section 3.2.2.4). OPTIONAL. 935 After receiving a HTTP POST request, a response is returned as 936 specified in Section 3.2.2. 938 The following example shows an HTTP POST Query request with search 939 parameters attributes, filter, and count included: 941 POST /.search 942 Host: example.com 943 Accept: application/scim+json 944 Content-Type: application/scim+json 945 Authorization: Bearer h480djs93hd8 946 Content-Length: ... 948 { 949 "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], 950 "attributes": ["displayName", "userName"], 951 "filter": "(displayName sw \"smith\") and (meta.resourceType eq \"User\")", 952 "startIndex": 1, 953 "count": 10 954 } 956 Figure 3: Example POST Query Request 958 A query response is shown with the first page of results. For 959 brevity reasons, only two matches are shown: one User and one Group. 961 HTTP/1.1 200 OK 962 Content-Type: application/scim+json 963 Location: https://example.com/.search 964 { 965 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 966 "totalResults":100, 967 "itemsPerPage":10, 968 "startIndex":1, 969 "Resources":[ 970 { 971 "meta":{ 972 "location": 973 "https://example.com/Users/2819c223-7f76-413861904646", 974 "resourceType":"User", 975 "lastModified": ... 976 }, 977 "userName":"jsmith", 978 "displayName":"Smith, James" 979 }, 980 { 981 "meta":{ 982 "location": 983 "https://example.com/Groups/c8596b90-7539-4f20968d1908", 984 "resourceType":"Group", 985 "lastModified": ... 986 }, 987 "displayName":"Smith Family" 988 }, 989 ... 990 ] 991 } 993 Figure 4: Example POST Query Response 995 3.3. Modifying Resources 997 Resources can be modified in whole or in part via PUT or PATCH, 998 respectively. Implementers MUST support PUT as specified in 999 Section 4.3 [RFC7231]. Resources such as Groups may be very large 1000 hence implementers SHOULD support HTTP PATCH [RFC5789] to enable 1001 partial resource modifications. 1003 3.3.1. Replacing with PUT 1005 HTTP PUT is used to perform a full update of a resource's attributes. 1006 Clients that MAY have previously retrieved the entire resource in 1007 advance and revised it, MAY replace the resource using an HTTP PUT. 1008 Because SCIM resource identifiers are typically assigned by the 1009 service provider, HTTP PUT MUST NOT be used to create new resources. 1011 As the operation intent is to replace all attributes, SCIM clients 1012 MAY send all attributes regardless of each attribute's mutability. 1013 The server will apply attribute by attribute replace according to the 1014 following attribute mutability rules: 1016 readWrite, writeOnly Any values provided SHALL replace the existing 1017 attribute values. 1019 immutable If value(s) are already set for the attribute, the input 1020 value(s) MUST match or HTTP status 400 SHOULD be returned with 1021 error code "mutability". If the service provider has no existing 1022 values, the new value(s) SHALL be applied. 1024 readOnly Any values provided (e.g. meta.resourceType) SHALL be 1025 ignored. 1027 If an attribute is "required", clients MUST specify the attribute in 1028 the PUT request. 1030 Attributes whose mutability is "readWrite", that are omitted from the 1031 request body, MAY be assumed to be not asserted by the client. The 1032 service provider MAY assume any existing values are to be cleared or 1033 the service provider MAY assign a default value to the final resource 1034 representation. Service providers MAY take into account whether a 1035 client has access to, or understands, all of the resource's 1036 attributes when deciding whether non-asserted attributes SHALL be 1037 removed or defaulted. Clients that would like to override a server 1038 defaults, MAY specify "null" for a single-valued attribute or an 1039 empty array "[]" for a multi-valued attribute to clear all values. 1041 Unless otherwise specified a successful PUT operation returns a 200 1042 OK response code and the entire resource within the response body, 1043 enabling the client to correlate the client's and the service 1044 provider's views of the updated resource. Example: 1046 PUT /Users/2819c223-7f76-453a-919d-413861904646 1047 Host: example.com 1048 Accept: application/scim+json 1049 Content-Type: application/scim+json 1050 Authorization: Bearer h480djs93hd8 1051 If-Match: W/"a330bc54f0671c9" 1053 { 1054 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 1055 "id":"2819c223-7f76-453a-919d-413861904646", 1056 "userName":"bjensen", 1057 "externalId":"bjensen", 1058 "name":{ 1059 "formatted":"Ms. Barbara J Jensen III", 1060 "familyName":"Jensen", 1061 "givenName":"Barbara", 1062 "middleName":"Jane" 1063 }, 1064 "roles":[], 1065 "emails":[ 1066 { 1067 "value":"bjensen@example.com" 1068 }, 1069 { 1070 "value":"babs@jensen.org" 1071 } 1072 ] 1073 } 1074 The service responds with the entire, updated User: 1076 HTTP/1.1 200 OK 1077 Content-Type: application/scim+json 1078 ETag: W/"b431af54f0671a2" 1079 Location:"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646" 1080 { 1081 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 1082 "id":"2819c223-7f76-453a-919d-413861904646", 1083 "userName":"bjensen", 1084 "externalId":"bjensen", 1085 "name":{ 1086 "formatted":"Ms. Barbara J Jensen III", 1087 "familyName":"Jensen", 1088 "givenName":"Barbara", 1089 "middleName":"Jane" 1090 }, 1091 "emails":[ 1092 { 1093 "value":"bjensen@example.com" 1094 }, 1095 { 1096 "value":"babs@jensen.org" 1097 } 1098 ], 1099 "meta": { 1100 "resourceType":"User", 1101 "created":"2011-08-08T04:56:22Z", 1102 "lastModified":"2011-08-08T08:00:12Z", 1103 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 1104 "version":"W\/\"b431af54f0671a2\"" 1105 } 1106 } 1108 3.3.2. Modifying with PATCH 1110 HTTP PATCH is an OPTIONAL server function that enables clients to 1111 update one or more attributes of a SCIM resource using a sequence of 1112 operations to "add", "remove", or "replace" values. The general form 1113 of the SCIM patch request is based on JavaScript Object Notation 1114 (JSON) Patch [RFC6902]. One difference between SCIM patch and JSON 1115 patch is that SCIM servers do not support array indexing and may not 1116 support all [RFC6902] operation types. 1118 The body of an HTTP PATCH request MUST contain one or more patch 1119 operation objects. A patch operation object MUST have exactly one 1120 "op" member, whose value indicates the operation to perform and MAY 1121 be one of "add", "remove", or "replace". The semantics of each 1122 operation are defined below. 1124 The body of each request MUST contain the following "schemas" URI: 1125 "urn:ietf:params:scim:api:messages:2.0:PatchOp", followed by an array 1126 of one or more operations. For example: 1128 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1129 [ 1130 { 1131 "op":"add", 1132 "path":"members", 1133 "value":[ 1134 { 1135 "display": "Babs Jensen", 1136 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1137 "value": "2819c223-7f76-453a-919d-413861904646" 1138 } 1139 ] 1140 }, 1141 ... + additional operations if needed ... 1142 ] 1143 } 1145 Example JSON body for SCIM PATCH Request 1147 A "path" attribute value is a String containing an attribute path 1148 describing the target of the operation. The "path" attribute is 1149 OPTIONAL for "add" and "replace" and is REQUIRED for "remove" 1150 operations. See relevant operation sections below for details. 1152 The "path" attribute is described by the following ABNF syntax rule: 1154 PATH = attrPath / valuePath [subAttr] 1156 Figure 5: SCIM Patch PATH Rule 1158 The ABNF rules, "attrPath", "valuePath", and "subAttr" are defined in 1159 Section 3.2.2.2. The "valuePath" rule allows specific values of a 1160 complex, multi-valued attribute to be selected. 1162 Valid examples of "path" values are as follows: 1164 "path":"members" 1166 "path":"name.familyName" 1168 "path":"addresses[type eq \"work\"]" 1170 "path":"members[value eq 1171 \"2819c223-7f76-453a-919d-413861904646\"]" 1173 "path":"members[value eq 1174 \"2819c223-7f76-453a-919d-413861904646\"].displayName" 1176 Figure 6: Example Path Values 1178 Each operation against an attribute MUST be compatible with the 1179 attribute's mutability and schema as defined in the Attribute Types 1180 Section of [I-D.ietf-scim-core-schema]. For example, a client MAY 1181 NOT modify an attribute that has mutability "readOnly" or 1182 "immutable". However, a client MAY "add" a value to an "immutable" 1183 attribute if the attribute had no previous value. An operation that 1184 is not compatibile with an attribute's mutability or schema SHALL 1185 return the appropriate HTTP response status code and a JSON detail 1186 error response as defined in Section 3.10. 1188 The attribute notation rules described in Section 3.8 apply for 1189 describing attribute paths. For all operations, the value of the 1190 "schemas" attribute on the SCIM service provider's representation of 1191 the resource SHALL be assumed by default. If one of the PATCH 1192 operations modifies the "schemas" attribute, subsequent operations 1193 SHALL assume the modified state of the "schemas" attribute. Clients 1194 MAY implicitly modify the "schemas" attribute by adding (or 1195 replacing) an attribute with its fully qualified name including 1196 schema URN. For example, adding the attribute "urn:ietf:params:scim: 1197 schemas:extension:enterprise:2.0:User:employeeNumber", automatically 1198 adds the value 1199 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" to the 1200 resource's "schemas" attribute. 1202 Each patch operation represents a single action to be applied to the 1203 same SCIM resource specified by the request URI. Operations are 1204 applied sequentially in the order they appear in the array. Each 1205 operation in the sequence is applied to the target resource; the 1206 resulting resource becomes the target of the next operation. 1207 Evaluation continues until all operations are successfully applied or 1208 until an error condition is encountered. 1210 For a multi-valued attributes, a patch operation that sets a value's 1211 "primary" attribute to "true", SHALL cause the server to 1212 automatically set "primary" to "false" for any other values in the 1213 array as only one value MAY be primary. 1215 A patch request, regardless of the number of operations, SHALL be 1216 treated as atomic. If a single operation encounters an error 1217 condition, the original SCIM resource MUST be restored, and a failure 1218 status SHALL be returned. 1220 If a request fails, the server SHALL return an HTTP response status 1221 code and a JSON detail error response as defined in Section 3.10. 1223 On successful completion, the server MUST return either a 200 OK 1224 response code and the entire resource (subject to the "attributes" 1225 query parameter - see Additional Retrieval Query Parameters 1226 (Section 3.7) ) within the response body, or a 204 No Content 1227 response code and the appropriate response headers for a successful 1228 patch request. The server MUST return a 200 OK if the "attributes" 1229 parameter is specified on the request. 1231 3.3.2.1. Add Operation 1233 The "add" operation is used to add a new attribute value to an 1234 existing resource. 1236 The operation MUST contain a "value" member whose content specifies 1237 the value to be added. The value MAY be a quoted value OR it may be 1238 a JSON object containing the sub-attributes of the complex attribute 1239 specified in the operation's "path". 1241 The result of the add operation depends upon what the target location 1242 indicated by "path" references: 1244 o If omitted, the target location is assumed to be the resource 1245 itself. The "value" parameter contains a set of attributes to be 1246 added to the resource. 1248 o If the target location does not exist, the attribute and value is 1249 added. 1251 o If the target location specifies a complex attribute, a set of 1252 sub-attributes SHALL be specified in the "value" parameter. 1254 o If the target location specifies a multi-valued attribute, a new 1255 value is added to the attribute. 1257 o if the target location specifies a single-valued attribute, the 1258 existing value is replaced. 1260 o If the target location specifies an attribute that does not exist 1261 (has no value), the attribute is added with the new value. 1263 o If the target location exists, the value is replaced. 1265 o If the target location already contains the value specified, no 1266 changes SHOULD be made to the resource and a success response 1267 SHOULD be returned. Unless other operations change the resource, 1268 this operation SHALL NOT change the modify timestamp of the 1269 resource. 1271 The following example shows how to add a member to a group. Some 1272 text removed for readability ("..."): 1274 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1275 Host: example.com 1276 Accept: application/scim+json 1277 Content-Type: application/scim+json 1278 Authorization: Bearer h480djs93hd8 1279 If-Match: W/"a330bc54f0671c9" 1280 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1281 [ 1282 { 1283 "op":"add", 1284 "path":"members", 1285 "value":[ 1286 { 1287 "display": "Babs Jensen", 1288 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1289 "value": "2819c223-7f76-453a-919d-413861904646" 1290 } 1291 ] 1292 } 1293 ] 1294 } 1296 If the user was already a member of this group, no changes should be 1297 made to the resource and a success response should be returned. The 1298 server responds with either the entire updated Group or no response 1299 body: 1301 HTTP/1.1 204 No Content 1302 Authorization: Bearer h480djs93hd8 1303 ETag: W/"b431af54f0671a2" 1304 Location: "https://example.com/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" 1305 The following example shows how to add one or more attributes to a 1306 User resource without using a "path" attribute. 1308 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1309 Host: example.com 1310 Accept: application/scim+json 1311 Content-Type: application/scim+json 1312 Authorization: Bearer h480djs93hd8 1313 If-Match: W/"a330bc54f0671c9" 1315 { 1316 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1317 [{ 1318 "op":"add", 1319 "value":"{ 1320 "emails":[ 1321 { 1322 "value":"babs@jensen.org", 1323 "type":"home" 1324 } 1325 ], 1326 "nickname":"Babs" 1327 }] 1328 } 1330 In the above example, an additional value is added to the multi- 1331 valued attribute "emails". The second attribute, "nickname" is added 1332 to the User resource. If the resource already had an existing 1333 "nickname", the value is replaced per the processing rules above for 1334 single-valued attributes. 1336 3.3.2.2. Remove Operation 1338 The "remove" operation removes the value at the target location 1339 specified by the required attribute "path". The operation performs 1340 the following functions depending on the target location specified by 1341 "path" : 1343 o If "path" is unspecified, the operation fails with HTTP status 1344 "400" and "scimType" of "noTarget". 1346 o If the target location is a single-value attribute, the attribute 1347 and its associated value is removed and the attribute SHALL be 1348 considered unassigned. 1350 o If the target location is a multi-valued attribute and no filter 1351 is specified, the attribute and all values are removed and the 1352 attribute SHALL be considered unassigned. 1354 o If the target location is a multi-valued attribute and a complex 1355 filter is specified comparing a "value", the values matched by the 1356 filter are removed. If after removal of the selected values, no 1357 other values remain, the multi-valued attribute SHALL be 1358 considered unassigned. 1360 o If the target location is a complex-multi-valued attribute and a 1361 complex filter is specified based on the attribute's sub- 1362 attributes, the matching records are removed. Sub-attributes 1363 whose values have been removed SHALL be considered unassigned. If 1364 the complex-multi-valued attribute has no remaining records, the 1365 attribute SHALL be considered unassigned. 1367 If an attribute is removed or becomes unassigned and is defined as a 1368 required attribute or a read-only attribute, the server SHALL return 1369 an HTTP response status code and a JSON detail error response as 1370 defined in Section 3.10 with a "scimType" error of "mutability". 1372 The following example shows how to remove a member from a group. As 1373 with the previous example, the "display" sub-attribute is optional. 1374 If the user was not a member of this group, no changes should be made 1375 to the resource and a success response should be returned. 1377 Note that server responses have been omitted for the rest of the 1378 PATCH examples. 1380 Remove a single member from a group. Some text removed for 1381 readability ("..."): 1383 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1384 Host: example.com 1385 Accept: application/scim+json 1386 Content-Type: application/scim+json 1387 Authorization: Bearer h480djs93hd8 1388 If-Match: W/"a330bc54f0671c9" 1390 { 1391 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1392 [{ 1393 "op":"remove", 1394 "path":"members[value eq \"2819c223-7f76-...413861904646\"]" 1395 }] 1396 } 1397 Remove all members of a group: 1399 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1400 Host: example.com 1401 Accept: application/scim+json 1402 Content-Type: application/scim+json 1403 Authorization: Bearer h480djs93hd8 1404 If-Match: W/"a330bc54f0671c9" 1406 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1407 [{ 1408 "op":"remove","path":"members" 1409 }] 1410 } 1412 Removal of a value from a complex-multi-valued attribute (request 1413 headers removed for brevity): 1415 { 1416 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1417 [{ 1418 "op":"remove", 1419 "path":"emails[type eq \"work\" and value ew \"example.com\"]" 1420 }] 1421 } 1422 Example request to remove and add a member. Some text removed for 1423 readability ("..."): 1425 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1426 Host: example.com 1427 Accept: application/scim+json 1428 Content-Type: application/scim+json 1429 Authorization: Bearer h480djs93hd8 1430 If-Match: W/"a330bc54f0671c9" 1431 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1432 [ 1433 { 1434 "op":"remove", 1435 "path":"members[value eq\"2819c223...919d-413861904646\"]" 1436 }, 1437 { 1438 "op":"add", 1439 "path":"members", 1440 "value": [ 1441 { 1442 "display": "James Smith", 1443 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1444 "value": "08e1d05d...473d93df9210" 1445 } 1446 ] 1447 } 1448 ] 1449 } 1450 The following example shows how to replace all the members of a group 1451 with a different members list. Some text removed for readabilty 1452 ("..."): 1454 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1455 Host: example.com 1456 Accept: application/scim+json 1457 Content-Type: application/scim+json 1458 Authorization: Bearer h480djs93hd8 1459 If-Match: W/"a330bc54f0671c9" 1460 { 1461 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1462 [ 1463 { 1464 "op":"remove","path":"members" 1465 }, 1466 { 1467 "op":"add", 1468 "path":"members", 1469 "value":[ 1470 { 1471 "display": "Babs Jensen", 1472 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1473 "value": "2819c223-7f76-453a-919d-413861904646" 1474 }, 1475 { 1476 "display": "James Smith", 1477 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1478 "value": "08e1d05d-121c-4561-8b96-473d93df9210" 1479 }] 1480 } 1481 ] 1482 } 1484 3.3.2.3. Replace Operation 1486 The "replace" operation replaces the value at the target location 1487 specified by the "path". The operation performs the following 1488 functions depending on the target location specified by "path" : 1490 o If the "path" parameter is omitted, the target is assumed to be 1491 the resource itself. In this case, the "value" attribute SHALL 1492 contain a list of one or more attributes that are to be replaced. 1494 o If the target location is a single-value attribute, the attributes 1495 value is replaced. 1497 o If the target location is a multi-valued attribute and no filter 1498 is specified, the attribute and all values are replaced. 1500 o If the target location specifies a complex attribute, a set of 1501 sub-attributes SHALL be specified in the "value" parameter which 1502 replaces any existing values or adds where an attribute did not 1503 previously exist. Sub-attributes that are not specified in the 1504 "value" parameter are left unchanged. 1506 o If the target location is a multi-valued attribute and a complex 1507 filter is specified comparing a "value", the values matched by the 1508 filter are replaced. 1510 o If the target location is a complex-multi-valued attribute and a 1511 complex filter is specified based on the attribute's sub- 1512 attributes, the matching records are replaced. 1514 o If the target location is a complex-multi-valued attribute with a 1515 complex filter and a specific sub-attribute (e.g. "addresses[type 1516 eq "work"].streetAddress" ), the matching sub-attribute of the 1517 matching record is replaced. 1519 The following example shows how to replace all the members of a group 1520 with a different members list in a single replace operation. Some 1521 text removed for readability ("..."): 1523 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1524 Host: example.com 1525 Accept: application/scim+json 1526 Content-Type: application/scim+json 1527 Authorization: Bearer h480djs93hd8 1528 If-Match: W/"a330bc54f0671c9" 1530 { 1531 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1532 [{ 1533 "op":"replace", 1534 "path":"members", 1535 "value":[ 1536 { 1537 "display": "Babs Jensen", 1538 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1539 "value": "2819c223...413861904646" 1540 }, 1541 { 1542 "display": "James Smith", 1543 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1544 "value": "08e1d05d...473d93df9210" 1545 } 1546 ] 1547 }] 1548 } 1549 The following example shows how to change a User's entire "work" 1550 address. 1552 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1553 Host: example.com 1554 Accept: application/scim+json 1555 Content-Type: application/scim+json 1556 Authorization: Bearer h480djs93hd8 1557 If-Match: W/"a330bc54f0671c9" 1559 { 1560 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1561 [{ 1562 "op":"replace", 1563 "path":"addresses[type eq \"work\"]", 1564 "value": 1565 { 1566 "type": "work", 1567 "streetAddress": "911 Universal City Plaza", 1568 "locality": "Hollywood", 1569 "region": "CA", 1570 "postalCode": "91608", 1571 "country": "US", 1572 "formatted": "911 Universal City Plaza\nHollywood, CA 91608 US", 1573 "primary": true 1574 } 1575 }] 1576 } 1578 The following example shows how to change a User's "work" email 1579 address: 1581 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1582 Host: example.com 1583 Accept: application/scim+json 1584 Content-Type: application/scim+json 1585 Authorization: Bearer h480djs93hd8 1586 If-Match: W/"a330bc54f0671c9" 1588 { 1589 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1590 [{ 1591 "op":"replace", 1592 "path":"emails[type eq \"work\"].value", 1593 "value":"bjenson@example.com" 1594 }] 1595 } 1596 The following example shows how to replace one or more attributes of 1597 a User resource. 1599 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1600 Host: example.com 1601 Accept: application/scim+json 1602 Content-Type: application/scim+json 1603 Authorization: Bearer h480djs93hd8 1604 If-Match: W/"a330bc54f0671c9" 1606 { 1607 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1608 [{ 1609 "op":"replace", 1610 "value":"{ 1611 "emails":[ 1612 { 1613 "value":"bjensen@example.com", 1614 "type":"work", 1615 "primary":true 1616 }, 1617 { 1618 "value":"babs@jensen.org", 1619 "type":"home" 1620 } 1621 ], 1622 "nickname":"Babs" 1623 }] 1624 } 1626 3.4. Deleting Resources 1628 Clients request resource removal via DELETE. Service providers MAY 1629 choose not to permanently delete the resource, but MUST return a 404 1630 error code for all operations associated with the previously deleted 1631 Id. Service providers MUST also omit the resource from future query 1632 results. In addition the service provider SHOULD NOT consider the 1633 deleted resource in conflict calculation. For example if a User 1634 resource is deleted, a CREATE request for a User resource with the 1635 same userName as the previously deleted resource should not fail with 1636 a 409 error due to userName conflict. 1638 DELETE /Users/2819c223-7f76-453a-919d-413861904646 1639 Host: example.com 1640 Authorization: Bearer h480djs93hd8 1641 If-Match: W/"c310cd84f0281b7" 1643 In response to a successful delete, the server SHALL respond with 1644 successful HTTP status 204 (No Content). A non-normative example 1645 response: 1647 HTTP/1.1 204 No Content 1649 Example: client attempt to retrieve the previously deleted User 1651 GET /Users/2819c223-7f76-453a-919d-413861904646 1652 Host: example.com 1653 Authorization: Bearer h480djs93hd8 1655 Server Response: 1657 HTTP/1.1 404 NOT FOUND 1659 { 1660 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 1661 "Errors":[ 1662 { 1663 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 1664 "code":"404" 1665 } 1666 ] 1667 } 1669 3.5. Bulk 1671 The SCIM bulk operation is an optional server feature that enables 1672 clients to send a potentially large collection of resource operations 1673 in a single request. The body of a a bulk operation contains a set 1674 of HTTP resource operations using one of the API supported HTTP 1675 methods; i.e., POST, PUT, PATCH or DELETE. 1677 Bulk requests are identified using the following URI: 1678 "urn:ietf:params:scim:api:messages:2.0:BulkRequest". Bulk responses 1679 are identified using the following URI: 1680 "urn:ietf:params:scim:api:messages:2.0:BulkResponse". Bulk requests 1681 and bulk responses share many attributes. Unless otherwise 1682 specified, each attribute below is present in both bulk requests and 1683 bulk responses. 1685 The following Singular Attribute is defined in addition to the common 1686 attributes defined in SCIM core schema. 1688 failOnErrors 1689 An Integer specifying the number of errors that the service 1690 provider will accept before the operation is terminated and an 1691 error response is returned. OPTIONAL in a request. Not valid in 1692 a response. 1694 The following Complex Multi-valued Attribute is defined in addition 1695 to the common attributes defined in core schema. 1697 Operations 1698 Defines operations within a bulk job. Each operation corresponds 1699 to a single HTTP request against a resource endpoint. REQUIRED. 1700 Operations has the following sub-attributes: 1702 method The HTTP method of the current operation. Possible values 1703 are POST, PUT, PATCH or DELETE. REQUIRED. 1705 bulkId The transient identifier of a newly created resource, 1706 unique within a bulk request and created by the client. The 1707 bulkId serves as a surrogate resource id enabling clients to 1708 uniquely identify newly created resources in the Response and 1709 cross reference new resources in and across operations within a 1710 bulk request. REQUIRED when method is POST. 1712 version The current resource version. Version is MAY be used if 1713 the service provider supports ETags and the method is PUT, 1714 PATCH, or DELETE. 1716 path The resource's relative path. If the method is POST the 1717 value must specify a resource type endpoint; e.g., /Users or 1718 /Groups whereas all other method values must specify the path 1719 to a specific resource; e.g., /Users/2819c223-7f76-453a-919d- 1720 413861904646. REQUIRED in a request. 1722 data The resource data as it would appear for a single POST, PUT 1723 or PATCH resource operation. REQUIRED in a request when method 1724 is POST, PUT and PATCH. 1726 location The resource endpoint URL. REQUIRED in a response, 1727 except in the event of a POST failure. 1729 response The HTTP response body to the specified request 1730 operation. When indicating a response with an HTTP status 1731 other than a 200 series response, the response body MUST be 1732 included. For normal completion, the server MAY elect to omit 1733 the response body. 1735 status The HTTP response status code to the requested operation. 1736 When indicating an error, the "response" attribute MUST contain 1737 the detailed error response as per Section 3.10. 1739 If a bulk job is processed successfully the HTTP response code 200 OK 1740 MUST be returned, otherwise an appropriate HTTP error code MUST be 1741 returned. 1743 The service provider MUST continue performing as many changes as 1744 possible and disregard partial failures. The client MAY override 1745 this behavior by specifying a value for the "failOnErrors" attribute. 1746 The failOnErrors attribute defines the number of errors that the 1747 service provider should accept before failing the remaining 1748 operations returning the response. 1750 To be able to reference a newly created resource the attribute bulkId 1751 MUST be specified when creating new resources. The "bulkId" is 1752 defined by the client as a surrogate identifier in a POST operation 1753 (see Section 3.5.2). The service provider MUST return the same 1754 "bulkId" together with the newly created resource. The "bulkId" can 1755 then be used by the client to map the service provider id with the 1756 "bulkId" of the created resource. 1758 A SCIM service provider MAY elect to optimize a sequence operations 1759 received (e.g. to improve processing performance). When doing so, 1760 the service provider MUST ensure the clients intent is preserved and 1761 the same stateful result is achieved as for non-optimized processing. 1762 For example, before a "User" can be added to a "Group", they must 1763 first be created. Processing these requests out of order, might 1764 result in a failure to add the new "User" to the "Group". 1766 3.5.1. Circular Reference Processing 1768 The service provider MUST try to resolve circular cross references 1769 between resources in a single bulk job but MAY stop after a failed 1770 attempt and instead return the status code 409 Conflict. The 1771 following example exhibits the potential conflict. 1773 POST /v2/Bulk 1774 Host: example.com 1775 Accept: application/scim+json 1776 Content-Type: application/scim+json 1777 Authorization: Bearer h480djs93hd8 1778 Content-Length: ... 1780 { 1781 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 1782 "Operations": [ 1783 { 1784 "method": "POST", 1785 "path": "/Groups", 1786 "bulkId": "qwerty", 1787 "data": { 1788 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1789 "displayName": "Group A", 1790 "members": [ 1791 { 1792 "type": "Group", 1793 "value": "bulkId:ytrewq" 1794 } 1795 ] 1796 } 1797 }, 1798 { 1799 "method": "POST", 1800 "path": "/Groups", 1801 "bulkId": "ytrewq", 1802 "data": { 1803 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1804 "displayName": "Group B", 1805 "members": [ 1806 { 1807 "type": "Group", 1808 "value": "bulkId:qwerty" 1809 } 1810 ] 1811 } 1812 } 1813 ] 1814 } 1816 If the service provider resolved the above circular references the 1817 following is returned from a subsequent GET request. 1819 GET /v2/Groups?filter=displayName sw 'Group' 1820 Host: example.com 1821 Accept: application/scim+json 1822 Authorization: Bearer h480djs93hd8 1824 HTTP/1.1 200 OK 1825 Content-Type: application/scim+json 1827 { 1828 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 1829 "totalResults": 2, 1830 "Resources": [ 1831 { 1832 "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1833 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1834 "displayName": "Group A", 1835 "meta": { 1836 "resourceType": "Group", 1837 "created": "2011-08-01T18:29:49.793Z", 1838 "lastModified": "2011-08-01T18:29:51.135Z", 1839 "location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1840 "version": "W\/\"mvwNGaxB5SDq074p\"" 1841 }, 1842 "members": [ 1843 { 1844 "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1845 "$ref": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1846 "type": "Group" 1847 } 1848 ] 1849 }, 1850 { 1851 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1852 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1853 "displayName": "Group B", 1854 "meta": { 1855 "resourceType": "Group", 1856 "created": "2011-08-01T18:29:50.873Z", 1857 "lastModified": "2011-08-01T18:29:50.873Z", 1858 "location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1859 "version": "W\/\"wGB85s2QJMjiNnuI\"" 1860 }, 1861 "members": [ 1862 { 1863 "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1864 "$ref": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1865 "type": "Group" 1866 } 1867 ] 1868 } 1869 ] 1870 } 1871 3.5.2. BulkdId Temporary Identifiers 1873 The client can, within one bulk operation, create a new "User", a new 1874 "Group" and add the newly created "User" to the newly created 1875 "Group". In order to add the new "User" to the "Group" the client 1876 must use the surrogate id attribute, "bulkId", to reference the User. 1877 The "bulkId" attribute value must be pre-pended with the literal 1878 "bulkId:"; e.g., if the bulkId is 'qwerty', the value is 1879 "bulkId:qwerty". The service provider MUST replace the string 1880 "bulkId:qwerty" with the permanent resource id once created. 1882 The following example creates a User with the "userName" 'Alice' and 1883 a "Group" with the "displayName" 'Tour Guides' with Alice as a 1884 member. 1886 POST /v2/Bulk 1887 Host: example.com 1888 Accept: application/scim+json 1889 Content-Type: application/scim+json 1890 Authorization: Bearer h480djs93hd8 1891 Content-Length: ... 1893 { 1894 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 1895 "Operations": [ 1896 { 1897 "method": "POST", 1898 "path": "/Users", 1899 "bulkId": "qwerty", 1900 "data": { 1901 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 1902 "userName": "Alice" 1903 } 1904 }, 1905 { 1906 "method": "POST", 1907 "path": "/Groups", 1908 "bulkId": "ytrewq", 1909 "data": { 1910 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1911 "displayName": "Tour Guides", 1912 "members": [ 1913 { 1914 "type": "User", 1915 "value": "bulkId:qwerty" 1916 } 1917 ] 1918 } 1919 } 1920 ] 1921 } 1923 The service provider returns the following response: 1925 A subsequent GET request for the 'Tour Guides' Group ('e9e30dba-f08f- 1926 4109-8486-d5c6a331660a') returns the following: 1928 HTTP/1.1 200 OK 1929 Content-Type: application/scim+json 1930 Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1931 ETag: W/"lha5bbazU3fNvfe5" 1933 { 1934 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1935 "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", 1936 "displayName": "Tour Guides", 1937 "meta": { 1938 "resourceType": "Group", 1939 "created": "2011-08-01T18:29:49.793Z", 1940 "lastModified": "2011-08-01T20:31:02.315Z", 1941 "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1942 "version": "W\/\"lha5bbazU3fNvfe5\"" 1943 }, 1944 "members": [ 1945 { 1946 "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", 1947 "$ref": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1948 "type": "User" 1949 } 1950 ] 1951 } 1953 Extensions that include references to other resources MUST be handled 1954 in the same way by the service provider. The following example uses 1955 the bulkId attribute within the enterprise extension managerId 1956 attribute. 1958 POST /v2/Bulk 1959 Host: example.com 1960 Accept: application/scim+json 1961 Content-Type: application/scim+json 1962 Authorization: Bearer h480djs93hd8 1963 Content-Length: ... 1965 { 1966 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 1967 "Operations": [ 1968 { 1969 "method": "POST", 1970 "path": "/Users", 1971 "bulkId": "qwerty", 1972 "data": { 1973 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 1974 "userName": "Alice" 1975 } 1976 }, 1977 { 1978 "method": "POST", 1979 "path": "/Users", 1980 "bulkId": "ytrewq", 1981 "data": { 1982 "schemas": [ 1983 "urn:ietf:params:scim:schemas:core:2.0:User", 1984 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" 1985 ], 1986 "userName": "Bob", 1987 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { 1988 "employeeNumber": "11250", 1989 "manager": { 1990 "managerId": "batchId:qwerty", 1991 "displayName": "Alice" 1992 } 1993 } 1994 } 1995 } 1996 ] 1997 } 1999 3.5.3. Response and Error Handling 2001 The service provider response MUST include the result of all 2002 processed operations. A "location" attribute that includes the 2003 resource's endpoint MUST be returned for all operations excluding 2004 failed POSTs. The status attribute includes information about the 2005 success or failure of one operation within the bulk job. The 2006 attribute status MUST include the code attribute that holds the HTTP 2007 response code that would have been returned if a single HTTP request 2008 would have been used. If an error occurred the status MUST also 2009 include the description attribute containing a human readable 2010 explanation of the error. 2012 "status": "201" 2014 The following is an example of a status in a failed operation. 2016 "status": "400", 2017 "response":{ 2018 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2019 "scimType":"invalidSyntax" 2020 "detail":"Request is unparseable, syntactically incorrect, or violates schema.", 2021 "status":"400" 2022 } 2024 The following example shows how to add, update, and remove a user. 2025 The "failOnErrors" attribute is set to '1' indicating the service 2026 provider should return on the first error. The POST operation's 2027 bulkId value is set to 'qwerty' enabling the client to match the new 2028 User with the returned resource id '92b725cd-9465-4e7d- 2029 8c16-01f8e146b87a'. 2031 POST /v2/Bulk 2032 Host: example.com 2033 Accept: application/scim+json 2034 Content-Type: application/scim+json 2035 Authorization: Bearer h480djs93hd8 2036 Content-Length: ... 2038 { 2039 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 2040 "failOnErrors":1, 2041 "Operations":[ 2042 { 2043 "method":"POST", 2044 "path":"/Users", 2045 "bulkId":"qwerty", 2046 "data":{ 2047 "schemas": ["urn:ietf:params:scim:api:messages:2.0:User"], 2048 "userName":"Alice" 2049 } 2050 }, 2051 { 2052 "method":"PUT", 2053 "path":"/Users/b7c14771-226c-4d05-8860-134711653041", 2054 "version":"W\/\"3694e05e9dff591\"", 2055 "data":{ 2056 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 2057 "id":"b7c14771-226c-4d05-8860-134711653041", 2058 "userName":"Bob" 2059 } 2060 }, 2061 { 2062 "method": "PATCH", 2063 "path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2064 "version": "W/\"edac3253e2c0ef2\"", 2065 "data": {[ 2066 { 2067 "op": "remove", 2068 "path": "nickName" 2069 }, 2070 { 2071 "op": "add", 2072 "path": "userName", 2073 "value": "Dave" 2074 } 2075 ]} 2076 }, 2077 { 2078 "method":"DELETE", 2079 "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2080 "version":"W\/\"0ee8add0a938e1a\"" 2081 } 2082 ] 2083 } 2085 The service provider returns the following response. 2087 HTTP/1.1 200 OK 2088 Content-Type: application/scim+json 2090 { 2091 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2092 "Operations": [ 2093 { 2094 "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2095 "method": "POST", 2096 "bulkId": "qwerty", 2097 "version": "W\/\"oY4m4wn58tkVjJxK\"", 2098 "status": "201" 2099 }, 2100 { 2101 "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 2102 "method": "PUT", 2103 "version": "W\/\"huJj29dMNgu3WXPD\"", 2104 "status": "200" 2105 }, 2106 { 2107 "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2108 "method": "PATCH", 2109 "version": "W\/\"huJj29dMNgu3WXPD\"", 2110 "status": "200" 2111 }, 2112 { 2113 "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2114 "method": "DELETE", 2115 "status": "204" 2116 } 2117 ] 2118 } 2120 The following response is returned if an error occurred when 2121 attempting to create the User 'Alice'. The service provider stops 2122 processing the bulk operation and immediately returns a response to 2123 the client. The response contains the error and any successful 2124 results prior to the error. 2126 HTTP/1.1 200 OK 2127 Content-Type: application/scim+json 2129 { 2130 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2131 "Operations": [ 2132 { 2133 "method": "POST", 2134 "bulkId": "qwerty", 2135 "status": "400", 2136 "response":{ 2137 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2138 "scimType":"invalidSyntax" 2139 "detail":"Request is unparseable, syntactically incorrect, or violates schema.", 2140 "status":"400" 2141 } 2142 } 2143 ] 2144 } 2146 If the "failOnErrors" attribute is not specified or the service 2147 provider has not reached the error limit defined by the client the 2148 service provider will continue to process all operations. The 2149 following is an example in which all operations failed. 2151 HTTP/1.1 200 OK 2152 Content-Type: application/scim+json 2154 { 2155 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2156 "Operations": [ 2157 { 2158 "method": "POST", 2159 "bulkId": "qwerty", 2160 "status": "400", 2161 "response":{ 2162 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2163 "scimType":"invalidSyntax" 2164 "detail":"Request is unparseable, syntactically incorrect, or violates schema.", 2165 "status":"400" 2166 } 2167 }, 2168 { 2169 "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 2170 "method": "PUT", 2171 "status": "412", 2172 "response":{ 2173 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2174 "detail":"Failed to update as user changed on the server since you last retrieved it.", 2175 "status":"412" 2176 } 2177 }, 2178 { 2179 "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2180 "method": "PATCH", 2181 "status": "412", 2182 "response":{ 2183 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2184 "detail":"Failed to update as user changed on the server since you last retrieved it.", 2185 "status":"412" 2186 } 2187 }, 2188 { 2189 "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2190 "method": "DELETE", 2191 "status": "404", 2192 "response":{ 2193 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2194 "detail":"Resource does not exist.", 2195 "status":"404" 2196 } 2197 } 2198 ] 2199 } 2200 HTTP/1.1 200 OK 2201 Content-Type: application/scim+json 2203 { 2204 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2205 "Operations": [ 2206 { 2207 "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2208 "method": "POST", 2209 "bulkId": "qwerty", 2210 "version": "W\/\"4weymrEsh5O6cAEK\"", 2211 "status": "201" 2212 }, 2213 { 2214 "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 2215 "method": "POST", 2216 "bulkId": "ytrewq", 2217 "version": "W\/\"lha5bbazU3fNvfe5\"", 2218 "status": "201" 2219 } 2220 ] 2221 } 2223 3.5.4. Maximum Operations 2225 The service provider MUST define the maximum number of operations and 2226 maximum payload size a client may send in a single request. If 2227 either limits are exceeded the service provider MUST return the HTTP 2228 response code 413 Request Entity Too Large. The returned response 2229 MUST specify the limit exceeded in the body of the error response. 2231 The following example the client sent a request exceeding the service 2232 provider's max payload size of 1 megabyte. 2234 POST /v2/Bulk 2235 Host: example.com 2236 Accept: application/scim+json 2237 Content-Type: application/scim+json 2238 Authorization: Bearer h480djs93hd8 2239 Content-Length: 4294967296 2241 ... 2243 HTTP/1.1 413 Request Entity Too Large 2244 Content-Type: application/scim+json 2246 { 2247 "schemas":["urn:ietf:params:scim:api:messages:2.0:Error"], 2248 "status": "413", 2249 "detail":"The size of the bulk operation exceeds the maxPayloadSize (1048576)." 2250 } 2252 3.6. Data Input/Output Formats 2254 Servers MUST accept requests and respond with JSON structured 2255 responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default 2256 encoding format. 2258 Clients using other encodings MUST specify the format in which the 2259 data is submitted via HTTP header "Content-Type" as specified in 2260 Section 3.1.1.5 [RFC7231] and MAY specify the desired response data 2261 format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g., 2262 "Accept: application/scim+json" or via URI suffix; e.g., 2264 GET /Users/2819c223-7f76-453a-919d-413861904646.scim 2265 Host: example.com 2267 Service providers MUST support the accept header "Accept: 2268 application/scim+json" and SHOULD support header "Accept: 2269 application/json" both of which specify JSON documents conforming to 2270 [RFC7159]. The format defaults to "application/scim+json" if no 2271 format is specified. 2273 Singular attributes are encoded as string name-value-pairs in JSON; 2274 e.g., 2276 "attribute": "value" 2278 Multi-valued attributes in JSON are encoded as arrays; e.g., 2280 "attributes": [ "value1", "value2" ] 2282 Elements with nested elements are represented as objects in JSON; 2283 e.g, 2285 "attribute": { "subattribute1": "value1", "subattribute2": "value2" } 2287 3.7. Additional Operation Response Parameters 2289 For any SCIM operation where a resource representation is returned 2290 (e.g. HTTP GET), the attributes returned are defined as the minimum 2291 attribute set plus default attributes set. The minimum set are those 2292 attributes whose schema have "returned" set to "always". The default 2293 attribute set are those attributes whose schema have "returned" set 2294 to "default". 2296 Clients MAY request a partial resource representation on any 2297 operation that returns a resource within the response by specifying 2298 either of the mutually exclusive URL query parameters "attributes" OR 2299 "excludedAtributes" as follows: 2301 attributes When specified the default list of attributes SHALL be 2302 overridden and each resource returned MUST contain the 2303 minimum set of resource attributes and any attributes or sub- 2304 attributes explicitly requested by the "attributes" 2305 parameter. The query parameter attributes value is a comma 2306 separated list of resource attribute names in standard 2307 attribute notation (Section 3.8) form (e.g. userName, name, 2308 emails). 2310 excludedAttributes When specified, each resource returned MUST 2311 contain the minimal set of resource attributes. 2312 Additionally, the default set of attributes minus those 2313 attributes listed in "excludedAttributes" are also returned. 2314 The query parameter attributes value is a comma separated 2315 list of resource attribute names in standard attribute 2316 notation (Section 3.8) form (e.g. userName, name, emails). 2318 . 2320 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName 2321 Host: example.com 2322 Accept: application/scim+json 2323 Authorization: Bearer h480djs93hd8 2325 Giving the response 2327 HTTP/1.1 200 OK 2328 Content-Type: application/scim+json 2329 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2330 ETag: W/"a330bc54f0671c9" 2332 { 2333 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2334 "id":"2819c223-7f76-453a-919d-413861904646", 2335 "userName":"bjensen", 2336 "meta":{ 2337 "resourceType": "User", 2338 "created":"2011-08-01T18:29:49.793Z", 2339 "lastModified":"2011-08-01T18:29:49.793Z", 2340 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2341 "version":"W\/\"a330bc54f0671c9\"" 2342 } 2343 } 2345 3.8. Attribute Notation 2347 All operations share a common scheme for referencing simple and 2348 complex attributes. In general, attributes are identified by 2349 prefixing the attribute name with its schema URN separated by a ':' 2350 character; e.g., the core User resource attribute 'userName' is 2351 identified as "urn:ietf:params:scim:schemas:core:2.0:User:userName". 2352 Clients MAY omit core schema attribute URN prefixes though MUST fully 2353 qualify extended attributes with the associated resource URN; e.g., 2354 the attribute 'age' defined in 2355 "urn:ietf:params:scim:schemas:exampleCo:2.0:hr" is fully encoded as 2356 "urn:ietf:params:scim:schemas:exampleCo:2.0:hr:age". A Complex 2357 attributes' Sub-Attributes are referenced via nested, dot ('.') 2358 notation; i.e., {urn}:{Attribute name}.{Sub-Attribute name}. For 2359 example, the fully qualified path for a User's givenName is 2360 "urn:ietf:params:scim:schemas:core:2.0:User:name.givenName" All 2361 facets (URN, attribute and Sub-Attribute name) of the fully encoded 2362 Attribute name are case insensitive. 2364 3.9. "/Me" Authenticated Subject Alias 2366 A client MAY use a URL of the form "/Me" as a URI alias for 2367 the User or other resource associated with the currently 2368 authenticated subject for any SCIM operation. A service provider MAY 2369 respond in ONE of 3 ways: 2371 o A service provider that does NOT support this feature SHOULD 2372 respond with status 403 (FORBIDDEN). 2374 o A service provider MAY choose to redirect the client using HTTP 2375 status 308 to the resource associated with the authenticated 2376 subject. The client MAY then repeat the request at the indicated 2377 location. 2379 o A service provider MAY process the SCIM request directly. In any 2380 response, the HTTP "Location" header MUST be the permanent 2381 location of the aliased resource associated with the authenticated 2382 subject. 2384 3.10. HTTP Status and Error Response Handling 2386 The SCIM Protocol uses the HTTP status response status codes defined 2387 in Section 6 [RFC7231] to indicate operation success or failure. In 2388 addition to returning a HTTP response code implementers MUST return 2389 the errors in the body of the response in the client requested format 2390 containing the error response and, per the HTTP specification, human- 2391 readable explanations. Error responses are identified using the 2392 following "schema" URI: 2393 "urn:ietf:params:scim:api:messages:2.0:Error". The following 2394 attributes are defined for a SCIM error response using a JSON body: 2396 status 2397 The HTTP status code (see Section 6 [RFC7231]). REQUIRED 2399 scimType 2400 A SCIM detailed error keyword. See Table 8. OPTIONAL 2402 detail 2403 A detailed, human readable message. OPTIONAL 2405 Implementers SHOULD handle the identified HTTP status codes as 2406 described below. 2408 +--------------+---------------+------------------------------------+ 2409 | Status | Applicability | Suggested Explanation | 2410 +--------------+---------------+------------------------------------+ 2411 | 307 | GET, POST, | The client is directed to repeat | 2412 | TEMPORARY | PUT, PATCH, | the same HTTP request at the | 2413 | REDIRECT | DELETE | location identified. The client | 2414 | | | SHOULD NOT use the location | 2415 | | | provided in the response as a | 2416 | | | permanent reference to the | 2417 | | | resource and SHOULD continue to | 2418 | | | use the original request URI | 2419 | | | [RFC7231]. | 2420 | 308 | GET, POST, | The client is directed to repeat | 2421 | PERMANENT | PUT, PATCH, | the same HTTP request at the | 2422 | REDIRECT | DELETE | location identified. The client | 2423 | | | SHOULD use the location provided | 2424 | | | in the response as the permanent | 2425 | | | reference to the resource | 2426 | | | [I-D.reschke-http-status-308]. | 2427 | 400 BAD | GET, POST, | Request is unparseable, | 2428 | REQUEST | PUT, PATCH, | syntactically incorrect, or | 2429 | | DELETE | violates schema | 2430 | 401 | GET, POST, | Authorization failure | 2431 | UNAUTHORIZED | PUT, PATCH, | | 2432 | | DELETE | | 2433 | 403 | GET, POST, | Server does not support requested | 2434 | FORBIDDEN | PUT, PATCH, | operation | 2435 | | DELETE | | 2436 | 404 NOT | GET, PUT, | Specified resource (e.g., User) or | 2437 | FOUND | PATCH, DELETE | end-point, does not exist | 2438 | 409 CONFLICT | POST, PUT, | The specified version number does | 2439 | | PATCH, DELETE | not match the resource's latest | 2440 | | | version number or a service | 2441 | | | provider refused to create a new, | 2442 | | | duplicate resource | 2443 | 412 | PUT, PATCH,D | Failed to update as resource {id} | 2444 | PRECONDITION | ELETE | changed on the server last | 2445 | FAILED | | retrieved | 2446 | 413 REQUEST | POST | {"maxOperations": | 2447 | ENTITY TOO | | 1000,"maxPayload": 1048576} | 2448 | LARGE | | | 2449 | 500 INTERNAL | GET, POST, | An internal error. Implementers | 2450 | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive | 2451 | | DELETE | debugging advice | 2452 | 501 NOT | GET, POST, | Service Provider does not support | 2453 | IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH | 2454 | | DELETE | | 2455 +--------------+---------------+------------------------------------+ 2457 Table 7: SCIM HTTP Status Code Usage 2459 For HTTP Status 400 (Bad Request) responses, the following detail 2460 error types are defined: 2462 +--------------+------------------------------+---------------------+ 2463 | scimType | Description | Applicability | 2464 +--------------+------------------------------+---------------------+ 2465 | invalidFilte | The specified filter syntax | GET(Section 3.2.2), | 2466 | r | was invalid (does not comply | POST (Search - | 2467 | | with Figure 1) or the | Section 3.2.3), | 2468 | | specified attribute and | PATCH (Path Filter | 2469 | | filter comparison | - Section 3.3.2) | 2470 | | combination is not | | 2471 | | supported. | | 2472 | tooMany | The specified filter yields | GET(Section 3.2.2), | 2473 | | many more results than the | POST (Search - | 2474 | | server is willing calculate | Section 3.2.3) | 2475 | | or process. For example, a | | 2476 | | filter such as "(userName | | 2477 | | pr)" by itself would return | | 2478 | | all entries with a | | 2479 | | "userName" and MAY not be | | 2480 | | acceptable to the service | | 2481 | | provider. | | 2482 | uniqueness | One or more of attribute | POST (Create - | 2483 | | values is already in use or | Section 3.1), PUT | 2484 | | is reserved. | (Section 3.3.1), | 2485 | | | PATCH (Section | 2486 | | | 3.3.2) | 2487 | mutability | The attempted modification | PUT (Section | 2488 | | is not compatible with the | 3.3.1), PATCH | 2489 | | target attributes mutability | (Section 3.3.2) | 2490 | | or current state (e.g. | | 2491 | | modification of an immutable | | 2492 | | attribute with an existing | | 2493 | | value). | | 2494 | invalidSynta | The request body message | POST (Search - | 2495 | x | structure was invalid or did | Section 3.2.2, | 2496 | | not conform to the request | Create - Section | 2497 | | schema. | 3.1, Bulk - Section | 2498 | | | 3.5), PUT (Section | 2499 | | | 3.3.1) | 2500 | invalidPath | The path attribute was | PATCH (Section | 2501 | | invalid or malformed (see | 3.3.2) | 2502 | | Figure 5). | | 2503 | noTarget | The specified "path" did not | PATCH (Section | 2504 | | yield an attribute or | 3.3.2) | 2505 | | attribute value that could | | 2506 | | be operated on. This occurs | | 2507 | | when the specified "path" | | 2508 | | value contains a filter that | | 2509 | | yields no match. | | 2510 | invalidValue | A required value was | GET (Section | 2511 | | missing, or the value | 3.2.2), POST | 2512 | | specified was not compatible | (Create - Section | 2513 | | with the operation or | 3.1, Query - | 2514 | | attribute type (see Section | Section 3.2.2), PUT | 2515 | | 2.1 [I-D.ietf-scim-core-sche | (Section 3.3.1), | 2516 | | ma]). | PATCH (Section | 2517 | | | 3.3.2) | 2518 | invalidVers | The specified SCIM protocol | GET (Section | 2519 | | version is not supported | 3.2.2), POST (ALL), | 2520 | | (see Section 3.11). | PUT (Section | 2521 | | | 3.3.1), PATCH | 2522 | | | (Section 3.3.2), | 2523 | | | DELETE (Section | 2524 | | | 3.4) | 2525 +--------------+------------------------------+---------------------+ 2527 Table 8: Table of SCIM Detail Error Keyword Values 2529 Note that in the table above (Table 8), the applicability table 2530 applies to the normal HTTP method but MAY apply within a SCIM Bulk 2531 operation (via HTTP POST). 2533 Error example in response to a non-existent GET request. 2535 HTTP/1.1 404 NOT FOUND 2537 { 2538 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2539 "detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 2540 "status":"404 2541 } 2543 Error example in response to a PUT request. 2545 HTTP/1.1 400 BAD REQUEST 2547 { 2548 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2549 "scimType":"mutability" 2550 "detail":"Attribute 'id' is readOnly", 2551 "status":"400" 2552 } 2554 [[Editor's note: while the detail error codes seem to have consensus, 2555 there is a question about whether the error codes should be 2556 extensible so that individual service providers may define site 2557 specific codes. Should all scimTypes be URIs, so that scimTypes can 2558 be registered via IANA? Should there be a separate field defined for 2559 this purpose? Or, should custom signalling (for non-protocol/schema 2560 errors, be out of scope?]] 2562 3.11. API Versioning 2564 The Base URL MAY be appended with a version identifier as a separate 2565 segment in the URL path. At this time of this specification, the 2566 identifier is 'v2'. If specified, the version identifier MUST appear 2567 in the URL path immediately preceding the resource endpoint and 2568 conform to the following scheme: the character 'v' followed by the 2569 desired SCIM version number; e.g., a version 'v2' User request is 2570 specified as /v2/Users. When specified service providers MUST 2571 perform the operation using the desired version or reject the 2572 request. When omitted service providers SHOULD perform the operation 2573 using the most recent SCIM protocol version supported by the service 2574 provider. 2576 3.12. Versioning Resources 2578 The SCIM protocol supports resource versioning via standard HTTP 2579 ETags Section 2.3 [RFC7233]. Service providers MAY support weak 2580 ETags as the preferred mechanism for performing conditional 2581 retrievals and ensuring clients do not inadvertently overwrite each 2582 others changes, respectively. When supported SCIM ETags MUST be 2583 specified as an HTTP header and SHOULD be specified within the 2584 'version' attribute contained in the resource's 'meta' attribute. 2586 Example: 2588 POST /Users HTTP/1.1 2589 Host: example.com 2590 Content-Type: application/scim+json 2591 Authorization: Bearer h480djs93hd8 2592 Content-Length: ... 2594 { 2595 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2596 "userName":"bjensen", 2597 "externalId":"bjensen", 2598 "name":{ 2599 "formatted":"Ms. Barbara J Jensen III", 2600 "familyName":"Jensen", 2601 "givenName":"Barbara" 2602 } 2603 } 2605 The server responds with an ETag in the response header and meta 2606 structure. 2608 HTTP/1.1 201 Created 2609 Content-Type: application/scim+json 2610 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2611 ETag: W/"e180ee84f0671b1" 2613 { 2614 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2615 "id":"2819c223-7f76-453a-919d-413861904646", 2616 "meta":{ 2617 "resourceType":"User", 2618 "created":"2011-08-01T21:32:44.882Z", 2619 "lastModified":"2011-08-01T21:32:44.882Z", 2620 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2621 "version":"W\/\"e180ee84f0671b1\"" 2622 }, 2623 "name":{ 2624 "formatted":"Ms. Barbara J Jensen III", 2625 "familyName":"Jensen", 2626 "givenName":"Barbara" 2627 }, 2628 "userName":"bjensen" 2629 } 2631 With the returned ETag, clients MAY choose to retrieve the resource 2632 only if the resource has been modified. 2634 Conditional retrieval example using If-None-Match Section 3.2 2635 [RFC7233] header: 2637 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName 2638 Host: example.com 2639 Accept: application/scim+json 2640 Authorization: Bearer h480djs93hd8 2641 If-None-Match: W/"e180ee84f0671b1" 2643 If the resource has not changed the service provider simply returns 2644 an empty body with a 304 "Not Modified" response code. 2646 If the service providers supports versioning of resources the client 2647 MAY supply an If-Match Section 3.1 [RFC7233] header for PUT and PATCH 2648 operations to ensure that the requested operation succeeds only if 2649 the supplied ETag matches the latest service provider resource; e.g., 2650 If-Match: W/"e180ee84f0671b1" 2652 4. Preparation and Comparison of Internationalized Strings 2654 To increase the likelihood that the input and comparison of unicode 2655 usernames and passwords will work in ways that make sense for typical 2656 users throughout the world there are special string preparation and 2657 comparison methods (PRECIS) that MUST be followed for usernames and 2658 passwords. Before comparing or evaluating uniqueness of a "userName" 2659 or "password" attribute, service providers MUST use the "PRECIS" 2660 profile described in Sections 4 and 5 respectively of 2661 [I-D.ietf-precis-saslprepbis] and is based on the "PRECIS" framework 2662 specification [I-D.ietf-precis-framework]. 2664 5. Multi-Tenancy 2666 A single service provider may expose the SCIM protocol to multiple 2667 clients. Depending on the nature of the service, the clients may 2668 have authority to access and alter resources initially created by 2669 other clients. Alternatively, clients may expect to access disjoint 2670 sets of resources, and may expect that their resources are 2671 inaccessible by other clients. These scenarios are called "multi- 2672 tenancy", where each client is understood to be or represent a 2673 "tenant" of the service provider. Clients may also be multi- 2674 tenanted. 2676 The following common cases may occur: 2678 1. All clients share all resources (no tenancy) 2680 2. Each single client creates and accesses a private subset of 2681 resources (1 client:1 Tenant) 2683 3. Sets of clients share sets of resources (M clients:1 Tenant) 2685 4. One client to Multiple Tenants (1 client:M Tenants) 2687 Service providers may implement any subset of the above cases. 2689 Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a 2690 scheme for multi-tenancy. 2692 The SCIM protocol does not prescribe the mechanisms whereby clients 2693 and service providers interact for: 2695 o Registering or provisioning Tenants 2697 o Associating a subset of clients with a subset of the Tenants 2698 o Indicating which tenant is associated with the data in a request 2699 or response, or indicating which Tenant is the subject of a query 2701 5.1. Associating Clients to Tenants 2703 The service provider MAY use the authentication mechanism (Section 2) 2704 to determine the identity of the client, and thus infer the 2705 associated Tenant. 2707 For implementations where a client is associated with more than one 2708 Tenant, the service provider MAY use one of the following methods for 2709 explicit specification of the Tenant. 2711 If any of these methods of allowing the client to explicitly specify 2712 the Tenant are employed, the service provider should ensure that 2713 access controls are in place to prevent or allow cross-tenant use 2714 cases. 2716 The service provider should consider precedence in cases where a 2717 client may explicitly specify a Tenant while being implicitly 2718 associated with a different Tenant. 2720 In all of these methods, the {tenant_id} is a unique identifier for 2721 the Tenant as defined by the service provider. 2723 o A URL prefix: "https://www.example.com/Tenants/{tenant_id}/v2/ 2724 Users" 2726 o A sub-domain: "https://{tenant_id}.example.com/v2/Groups" 2728 o The service provider may recognize a {tenant_id} provided by the 2729 client in an HTTP Header as the indicator of the desired target 2730 Tenant. 2732 5.2. SCIM Identifiers with Multiple Tenants 2734 Considerations for a Multi-Tenant Implementation: 2736 The service provider may choose to implement SCIM ids which are 2737 unique across all resources for all Tenants, but this is not 2738 required. 2740 The externalId, defined by the client, is required to be unique ONLY 2741 within the resources associated with the associated Tenant. 2743 6. Security Considerations 2745 6.1. TLS Support 2747 The SCIM Protocol layers on top of Hypertext Transfer Protocol and 2748 thus subject to the security considerations of HTTP Section 9 2749 [RFC7230] and its related specifications. 2751 SCIM resources (e.g., Users and Groups) can contain sensitive 2752 information. Therefore, SCIM clients and service providers MUST 2753 implement TLS. Which version(s) ought to be implemented will vary 2754 over time, and depend on the widespread deployment and known security 2755 vulnerabilities at the time of implementation. At the time of this 2756 writing, TLS version 1.2 [RFC5246] is the most recent version, but 2757 has very limited actual deployment, and might not be readily 2758 available in implementation toolkits. TLS version 1.0 [RFC2246] is 2759 the most widely deployed version, and will give the broadest 2760 interoperability. 2762 6.2. Disclosure of Sensitive Information in URIs 2764 As mentioned in ,Section 9.4 [RFC7231], SCIM clients requesting 2765 information using query filters using HTTP GET SHOULD give 2766 consideration to the information content of the filters and whether 2767 their exposure in a URI would represent a breach of security or 2768 confidentiality through leakage in a web browsers or server logs. 2769 This is particularly true for information that is legally considered 2770 "personally identifiable information" or is otherwise restricted by 2771 privacy laws. In these situations to ensure maximum security and 2772 confidentiality, clients SHOULD query using HTTP POST (see 2773 Section 3.2.3 ). 2775 Servers that receive HTTP GET requests using filters that contain 2776 restricted or confidential information SHOULD respond with HTTP 2777 status 403 indicating the operation is FORBIDDEN. A detailed error, 2778 "confidential_restricted" may be returned indicating the request must 2779 be submitted using POST. A non-normative example: 2781 HTTP/1.1 403 FORBIDDEN 2783 { 2784 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2785 "Errors":[ 2786 { 2787 "description":"Query filter involving 'name' is restricted or confidential", 2788 "error":"confidential_restricted" 2789 } 2790 ] 2791 } 2793 6.3. HTTP Considerations 2795 As an HTTP based protocol, implementers of SCIM SHOULD consider all 2796 security considerations of the HTTP/1.1 as enumerated in Section 1 2797 [RFC7230] 2799 As stated in Section 2.7.1 [RFC7230], a SCIM client MUST NOT generate 2800 the userinfo (i.e. username and password) component (and its "@" 2801 delimiter) when an "http" URI reference is generated with a message 2802 as they are now disallowed in HTTP. 2804 6.4. Secure Storage and Handling of Sensitive Data 2806 An attacker may obtain valid username/password combinations from the 2807 SCIM service provider's underlying database by gaining access to the 2808 database and/or launching injection attacks. This could lead to 2809 unintended disclosure of username/password combinations. The impact 2810 may extend beyond the domain of the SCIM service provider if the data 2811 was provisioned from other domains. 2813 Administrators should undertake industry best practices to protect 2814 the storage of credentials and in particular SHOULD follow 2815 recommendations outlines in Section 5.1.4.1 [RFC6819]. These 2816 recommendations include but are not limited to: 2818 o Provide injection attack counter measures (e.g. by validating all 2819 inputs and parameters), 2821 o No cleartext storage of credentials, 2823 o Store credentials using an encrypted protection mechanism, and 2825 o Avoid passwords and consider use of asymmetric cryptography based 2826 credentials. 2828 As outlined in Section 5.1.4.2 [RFC6819], adminitrators SHOULD take 2829 counter measures to prevent online attacks on secrets such as: 2831 o Utilize secure password policy in order to increase user password 2832 entrophy to hinder online attacks and password guessing, 2834 o Mitigate attacks on passwords by locking respective accounts have 2835 a number of failed attempts, 2837 o Use "tar pit" techniques by temporarily locking a respective 2838 account and delaying responses for a certain duration. The 2839 duration may increase with the number of failed attempts, and 2841 o Use authentication system that use CAPTCHA's and other factors for 2842 authenticating users further reducing the possibility of automated 2843 attacks. 2845 6.5. Case Insensitive Comparision & International Languages 2847 When comparing unicode strings such as in query filters or testing 2848 for uniqueness of usernames and passwords, strings MUST be 2849 appopriately prepared before comparison. See Section 4. 2851 7. IANA Considerations 2853 7.1. Media Type Registration 2855 To: ietf-types@iana.org 2857 Subject: Registration of media type application/scim+json 2859 Type name: application 2861 Subtype name: scim+json 2863 Required parameters: none 2865 Optional parameters: none 2867 Encoding considerations: 8bit 2869 Security considerations: See Section 6 2871 Interoperability considerations: The "application/scim+json" media 2872 type is intended to identify JSON structure data that conforms to 2873 the SCIM protocol and schema specifications. Older versions of 2874 SCIM are known to informally use "application/json". 2876 Published specification: [[this document]] 2878 Applications that use this media type: It is expected that 2879 applications that use this type may be special purpose 2880 applications intended for inter-domain provisioning. Clients may 2881 also be applications (e.g. mobile applications) that need to use 2882 SCIM for self-registration of user accounts. SCIM services may be 2883 offered by web applications that offer support for standards based 2884 provisioning or may be a dedicated SCIM service provider such as a 2885 "cloud directory". Content may be treated as equivalent to 2886 "application/json" type for the purpose of displaying in web 2887 browsers. 2889 Additional information: 2891 Magic number(s): 2893 File extension(s): .scim .scm 2895 Macintosh file type code(s): 2897 Person & email address to contact for futher information: SCIM 2898 mailing list "" 2900 Intended usage: COMMON* (see restrictions) 2902 Restrictions on usage: For most client types, it is sufficient to 2903 recognize the content as equivalent to "application/json". 2904 Applications intending to use SCIM protocol SHOULD use the 2905 application/scim+json media type. 2907 Author: Phil Hunt 2909 Change controller: IETF 2911 7.2. SCIM Message URI Registry 2913 As per the IANA SCIM Schema Registry in [I-D.ietf-scim-core-schema], 2914 the following registers and extends the SCIM Schema Registry to 2915 define SCIM protocol request/response JSON schema URN identifier 2916 prefix of "urn:ietf:params:scim:api:messages:2.0" which is part of 2917 the URN sub-Namespace for SCIM. There is no specific associated 2918 resource type. 2920 +---------------------------------+-----------------+---------------+ 2921 | Schema URI | Name | Reference | 2922 +---------------------------------+-----------------+---------------+ 2923 | urn:ietf:params:scim:api: | List/Query | See Section | 2924 | messages:2.0:ListResponse | Response | 3.2.2 | 2925 | urn:ietf:params:scim:api: | POST Query | See Section | 2926 | messages:2.0:SearchRequest | Request | 3.2.3 | 2927 | urn:ietf:params:scim:api: | Patch Operation | See Section | 2928 | messages:2.0:PatchOp | | 3.3.2 | 2929 | urn:ietf:params:scim:api: | Bulk Operations | See Section | 2930 | messages:2.0:BulkRequest | Request | 3.5 | 2931 | urn:ietf:params:scim:api: | Bulk Operations | See Section | 2932 | messages:2.0:BulkResponse | Response | 3.5 | 2933 | urn:ietf:params:scim:api: | Error Response | See Section | 2934 | messages:2.0:Error | | 3.10 | 2935 +---------------------------------+-----------------+---------------+ 2937 Table 9: SCIM Schema URIs for Data Resources 2939 8. References 2941 8.1. Normative References 2943 [I-D.ietf-precis-saslprepbis] 2944 Saint-Andre, P. and A. Melnikov, "Preparation and 2945 Comparison of Internationalized Strings Representing 2946 Usernames and Passwords", draft-ietf-precis-saslprepbis-07 2947 (work in progress), March 2014. 2949 [I-D.ietf-scim-core-schema] 2950 Grizzle, K., Hunt, P., Wahlstroem, E., and C. Mortimore, 2951 "System for Cross-Domain Identity Management: Core 2952 Schema", draft-ietf-scim-core-schema-09 (work in 2953 progress), August 2014. 2955 [IANA.Language] 2956 Internet Assigned Numbers Authority (IANA), "Language 2957 Subtag Registry", 2005. 2959 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2960 Requirement Levels", BCP 14, RFC 2119, March 1997. 2962 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2963 RFC 2246, January 1999. 2965 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2966 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2967 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2969 [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of 2970 Internationalized Strings ("stringprep")", RFC 3454, 2971 December 2002. 2973 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2974 10646", STD 63, RFC 3629, November 2003. 2976 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2977 Resource Identifier (URI): Generic Syntax", STD 66, RFC 2978 3986, January 2005. 2980 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2981 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2983 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2984 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2986 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 2987 5789, March 2010. 2989 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 2990 Interchange Format", RFC 7159, March 2014. 2992 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2993 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 2994 2014. 2996 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2997 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 2999 [RFC7233] Fielding, R., Lafon, Y., and J. Reschke, "Hypertext 3000 Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, 3001 June 2014. 3003 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3004 (HTTP/1.1): Authentication", RFC 7235, June 2014. 3006 8.2. Informative References 3008 [I-D.ietf-precis-framework] 3009 Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 3010 Preparation and Comparison of Internationalized Strings in 3011 Application Protocols", draft-ietf-precis-framework-17 3012 (work in progress), May 2014. 3014 [I-D.reschke-http-status-308] 3015 Reschke, J., "The Hypertext Transfer Protocol (HTTP) 3016 Status Code 308 (Permanent Redirect)", draft-reschke-http- 3017 status-308-07 (work in progress), March 2012. 3019 [OpenSearch] 3020 Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . 3022 [Order-Operations] 3023 Wikipedia, "Order of Operations: Programming Languages", . 3025 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 3026 Languages", BCP 18, RFC 2277, January 1998. 3028 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 3029 Framework: Bearer Token Usage", RFC 6750, October 2012. 3031 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 3032 Threat Model and Security Considerations", RFC 6819, 3033 January 2013. 3035 [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation 3036 (JSON) Patch", RFC 6902, April 2013. 3038 Appendix A. Contributors 3040 Samuel Erdtman (samuel@erdtman.se) 3042 Patrick Harding (pharding@pingidentity.com) 3044 Appendix B. Acknowledgments 3046 The editors would like to acknowledge the contribution and work of 3047 the past draft editors: 3049 Trey Drake, UnboundID 3051 Chuck Mortimore, Salesforce 3053 The editor would like to thank the participants in the the SCIM 3054 working group for their support of this specification. 3056 Appendix C. Change Log 3058 [[This section to be removed prior to publication as an RFC]] 3060 Draft 02 - KG - Addition of schema extensibility 3061 Draft 03 - PH - Revisions based on following tickets: 3063 24 - Add filter negation 3065 39 - Clarification on response for DELETE 3067 42 - Make root searches optional 3069 49 - Add "ew" filter 3071 50 - Filters for multi-valued complex attributes 3073 51 - Search by Schema 3075 53 - Standard use of term client (some was consumer) 3077 55 - Redirect support (3xx) 3079 56 - Make manager attribute consistent with other $ref attrs 3081 57 - Update all "/v1" examples to '/v2" 3083 59 - Fix capitalization per IETF editor practices 3085 60 - Changed tags to normal and tags 3087 Draft 04 - PH - Revisions based on the following tickets: 3089 18 - New PATCH command based on JSON Patch (RFC6902) 3091 - Provided ABNF specification for filters (used in PATCH) 3093 - Updated references to RFC4627 to RFC7159 3095 Draft 05 - PH - Revisions based on the following tickets: 3097 03 - Support for excludedAttributes parameter 3099 13 - Change client use of Etags from MUST to MAY (correction) 3101 23 - Clarifications regarding case exact processing. 3103 41 - Add IANA considerations 3105 65 - Removed X-HTTP-Method-Override support 3107 69 - Added clarifications to intro to align with draft-nottingham- 3108 uri-get-off-my-lawn 3109 70 - Remove SCIM_TENANT_ID header 3111 72 - Added text to indicate UTF-8 is default and mandatory 3112 encoding format per BCP18 3114 74 - Added security considerations for using GET with confidential 3115 attribute filters 3117 - corrected error response in JSON PATCH operation 3119 Draft 06 - PH - Revisions based on the following tickets and 3120 editorial changes 3122 41 - Revised content types from application/json to application/ 3123 scim+json, registered API schemas 3125 63 - Revised uri schema prefixes for API json message schemas 3127 66 - Updated references for RFC2616 to HTTPbis 3129 75 - Added security considerations for International Strings and 3130 "PRECIS" support 3132 76 - Clarified handling of PUT (& POST) with regards to mutability 3133 and default values 3135 - Corrected version numbers in sec 3.11 API Versioning to v2 (from 3136 v1) 3138 - Clarified that no filter matches should return success 3139 totalResults=0 3141 Draft 07 - PH - Revisions regarding support of detailed errors 3142 (Tickets 37, 46, 67) 3144 Draft 08 - PH - Revisions as follows 3146 - Added clarification on schemas handling during PATCH operation 3148 - Revised example URN in Attribute Notation section to comply with 3149 IANA namespace rules 3151 - Fixed typo in ABNF, attrExpr should be attrExp 3153 - Added more security considerations for HTTP and sensitive data 3155 - Revised authentication and authorization sections for greater 3156 clarity. 3158 - Replaced the word "search" with "query" for consistency 3160 - Clarified sucessful resource creation response 3162 - Added clarification on primary value handling in PATCH 3163 (consistent with draft 03) 3165 - Revised SCIM Bullk error handling to conform with draft 07 error 3166 handling 3168 Draft 09 - PH - Revisions as follows 3170 - Aligned API with new URN namespace per RFC3553 and IETF90 3171 meeting 3173 - Clarified URN usage within patch (what schema urn applies) 3175 - Made 'path' optional in PATCH for Add and Replace 3177 Draft 10 - PH - Revisions as follows 3179 Restructuring of Bulk into sub-sections 3181 General clarifications 3183 Improved Base URI section 3185 Authorization section clarifications 3187 Authors' Addresses 3189 Phil Hunt (editor) 3190 Oracle Corporation 3192 Email: phil.hunt@yahoo.com 3194 Kelly Grizzle 3195 SailPoint 3197 Email: kelly.grizzle@sailpoint.com 3199 Morteza Ansari 3200 Cisco 3202 Email: morteza.ansari@cisco.com 3203 Erik Wahlstroem 3204 Technology Nexus 3206 Email: erik.wahlstrom@nexusgroup.com 3208 Chuck Mortimore 3209 Salesforce.com 3211 Email: cmortimore@salesforce.com