idnits 2.17.1 draft-ietf-scim-api-13.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 17, 2014) is 3447 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) == Outdated reference: A later version (-18) exists of draft-ietf-precis-saslprepbis-09 == Outdated reference: A later version (-22) exists of draft-ietf-scim-core-schema-13 ** 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-19 -- Obsolete informational reference (is this intentional?): RFC 7238 (Obsoleted by RFC 7538) Summary: 6 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). 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: May 21, 2015 SailPoint 6 M. Ansari 7 Cisco 8 E. Wahlstroem 9 Nexus Technology 10 C. Mortimore 11 Salesforce 12 November 17, 2014 14 System for Cross-Domain Identity Management: Protocol 15 draft-ietf-scim-api-13 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 May 21, 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 . . . . . . . . . . . . . 9 76 3.2.2. Query Resources . . . . . . . . . . . . . . . . . . . 10 77 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 21 78 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 24 79 3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 25 80 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 27 81 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 40 82 3.5. Bulk Operations . . . . . . . . . . . . . . . . . . . . . 41 83 3.5.1. Circular Reference Processing . . . . . . . . . . . . 43 84 3.5.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 46 85 3.5.3. Response and Error Handling . . . . . . . . . . . . . 50 86 3.5.4. Maximum Operations . . . . . . . . . . . . . . . . . 56 87 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 57 88 3.7. Additional Operation Response Parameters . . . . . . . . 58 89 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 59 90 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 59 91 3.10. HTTP Status and Error Response Handling . . . . . . . . . 60 92 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 64 93 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 64 94 4. Preparation and Comparison of Internationalized Strings . . . 66 95 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 66 96 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 67 97 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 68 98 6. Security Considerations . . . . . . . . . . . . . . . . . . . 68 99 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 68 100 6.2. Disclosure of Sensitive Information in URIs . . . . . . . 68 101 6.3. Anonymous Requests . . . . . . . . . . . . . . . . . . . 69 102 6.4. HTTP Considerations . . . . . . . . . . . . . . . . . . . 69 103 6.5. Secure Storage and Handling of Sensitive Data . . . . . . 70 104 6.6. Case Insensitive Comparision & International Languages . 71 105 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 71 106 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 71 107 7.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 72 108 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 73 109 8.1. Normative References . . . . . . . . . . . . . . . . . . 73 110 8.2. Informative References . . . . . . . . . . . . . . . . . 74 111 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 74 112 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 74 113 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 75 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 78 116 1. Introduction and Overview 118 The SCIM Protocol is an application-level, HTTP protocol for 119 provisioning and managing identity data on the web and in cross- 120 domain environments such as enterprise to cloud, or inter-cloud 121 scenarios. The protocol supports creation, modification, retrieval, 122 and discovery of core identity resources such as Users and Groups, as 123 well as custom resources and resource extensions. 125 1.1. Intended Audience 127 This document is intended as a guide to SCIM protocol usage for both 128 SCIM HTTP service providers and HTTP clients who may provision 129 information to service providers or retrieve information from them. 131 1.2. Notational Conventions 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 135 document are to be interpreted as described in [RFC2119]. These 136 keywords are capitalized when used to unambiguously specify 137 requirements of the protocol or application features and behavior 138 that affect the interoperability and security of implementations. 139 When these words are not capitalized, they are meant in their 140 natural-language sense. 142 For purposes of readability examples are not URL encoded. 143 Implementers MUST percent encode URLs as described in Section 2.1 of 144 [RFC3986]. 146 Throughout this documents all figures MAY contain spaces and extra 147 line-wrapping for readability and space limitations. Similarly, some 148 URI's contained within examples, have been shortened for space and 149 readability reasons. 151 1.3. Definitions 153 Base URI 154 The SCIM HTTP protocol is described in terms of a path relative to 155 a Base URI. The Base URI MUST NOT contain a query string as 156 clients may append additional path information and query 157 parameters as part of forming the request. The base URI most 158 often is a URL which most often consists of the "https" protocol 159 scheme, a domain name and some initial path [RFC3986]. Example: 160 "https://example.com/scim/" 162 For readability, all examples in this document are expressed 163 assuming the SCIM service root and the server root are the same 164 (no path pre-fix). It is expected that SCIM servers may be 165 deployed using any URI path prefix. For example, a SCIM server 166 might be have a prefix of "https://example.com/", or 167 "https://example.com/scim/tenancypath/". Additionally client may 168 also apply a version number to the server root prefix (see 169 Section 3.11 ). 171 2. Authentication and Authorization 173 Because SCIM builds on the HTTP protocol, it does not itself define a 174 scheme for authentication and authorization. SCIM depends on 175 standard HTTP authentication schemes. Implementers SHOULD support 176 existing authentication/authorization schemes. In particular, OAuth2 177 (see [RFC6749], [RFC6750]) is RECOMMENDED. Appropriate security 178 considerations of the selected authentication and authorization 179 schemes SHOULD be taken. Because this protocol uses HTTP response 180 status codes as the primary means of reporting the result of a 181 request, servers are advised to respond to unauthorized or 182 unauthenticated requests using the 401 response code in accordance 183 with Section 3.1 of [RFC7235]. 185 All examples show an OAuth2 bearer token [RFC6750] (though it is not 186 required); e.g., 188 GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 189 Host: example.com 190 Authorization: Bearer h480djs93hd8 192 When processing requests, the service provider SHOULD consider the 193 subject performing the request and whether the action is appropriate 194 given the subject and the resource affected by the request. The 195 subject performing the request is usually determined from the 196 "Authorization" header present in the request. 198 3. SCIM Protocol 200 The SCIM protocol specifies well-known endpoints and HTTP methods for 201 managing resources defined in the core schema; i.e., "User" and 202 "Group" resources correspond to "/Users" and "/Groups" respectively. 203 Service providers that support extended resources SHOULD define 204 resource endpoints using the convention of pluralizing the resource 205 name defined in the extended schema by appending an 's'. Given there 206 are cases where resource pluralization is ambiguous; e.g., a resource 207 named "Person" is legitimately "Persons" and "People". Clients 208 SHOULD discover resource endpoints via the "/ResourceTypes" endpoint. 210 GET 211 Retrieves one or more complete or partial resources. 213 POST 214 Depending on the endpoint, creates new resources, create a search 215 request, or may be used to bulk modify resources. 217 PUT 218 Modifies a resource by replacing existing attributes with a 219 specified set of replacement attributes (replace). PUT MUST NOT 220 be used to create new resources. 222 PATCH 223 Modifies a resource with a set of client specified changes 224 (partial update). 226 DELETE 227 Deletes a resource. 229 Resource Endpoint Operations Description 230 -------- ---------------- ---------------------- -------------------- 231 User /Users GET (Section 3.2.1), Retrieve, Add, 232 POST (Section 3.1), Modify Users 233 PUT (Section 3.3.1), 234 PATCH (Section 3.3.2), 235 DELETE (Section 3.4) 236 Group /Groups GET (Section 3.2.1), Retrieve, Add, 237 POST (Section 3.1), Modify Groups 238 PUT (Section 3.3.1), 239 PATCH (Section 3.3.2), 240 DELETE (Section 3.4) 241 Service /ServiceProvider GET (Section 3.2.1) Retrieve service 242 Provider Configs provider's 243 Config configuration 244 Resource /ResourceTypes GET (Section 3.2.1) Retrieve supported 245 Type resource types 246 Schema /Schemas GET (Section 3.2.1) Retrieve one or more 247 supported schemas. 248 Bulk /Bulk POST (Section 3.5) Bulk updates to one 249 or more resources 250 Search [prefix]/.search POST (Section 3.2.3) Search from system 251 root or within a 252 resource endpoint 253 for one or more 254 resource types using 255 POST. 257 Table 1: Defined endpoints 259 All requests to the service provider are made via HTTP Methods as per 260 Section 4.3 [RFC7231] on a URL derived from the Base URL. Responses 261 are returned in the body of the HTTP response, formatted as JSON. 262 Error status codes SHOULD be transmitted via the HTTP status code of 263 the response (if possible), and SHOULD also be specified in the body 264 of the response (see Section 3.10). 266 3.1. Creating Resources 268 To create new resources, clients send HTTP POST requests to the 269 resource endpoint such as: "/Users" or "/Groups". 271 The server SHALL process attributes according to the following 272 mutability rules: 274 o For attributes in the request body, whose mutability is 275 "readOnly", SHALL be ignored. 277 o For attributes whose mutability is "readWrite", that are omitted 278 from the request body, MAY be assumed to be not asserted by the 279 client. The service provider MAY assign a default value to non- 280 asserted attributes in the final resource representation. 282 o Service providers MAY take into account whether a client has 283 access to, or understands, all of the resource's attributes when 284 deciding whether non-asserted attributes should be defaulted. 285 Clients that intend to override server defaulted values for 286 attributes MAY specify "null" for a single-valued attribute or an 287 empty array "[]" for a multi-valued attribute to clear all values. 289 When the service provider successfully creates the new resource, an 290 HTTP response SHALL be returned with HTTP status "201" ("Created"). 291 The response body SHOULD contain the service provider's 292 representation of the newly created resource. The URI of the created 293 resource SHALL included in the HTTP "Location" header and in JSON 294 resource representation under the attribute "meta.location". Since 295 the server is free to alter and/or ignore POSTed content, returning 296 the full representation can be useful to the client, enabling it to 297 correlate the client and server views of the new resource. 299 If the service provider determines creation of the requested resource 300 conflicts with existing resources; e.g., a "User" resource with a 301 duplicate "userName", the service provider MUST return an HTTP Status 302 409, with "scimType" error code of "uniqueness" as per Section 3.10. 304 Below, in the following example, a client sends a POST request 305 containing a "User" to the "/Users" endpoint. 307 POST /Users HTTP/1.1 308 Host: example.com 309 Accept: application/scim+json 310 Content-Type: application/scim+json 311 Authorization: Bearer h480djs93hd8 312 Content-Length: ... 314 { 315 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 316 "userName":"bjensen", 317 "externalId":"bjensen", 318 "name":{ 319 "formatted":"Ms. Barbara J Jensen III", 320 "familyName":"Jensen", 321 "givenName":"Barbara" 322 } 323 } 324 In response to the example request above, the server signals a 325 successful creation with an HTTP status code 201 (Created) and 326 returns a representation of the resource created. 328 HTTP/1.1 201 Created 329 Content-Type: application/scim+json 330 Location: 331 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 332 ETag: W/"e180ee84f0671b1" 334 { 335 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 336 "id":"2819c223-7f76-453a-919d-413861904646", 337 "externalId":"bjensen", 338 "meta":{ 339 "resourceType":"User", 340 "created":"2011-08-01T21:32:44.882Z", 341 "lastModified":"2011-08-01T21:32:44.882Z", 342 "location": 343 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 344 "version":"W\/\"e180ee84f0671b1\"" 345 }, 346 "name":{ 347 "formatted":"Ms. Barbara J Jensen III", 348 "familyName":"Jensen", 349 "givenName":"Barbara" 350 }, 351 "userName":"bjensen" 352 } 354 3.1.1. Resource Types 356 When adding a resource to a specific endpoint, the meta attribute 357 "resourceType" SHALL be set by the HTTP service provider to the 358 corresponding resource type for the endpoint. For example, "/Users" 359 will set "resourceType" to "User", and "/Groups" will set 360 "resourceType" to "Group". 362 3.2. Retrieving Resources 364 Resources are retrieved via opaque, unique URLs or via Query. The 365 attributes returned are defined in the server's attribute schema (see 366 Section 10 [I-D.ietf-scim-core-schema]) and request parameters (see 367 Section 3.7). By default, resource attributes returned in a response 368 are those whose schema "returned" setting is "always" or "default". 370 3.2.1. Retrieving a known Resource 372 To retrieve a known resource, clients send GET requests to the 373 resource endpoint; e.g., "/Users/{id}" or "/Groups/{id}", or 374 "/Schemas/{id}". 376 If the resource exists the server responds with HTTP Status code 200 377 (OK) and includes the result in the body of the response. 379 The below example retrieves a single User via the "/Users" endpoint. 381 GET /Users/2819c223-7f76-453a-919d-413861904646 382 Host: example.com 383 Accept: application/scim+json 384 Authorization: Bearer h480djs93hd8 386 The server responds with: 388 HTTP/1.1 200 OK 389 Content-Type: application/scim+json 390 Location: 391 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 392 ETag: W/"f250dd84f0671c3" 394 { 395 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 396 "id":"2819c223-7f76-453a-919d-413861904646", 397 "externalId":"bjensen", 398 "meta":{ 399 "resourceType":"User", 400 "created":"2011-08-01T18:29:49.793Z", 401 "lastModified":"2011-08-01T18:29:49.793Z", 402 "location": 403 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 404 "version":"W\/\"f250dd84f0671c3\"" 405 }, 406 "name":{ 407 "formatted":"Ms. Barbara J Jensen III", 408 "familyName":"Jensen", 409 "givenName":"Barbara" 410 }, 411 "userName":"bjensen", 412 "phoneNumbers":[ 413 { 414 "value":"555-555-8377", 415 "type":"work" 416 } 417 ], 418 "emails":[ 419 { 420 "value":"bjensen@example.com", 421 "type":"work" 422 } 423 ] 424 } 426 3.2.2. Query Resources 428 The SCIM protocol defines a standard set of query parameters that can 429 be used to filter, sort, and paginate to return zero or more 430 resources in a query response. Queries MAY be made against a single 431 resource or a resource type endpoint (e.g. "/Users"). SCIM service 432 providers MAY support additional query parameters not specified here 433 and SHOULD ignore any query parameters they do not recognize. 435 Responses MUST be identified using the following URI: 436 "urn:ietf:params:scim:api:messages:2.0:ListResponse". The following 437 attributes are defined for responses: 439 totalResults The total number of results returned by the list or 440 query operation. This may not be equal to the number of elements 441 in the resources attribute of the list response if pagination 442 (Section 3.2.2.4) is requested. REQUIRED. 444 Resources A multi-valued list of complex objects containing the 445 requested resources. This may be a subset of the full set of 446 resources if pagination (Section 3.2.2.4) is requested. REQUIRED 447 if "totalResults" is non-zero. 449 startIndex The 1-based index of the first result in the current set 450 of list results. REQUIRED when partial results returned due to 451 pagination. 453 itemsPerPage The number of resources returned in a list response 454 page. REQUIRED when partial results returned due to pagination. 456 A query that does not return any matches SHALL return success (HTTP 457 Status 200) with "totalResults" set to a value of 0. 459 The query example below requests the userName for all Users: 461 GET /Users?attributes=userName 462 Host: example.com 463 Accept: application/scim+json 464 Authorization: Bearer h480djs93hd8 466 The following is an example response to the query above: 468 HTTP/1.1 200 OK 469 Content-Type: application/scim+json 471 { 472 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 473 "totalResults":2, 474 "Resources":[ 475 { 476 "userName":"bjensen" 477 }, 478 { 479 "userName":"jsmith" 480 } 481 ] 482 } 484 3.2.2.1. Query Endpoints 486 Queries MAY be performed against a SCIM resource object, a resource 487 type endpoint, or a SCIM server root. For example: 489 "/Users/{id}" 491 "/Users" 493 "/Groups" 495 A query against a server root indicates that ALL resources within the 496 server SHALL be included subject to filtering. A filter expression 497 using "meta.resourceType" MAY be used to restrict results to one or 498 more specific resource types (to exclude others). For example: 500 filter=(meta.resourceType eq User) or (meta.resourceType eq Group) 502 If a SCIM service provider determines that too many results would be 503 returned (e.g. because a client queried a resource type endpoint or 504 the server base URI), the server SHALL reject the request by 505 returning an HTTP response with "status" 400 and json attribute 506 "scimType" set to "tooMany" (see Table 8). 508 When processing query operations across endpoints that include more 509 than one SCIM resource type (e.g. a query from the server root 510 endpoint), filters MUST be processed as outlined in Section 3.2.2.2. 511 For filtered attributes that are not part of a particular resource 512 type, the service provider SHALL treat the attribute as if there is 513 no attribute value. For example, a presence or equality filter for 514 an undefined attribute evaluates as FALSE. 516 3.2.2.2. Filtering 518 Filtering is an OPTIONAL parameter for SCIM service providers. 519 Clients MAY discover service provider filter capabilities by looking 520 at the "filter" attribute of the "ServiceProviderConfig" (see 521 Section 8 [I-D.ietf-scim-core-schema]). Clients MAY request a subset 522 of resources by specifying the "filter" query parameter containing a 523 filter expression. When specified only those resources matching the 524 filter expression SHALL be returned. The expression language that is 525 used in the filter parameter supports references to attributes and 526 literals. 528 Attribute names and attribute operators used in filters are case 529 insensitive. For example, the following two expressions will 530 evaluate to the same logical value: 532 filter=userName Eq "john" 534 filter=Username eq "john" 536 The filter parameter MUST contain at least one valid Boolean 537 expression. Each expression MUST contain an attribute name followed 538 by an attribute operator and optional value. Multiple expressions 539 MAY be combined using the two logical operators. Furthermore 540 expressions can be grouped together using "()". 542 The operators supported in the expression are listed in the following 543 table. 545 +----------+-------------+------------------------------------------+ 546 | Operator | Description | Behavior | 547 +----------+-------------+------------------------------------------+ 548 | eq | equal | The attribute and operator values must | 549 | | | be identical for a match. | 550 | ne | not equal | The attribute and operator values are | 551 | | | not identical. | 552 | co | contains | The entire operator value must be a | 553 | | | substring of the attribute value for a | 554 | | | match. | 555 | sw | starts with | The entire operator value must be a | 556 | | | substring of the attribute value, | 557 | | | starting at the beginning of the | 558 | | | attribute value. This criterion is | 559 | | | satisfied if the two strings are | 560 | | | identical. | 561 | ew | ends with | The entire operator value must be a | 562 | | | substring of the attribute value, | 563 | | | matching at the end of the attribute | 564 | | | value. This criterion is satisfied if | 565 | | | the two strings are identical. | 566 | pr | present | If the attribute has a non-empty or non- | 567 | | (has value) | null value, or if it contains a non- | 568 | | | empty node for complex attributes there | 569 | | | is a match. | 570 | gt | greater | If the attribute value is greater than | 571 | | than | operator value, there is a match. The | 572 | | | actual comparison is dependent on the | 573 | | | attribute type. For string attribute | 574 | | | types, this is a lexicographical | 575 | | | comparison and for DateTime types, it is | 576 | | | a chronological comparison. For Integer | 577 | | | attributes it is a comparison by numeric | 578 | | | value. Boolean and Binary attributes | 579 | | | SHALL cause a failed response (HTTP | 580 | | | Status 400) with scimType of | 581 | | | invlaidFiler. | 582 | ge | greater | If the attribute value is greater than | 583 | | than or | or equal to the operator value, there is | 584 | | equal | a match. The actual comparison is | 585 | | | dependent on the attribute type. For | 586 | | | string attribute types, this is a | 587 | | | lexicographical comparison and for | 588 | | | DateTime types, it is a chronological | 589 | | | comparison. For Integer attributes it is | 590 | | | a comparison by numeric value. Boolean | 591 | | | and Binary attributes SHALL cause a | 592 | | | failed response (HTTP Status 400) with | 593 | | | scimType of invlaidFiler. | 594 | lt | less than | If the attribute value is less than | 595 | | | operator value, there is a match. The | 596 | | | actual comparison is dependent on the | 597 | | | attribute type. For string attribute | 598 | | | types, this is a lexicographical | 599 | | | comparison and for DateTime types, it is | 600 | | | a chronological comparison. For Integer | 601 | | | attributes it is a comparison by numeric | 602 | | | value. Boolean and Binary attributes | 603 | | | SHALL cause a failed response (HTTP | 604 | | | Status 400) with scimType of | 605 | | | invlaidFiler. | 606 | le | less than | If the attribute value is less than or | 607 | | or equal | equal to the operator value, there is a | 608 | | | match. The actual comparison is | 609 | | | dependent on the attribute type. For | 610 | | | string attribute types, this is a | 611 | | | lexicographical comparison and for | 612 | | | DateTime types, it is a chronological | 613 | | | comparison. For Integer attributes it is | 614 | | | a comparison by numeric value. Boolean | 615 | | | and Binary attributes SHALL cause a | 616 | | | failed response (HTTP Status 400) with | 617 | | | scimType of invlaidFiler. | 618 +----------+-------------+------------------------------------------+ 620 Table 2: Attribute Operators 622 +----------+-------------+------------------------------------------+ 623 | Operator | Description | Behavior | 624 +----------+-------------+------------------------------------------+ 625 | and | Logical And | The filter is only a match if both | 626 | | | expressions evaluate to true. | 627 | or | Logical or | The filter is a match if either | 628 | | | expression evaluates to true. | 629 | not | Not | The filter is a match if the expression | 630 | | function | evaluates to false. | 631 +----------+-------------+------------------------------------------+ 633 Table 3: Logical Operators 635 +----------+-------------+------------------------------------------+ 636 | Operator | Description | Behavior | 637 +----------+-------------+------------------------------------------+ 638 | ( ) | Precedence | Boolean expressions may be grouped using | 639 | | grouping | parentheses to change the standard order | 640 | | | of operations; i.e., evaluate OR logical | 641 | | | operators before logical AND operators. | 642 | [ ] | Complex | Service providers MAY support complex | 643 | | attribute | filters where expressions MUST be | 644 | | filter | applied to the same value of a parent | 645 | | grouping | attribute specified immediately before | 646 | | | the left square bracket ("["). The | 647 | | | expression within square brackets ("[" | 648 | | | and "]") MUST be a valid filter | 649 | | | expression based upon sub-attributes of | 650 | | | the parent attribute. Nested expressions | 651 | | | MAY be used. See examples below. | 652 +----------+-------------+------------------------------------------+ 654 Table 4: Grouping Operators 656 SCIM filters MUST conform to the following ABNF rules as per 657 [RFC5234] below: 659 FILTER = attrExp / logExp / valuePath / *1"not" "(" FILTER ")" 661 valuePath = attrPath "[" FILTER "]" 662 ; FILTER uses sub-attribs of a parent attrPath 664 ATTRNAME = ALPHA *(nameChar) 666 nameChar = "-" / "_" / DIGIT / ALPHA 668 attrPath = [URI ":"] ATTRNAME *1subAttr 669 ; SCIM attribute name 670 ; URI is SCIM "schema" URI 672 subAttr = "." ATTRNAME 673 ; a sub-attribute of a complex attribute 675 attrExp = (attrPath SP "pr") / 676 (attrPath SP compareOp SP compValue) 678 compValue = false / null / true / number / string 679 ; rules from JSON (RFC7159) 681 compareOp = "eq" / "ne" / "co" / 682 "sw" / "ew" / 683 "gt" / "lt" / 684 "ge" / "le" 686 logExp = FILTER ("and" / "or") FILTER 688 Figure 1: ABNF Specification of SCIM Filters 690 In the above ABNF, the "compValue" (comparison value) rule is built 691 on JSON Data Interchange format ABNF rules as specified in [RFC7159], 692 "DIGIT" and "ALPHA" are defined per Appendix B.1 of [RFC5234] and, 693 "URI" is defined per Appendix A of [RFC3986]. 695 Filters MUST be evaluated using standard order of operations 696 [Order-Operations]. Attribute operators have the highest precedence, 697 followed by the grouping operator (i.e, parentheses), followed by the 698 logical AND operator, followed by the logical OR operator. 700 If the specified attribute in a filter expression is a multi-valued 701 attribute, the resource MUST match if any of the instances of the 702 given attribute match the specified criterion; e.g. if a User has 703 multiple emails values, only one has to match for the entire User to 704 match. For complex attributes, a fully qualified Sub-Attribute MUST 705 be specified using standard attribute notation (Section 3.8). For 706 example, to filter by userName the parameter value is userName and to 707 filter by first name, the parameter value is name.givenName. 709 Providers MAY support additional filter operations if they choose. 710 Providers MUST decline to filter results if the specified filter 711 operation is not recognized and return a HTTP 400 error with an 712 appropriate human readable response. For example, if a client 713 specified an unsupported operator named 'regex' the service provider 714 should specify an error response description identifying the client 715 error; e.g., 'The operator 'regex' is not supported.' 717 String type attributes are case insensitive by default unless the 718 attribute type is defined as case exact. Attribute comparison 719 operators 'eq', 'co', and 'sw' MUST perform caseIgnore matching for 720 all string attributes unless the attribute is defined as case exact. 721 By default all string attributes are case insensitive. 723 Clients MAY query by schema or schema extensions by using a filter 724 expression including the "schemas" attribute. 726 The following are examples of valid filters. Some attributes (e.g. 727 rooms and rooms.number) are hypothetical extensions and are not part 728 of SCIM core schema: 730 filter=userName eq "bjensen" 732 filter=name.familyName co "O'Malley" 734 filter=userName sw "J" 736 filter=title pr 738 filter=meta.lastModified gt "2011-05-13T04:42:34Z" 740 filter=meta.lastModified ge "2011-05-13T04:42:34Z" 742 filter=meta.lastModified lt "2011-05-13T04:42:34Z" 744 filter=meta.lastModified le "2011-05-13T04:42:34Z" 746 filter=title pr and userType eq "Employee" 748 filter=title pr or userType eq "Intern" 750 filter= 751 schemas eq "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" 753 filter=userType eq "Employee" and (emails co "example.com" or emails 754 co "example.org") 756 filter=userType ne "Employee" and not (emails co "example.com" or 757 emails co "example.org") 759 filter=userType eq "Employee" and (emails.type eq "work") 761 filter=userType eq "Employee" and emails[type eq "work" and 762 value co "@example.com"] 764 filter=emails[type eq "work" and value co "@example.com"] or 765 ims[type eq "xmpp" and value co "@foo.com"] 767 filter=addresses[state eq "CA" and rooms[type eq "bedroom" and 768 number gt 2]] 770 Figure 2: Example Filters 772 3.2.2.3. Sorting 774 Sort is OPTIONAL. Sorting allows clients to specify the order in 775 which resources are returned by specifying a combination of sortBy 776 and sortOrder URL parameters. 778 sortBy: The sortBy parameter specifies the attribute whose value 779 SHALL be used to order the returned responses. If the sortBy 780 attribute corresponds to a singular attribute, resources are 781 sorted according to that attribute's value; if it's a multi-valued 782 attribute, resources are sorted by the value of the primary 783 attribute (see Section 2.2 [I-D.ietf-scim-core-schema]), if any, 784 or else the first value in the list, if any. If the attribute is 785 complex the attribute name must be a path to a sub-attribute in 786 standard attribute notation (Section 3.8) ; e.g., 787 "sortBy=name.givenName". For all attribute types, if there is no 788 data for the specified "sortBy" value they are sorted via the 789 "sortOrder" parameter; i.e., they are ordered last if ascending 790 and first if descending. 792 sortOrder: The order in which the sortBy parameter is applied. 793 Allowed values are "ascending" and "descending". If a value for 794 sortBy is provided and no sortOrder is specified, the sortOrder 795 SHALL default to ascending. String type attributes are case 796 insensitive by default unless the attribute type is defined as a 797 case exact string. "sortOrder" MUST sort according to the 798 attribute type; i.e., for case insensitive attributes, sort the 799 result using case insensitive, unicode alphabetic sort order, with 800 no specific locale implied and for case exact attribute types, 801 sort the result using case sensitive, Unicode alphabetic sort 802 order. 804 3.2.2.4. Pagination 806 Pagination parameters can be used together to "page through" large 807 numbers of resources so as not to overwhelm the client or service 808 provider. Pagination is not session based hence clients SHOULD never 809 assume repeatable results. For example, a request for a list of 10 810 resources beginning with a startIndex of 1 may return different 811 results when repeated as a resource in the original result could be 812 deleted or new ones could be added in-between requests. Pagination 813 parameters and general behavior are derived from the OpenSearch 814 Protocol [OpenSearch]. 816 The following table describes the URL pagination parameters. 818 +------------+----------------------------+-------------------------+ 819 | Parameter | Description | Default | 820 +------------+----------------------------+-------------------------+ 821 | startIndex | The 1-based index of the | 1 | 822 | | first query result. A | | 823 | | value less than 1 SHALL be | | 824 | | interpreted as 1. | | 825 | count | Non-negative Integer. | None. When specified | 826 | | Specifies the desired | the service provider | 827 | | maximum number of query | MUST NOT return more | 828 | | results per page; e.g., | results than specified | 829 | | 10. A negative value SHALL | though MAY return fewer | 830 | | be interpreted as "0". A | results. If | 831 | | value of "0" indicates no | unspecified, the | 832 | | resource results are to be | maximum number of | 833 | | returned except for | results is set by the | 834 | | "totalResults". | service provider. | 835 +------------+----------------------------+-------------------------+ 837 Table 5: Pagination Request parameters 839 The following table describes the query response pagination 840 attributes specified by the service provider. 842 +--------------+----------------------------------------------------+ 843 | Element | Description | 844 +--------------+----------------------------------------------------+ 845 | itemsPerPage | Non-negative Integer. Specifies the number of | 846 | | query results returned in a query response page; | 847 | | e.g., 10. | 848 | totalResults | Non-negative Integer. Specifies the total number | 849 | | of results matching the client query; e.g., 1000. | 850 | startIndex | The 1-based index of the first result in the | 851 | | current set of query results; e.g., 1. | 852 +--------------+----------------------------------------------------+ 854 Table 6: Pagination Response Elements 856 For example, to retrieve the first 10 Users set the startIndex to 1 857 and the count to 10: 859 GET /Users?startIndex=1&count=10 860 Host: example.com 861 Accept: application/scim+json 862 Authorization: Bearer h480djs93hd8 863 The response to the query above returns metadata regarding paging 864 similar to the following example (actual resources removed for 865 brevity): 867 { 868 "totalResults":100, 869 "itemsPerPage":10, 870 "startIndex":1, 871 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 872 "Resources":[{ 873 ... 874 }] 875 } 877 Given the example above, to continue paging set the startIndex to 11 878 and re-fetch; i.e., /Users?startIndex=11&count=10 880 3.2.2.5. Attributes 882 The following attributes control which attributes SHALL be returned 883 with a returned resource. SCIM clients MAY use up to one of these 884 two OPTIONAL parameters which MUST be supported by SCIM service 885 providers: 887 attributes A multi-valued list of strings indicating the names of 888 resource attributes to return in the response overriding the set 889 of attributes that would be returned by default. Attribute names 890 MUST be in standard.attribute notation (Section 3.8) form. See 891 additional retrieval query parameters (Section 3.7). 893 excludedAttributes A multi-valued list of strings indicating the 894 names of resource attributes to be removed from the default set of 895 attributes to return. This parameter SHALL have no effect on 896 attributes whose schema "returned" setting is "always" see Server 897 Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in 898 standard attribute notation (Section 3.8) form. See additional 899 retrieval query parameters (Section 3.7). 901 3.2.3. Querying Resources Using HTTP POST 903 Clients MAY execute queries without passing parameters on the URL by 904 using the HTTP POST verb combined with the '/.search' path extension. 905 The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL 906 be used to indicate the HTTP POST verb is intended to be a query 907 operation. 909 To create a new query result set, a SCIM client sends an HTTP POST 910 request to the desired SCIM resource endpoint (ending in '/.search'). 912 The body of the POST request MAY include any of the parameters as 913 defined in Section 3.2.2. 915 Query requests MUST be identified using the following URI: 916 'urn:ietf:params:scim:api:messages:2.0:SearchRequest'. The following 917 attributes are defined for query requests: 919 attributes A multi-valued list of strings indicating the names of 920 resource attributes to return in the response overriding the set 921 of attributes that would be returned by default. Attribute names 922 MUST be in standard attribute notation (Section 3.8) form. See 923 additional retrieval query parameters (Section 3.7). OPTIONAL. 925 excludedAttributes A multi-valued list of strings indicating the 926 names of resource attributes to be removed from the default set of 927 attributes to return. This parameter SHALL have no effect on 928 attributes whose schema "returned" setting is "always" see Server 929 Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in 930 standard attribute notation (Section 3.8) form. See additional 931 retrieval query parameters (Section 3.7). OPTIONAL. 933 filter The filter string used to request a subset of resources. The 934 filter string MUST be a valid filter (Section 3.2.2.2) expression. 935 OPTIONAL. 937 sortBy A string indicating the attribute whose value SHALL be used 938 to order the returned responses. The sortBy attribute MUST be in 939 standard attribute notation (Section 3.8) form. See sorting 940 (Section 3.2.2.3). OPTIONAL. 942 sortOrder A string indicating the order in which the sortBy 943 parameter is applied. Allowed values are "ascending" and 944 "descending". See sorting (Section 3.2.2.3). OPTIONAL. 946 startIndex An integer indicating the 1-based index of the first 947 query result. See pagination (Section 3.2.2.4). OPTIONAL. 949 count An integer indicating the desired maximum number of query 950 results per page. See pagination (Section 3.2.2.4). OPTIONAL. 952 After receiving a HTTP POST request, a response is returned as 953 specified in Section 3.2.2. 955 The following example shows an HTTP POST Query request with search 956 parameters attributes, filter, and count included: 958 POST /.search 959 Host: example.com 960 Accept: application/scim+json 961 Content-Type: application/scim+json 962 Authorization: Bearer h480djs93hd8 963 Content-Length: ... 965 { 966 "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], 967 "attributes": ["displayName", "userName"], 968 "filter": 969 "(displayName sw \"smith\") and (meta.resourceType eq \"User\")", 970 "startIndex": 1, 971 "count": 10 972 } 974 Figure 3: Example POST Query Request 976 A query response is shown with the first page of results. For 977 brevity reasons, only two matches are shown: one User and one Group. 979 HTTP/1.1 200 OK 980 Content-Type: application/scim+json 981 Location: https://example.com/.search 982 { 983 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 984 "totalResults":100, 985 "itemsPerPage":10, 986 "startIndex":1, 987 "Resources":[ 988 { 989 "meta":{ 990 "location": 991 "https://example.com/Users/2819c223-7f76-413861904646", 992 "resourceType":"User", 993 "lastModified": ... 994 }, 995 "userName":"jsmith", 996 "displayName":"Smith, James" 997 }, 998 { 999 "meta":{ 1000 "location": 1001 "https://example.com/Groups/c8596b90-7539-4f20968d1908", 1002 "resourceType":"Group", 1003 "lastModified": ... 1004 }, 1005 "displayName":"Smith Family" 1006 }, 1007 ... 1008 ] 1009 } 1011 Figure 4: Example POST Query Response 1013 3.3. Modifying Resources 1015 Resources can be modified in whole or in part via PUT or PATCH, 1016 respectively. Implementers MUST support PUT as specified in 1017 Section 4.3 [RFC7231]. Resources such as Groups may be very large 1018 hence implementers SHOULD support HTTP PATCH [RFC5789] to enable 1019 partial resource modifications. 1021 3.3.1. Replacing with PUT 1023 HTTP PUT is used to perform a full update of a resource's attributes. 1024 Clients that MAY have previously retrieved the entire resource in 1025 advance and revised it, MAY replace the resource using an HTTP PUT. 1026 Because SCIM resource identifiers are typically assigned by the 1027 service provider, HTTP PUT MUST NOT be used to create new resources. 1029 As the operation intent is to replace all attributes, SCIM clients 1030 MAY send all attributes regardless of each attribute's mutability. 1031 The server will apply attribute by attribute replace according to the 1032 following attribute mutability rules: 1034 readWrite, writeOnly Any values provided SHALL replace the existing 1035 attribute values. 1037 Attributes whose mutability is "readWrite", that are omitted from 1038 the request body, MAY be assumed to be not asserted by the client. 1039 The service provider MAY assume any existing values are to be 1040 cleared or the service provider MAY assign a default value to the 1041 final resource representation. Service providers MAY take into 1042 account whether a client has access to, or understands, all of the 1043 resource's attributes when deciding whether non-asserted 1044 attributes SHALL be removed or defaulted. Clients that would like 1045 to override a server defaults, MAY specify "null" for a single- 1046 valued attribute or an empty array "[]" for a multi-valued 1047 attribute to clear all values. 1049 immutable If value(s) are already set for the attribute, the input 1050 value(s) MUST match or HTTP status 400 SHOULD be returned with 1051 error code "mutability". If the service provider has no existing 1052 values, the new value(s) SHALL be applied. 1054 readOnly Any values provided (e.g. meta.resourceType) SHALL be 1055 ignored. 1057 If an attribute is "required", clients MUST specify the attribute in 1058 the PUT request. 1060 Unless otherwise specified a successful PUT operation returns a 200 1061 OK response code and the entire resource within the response body, 1062 enabling the client to correlate the client's and the service 1063 provider's views of the updated resource. Example: 1065 PUT /Users/2819c223-7f76-453a-919d-413861904646 1066 Host: example.com 1067 Accept: application/scim+json 1068 Content-Type: application/scim+json 1069 Authorization: Bearer h480djs93hd8 1070 If-Match: W/"a330bc54f0671c9" 1072 { 1073 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 1074 "id":"2819c223-7f76-453a-919d-413861904646", 1075 "userName":"bjensen", 1076 "externalId":"bjensen", 1077 "name":{ 1078 "formatted":"Ms. Barbara J Jensen III", 1079 "familyName":"Jensen", 1080 "givenName":"Barbara", 1081 "middleName":"Jane" 1082 }, 1083 "roles":[], 1084 "emails":[ 1085 { 1086 "value":"bjensen@example.com" 1087 }, 1088 { 1089 "value":"babs@jensen.org" 1090 } 1091 ] 1092 } 1093 The service responds with the entire, updated User: 1095 HTTP/1.1 200 OK 1096 Content-Type: application/scim+json 1097 ETag: W/"b431af54f0671a2" 1098 Location: 1099 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646" 1100 { 1101 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 1102 "id":"2819c223-7f76-453a-919d-413861904646", 1103 "userName":"bjensen", 1104 "externalId":"bjensen", 1105 "name":{ 1106 "formatted":"Ms. Barbara J Jensen III", 1107 "familyName":"Jensen", 1108 "givenName":"Barbara", 1109 "middleName":"Jane" 1110 }, 1111 "emails":[ 1112 { 1113 "value":"bjensen@example.com" 1114 }, 1115 { 1116 "value":"babs@jensen.org" 1117 } 1118 ], 1119 "meta": { 1120 "resourceType":"User", 1121 "created":"2011-08-08T04:56:22Z", 1122 "lastModified":"2011-08-08T08:00:12Z", 1123 "location": 1124 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 1125 "version":"W\/\"b431af54f0671a2\"" 1126 } 1127 } 1129 3.3.2. Modifying with PATCH 1131 HTTP PATCH is an OPTIONAL server function that enables clients to 1132 update one or more attributes of a SCIM resource using a sequence of 1133 operations to "add", "remove", or "replace" values. The general form 1134 of the SCIM patch request is based on JavaScript Object Notation 1135 (JSON) Patch [RFC6902]. One difference between SCIM patch and JSON 1136 patch is that SCIM servers do not support array indexing and may not 1137 support all [RFC6902] operation types. 1139 The body of each request MUST contain the following "schemas" 1140 attribute with the URI value of: 1141 "urn:ietf:params:scim:api:messages:2.0:PatchOp". 1143 The body of an HTTP PATCH request MUST contain the attribute 1144 "Operations", whose value is an array of one or more patch 1145 operations. Each patch operation object MUST have exactly one "op" 1146 member, whose value indicates the operation to perform and MAY be one 1147 of "add", "remove", or "replace". The semantics of each operation 1148 are defined in the following sub-sections. 1150 The following is an example representation of a PATCH request showing 1151 the basic JSON structure (non-normative): 1153 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1154 "Operations":[ 1155 { 1156 "op":"add", 1157 "path":"members", 1158 "value":[ 1159 { 1160 "display": "Babs Jensen", 1161 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1162 "value": "2819c223-7f76-453a-919d-413861904646" 1163 } 1164 ] 1165 }, 1166 ... + additional operations if needed ... 1167 ] 1168 } 1170 Figure 5: Example JSON body for SCIM PATCH Request 1172 A "path" attribute value is a String containing an attribute path 1173 describing the target of the operation. The "path" attribute is 1174 OPTIONAL for "add" and "replace" and is REQUIRED for "remove" 1175 operations. See relevant operation sections below for details. 1177 The "path" attribute is described by the following ABNF syntax rule: 1179 PATH = attrPath / valuePath [subAttr] 1181 Figure 6: SCIM Patch PATH Rule 1183 The ABNF rules, "attrPath", "valuePath", and "subAttr" are defined in 1184 Section 3.2.2.2. The "valuePath" rule allows specific values of a 1185 complex, multi-valued attribute to be selected. 1187 Valid examples of "path" values are as follows: 1189 "path":"members" 1191 "path":"name.familyName" 1193 "path":"addresses[type eq \"work\"]" 1195 "path":"members[value eq 1196 \"2819c223-7f76-453a-919d-413861904646\"]" 1198 "path":"members[value eq 1199 \"2819c223-7f76-453a-919d-413861904646\"].displayName" 1201 Figure 7: Example Path Values 1203 Each operation against an attribute MUST be compatible with the 1204 attribute's mutability and schema as defined in the Attribute Types 1205 Section of [I-D.ietf-scim-core-schema]. For example, a client MUST 1206 NOT modify an attribute that has mutability "readOnly" or 1207 "immutable". However, a client MAY "add" a value to an "immutable" 1208 attribute if the attribute had no previous value. An operation that 1209 is not compatibile with an attribute's mutability or schema SHALL 1210 return the appropriate HTTP response status code and a JSON detail 1211 error response as defined in Section 3.10. 1213 The attribute notation rules described in Section 3.8 apply for 1214 describing attribute paths. For all operations, the value of the 1215 "schemas" attribute on the SCIM service provider's representation of 1216 the resource SHALL be assumed by default. If one of the PATCH 1217 operations modifies the "schemas" attribute, subsequent operations 1218 SHALL assume the modified state of the "schemas" attribute. Clients 1219 MAY implicitly modify the "schemas" attribute by adding (or 1220 replacing) an attribute with its fully qualified name including 1221 schema URN. For example, adding the attribute "urn:ietf:params:scim: 1222 schemas:extension:enterprise:2.0:User:employeeNumber", automatically 1223 adds the value 1224 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" to the 1225 resource's "schemas" attribute. 1227 Each patch operation represents a single action to be applied to the 1228 same SCIM resource specified by the request URI. Operations are 1229 applied sequentially in the order they appear in the array. Each 1230 operation in the sequence is applied to the target resource; the 1231 resulting resource becomes the target of the next operation. 1232 Evaluation continues until all operations are successfully applied or 1233 until an error condition is encountered. 1235 For a multi-valued attributes, a patch operation that sets a value's 1236 "primary" attribute to "true", SHALL cause the server to 1237 automatically set "primary" to "false" for any other values in the 1238 array as only one value MAY be primary. 1240 A patch request, regardless of the number of operations, SHALL be 1241 treated as atomic. If a single operation encounters an error 1242 condition, the original SCIM resource MUST be restored, and a failure 1243 status SHALL be returned. 1245 If a request fails, the server SHALL return an HTTP response status 1246 code and a JSON detail error response as defined in Section 3.10. 1248 On successful completion, the server MUST return either a 200 OK 1249 response code and the entire resource (subject to the "attributes" 1250 query parameter - see Additional Retrieval Query Parameters 1251 (Section 3.7) ) within the response body, or a 204 No Content 1252 response code and the appropriate response headers for a successful 1253 patch request. The server MUST return a 200 OK if the "attributes" 1254 parameter is specified on the request. 1256 3.3.2.1. Add Operation 1258 The "add" operation is used to add a new attribute value to an 1259 existing resource. 1261 The operation MUST contain a "value" member whose content specifies 1262 the value to be added. The value MAY be a quoted value OR it may be 1263 a JSON object containing the sub-attributes of the complex attribute 1264 specified in the operation's "path". 1266 The result of the add operation depends upon what the target location 1267 indicated by "path" references: 1269 o If omitted, the target location is assumed to be the resource 1270 itself. The "value" parameter contains a set of attributes to be 1271 added to the resource. 1273 o If the target location does not exist, the attribute and value is 1274 added. 1276 o If the target location specifies a complex attribute, a set of 1277 sub-attributes SHALL be specified in the "value" parameter. 1279 o If the target location specifies a multi-valued attribute, a new 1280 value is added to the attribute. 1282 o if the target location specifies a single-valued attribute, the 1283 existing value is replaced. 1285 o If the target location specifies an attribute that does not exist 1286 (has no value), the attribute is added with the new value. 1288 o If the target location exists, the value is replaced. 1290 o If the target location already contains the value specified, no 1291 changes SHOULD be made to the resource and a success response 1292 SHOULD be returned. Unless other operations change the resource, 1293 this operation SHALL NOT change the modify timestamp of the 1294 resource. 1296 The following example shows how to add a member to a group. Some 1297 text removed for readability ("..."): 1299 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1300 Host: example.com 1301 Accept: application/scim+json 1302 Content-Type: application/scim+json 1303 Authorization: Bearer h480djs93hd8 1304 If-Match: W/"a330bc54f0671c9" 1305 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1306 "Operations":[ 1307 { 1308 "op":"add", 1309 "path":"members", 1310 "value":[ 1311 { 1312 "display": "Babs Jensen", 1313 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1314 "value": "2819c223-7f76-453a-919d-413861904646" 1315 } 1316 ] 1317 } 1318 ] 1319 } 1321 If the user was already a member of this group, no changes should be 1322 made to the resource and a success response should be returned. The 1323 server responds with either the entire updated Group or no response 1324 body: 1326 HTTP/1.1 204 No Content 1327 Authorization: Bearer h480djs93hd8 1328 ETag: W/"b431af54f0671a2" 1329 Location: 1330 "https://example.com/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" 1332 The following example shows how to add one or more attributes to a 1333 User resource without using a "path" attribute. 1335 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1336 Host: example.com 1337 Accept: application/scim+json 1338 Content-Type: application/scim+json 1339 Authorization: Bearer h480djs93hd8 1340 If-Match: W/"a330bc54f0671c9" 1342 { 1343 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1344 "Operations":[{ 1345 "op":"add", 1346 "value":"{ 1347 "emails":[ 1348 { 1349 "value":"babs@jensen.org", 1350 "type":"home" 1351 } 1352 ], 1353 "nickname":"Babs" 1354 }] 1355 } 1357 In the above example, an additional value is added to the multi- 1358 valued attribute "emails". The second attribute, "nickname" is added 1359 to the User resource. If the resource already had an existing 1360 "nickname", the value is replaced per the processing rules above for 1361 single-valued attributes. 1363 3.3.2.2. Remove Operation 1365 The "remove" operation removes the value at the target location 1366 specified by the required attribute "path". The operation performs 1367 the following functions depending on the target location specified by 1368 "path" : 1370 o If "path" is unspecified, the operation fails with HTTP status 1371 "400" and "scimType" of "noTarget". 1373 o If the target location is a single-value attribute, the attribute 1374 and its associated value is removed and the attribute SHALL be 1375 considered unassigned. 1377 o If the target location is a multi-valued attribute and no filter 1378 is specified, the attribute and all values are removed and the 1379 attribute SHALL be considered unassigned. 1381 o If the target location is a multi-valued attribute and a complex 1382 filter is specified comparing a "value", the values matched by the 1383 filter are removed. If after removal of the selected values, no 1384 other values remain, the multi-valued attribute SHALL be 1385 considered unassigned. 1387 o If the target location is a complex-multi-valued attribute and a 1388 complex filter is specified based on the attribute's sub- 1389 attributes, the matching records are removed. Sub-attributes 1390 whose values have been removed SHALL be considered unassigned. If 1391 the complex-multi-valued attribute has no remaining records, the 1392 attribute SHALL be considered unassigned. 1394 If an attribute is removed or becomes unassigned and is defined as a 1395 required attribute or a read-only attribute, the server SHALL return 1396 an HTTP response status code and a JSON detail error response as 1397 defined in Section 3.10 with a "scimType" error of "mutability". 1399 The following example shows how to remove a member from a group. As 1400 with the previous example, the "display" sub-attribute is optional. 1401 If the user was not a member of this group, no changes should be made 1402 to the resource and a success response should be returned. 1404 Note that server responses have been omitted for the rest of the 1405 PATCH examples. 1407 Remove a single member from a group. Some text removed for 1408 readability ("..."): 1410 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1411 Host: example.com 1412 Accept: application/scim+json 1413 Content-Type: application/scim+json 1414 Authorization: Bearer h480djs93hd8 1415 If-Match: W/"a330bc54f0671c9" 1417 { 1418 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1419 "Operations":[{ 1420 "op":"remove", 1421 "path":"members[value eq \"2819c223-7f76-...413861904646\"]" 1422 }] 1423 } 1425 Remove all members of a group: 1427 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1428 Host: example.com 1429 Accept: application/scim+json 1430 Content-Type: application/scim+json 1431 Authorization: Bearer h480djs93hd8 1432 If-Match: W/"a330bc54f0671c9" 1434 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1435 "Operations":[{ 1436 "op":"remove","path":"members" 1437 }] 1438 } 1440 Removal of a value from a complex-multi-valued attribute (request 1441 headers removed for brevity): 1443 { 1444 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1445 "Operations": [{ 1446 "op":"remove", 1447 "path":"emails[type eq \"work\" and value ew \"example.com\"]" 1448 }] 1449 } 1450 Example request to remove and add a member. Some text removed for 1451 readability ("..."): 1453 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1454 Host: example.com 1455 Accept: application/scim+json 1456 Content-Type: application/scim+json 1457 Authorization: Bearer h480djs93hd8 1458 If-Match: W/"a330bc54f0671c9" 1459 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1460 "Operations": [ 1461 { 1462 "op":"remove", 1463 "path":"members[value eq\"2819c223...919d-413861904646\"]" 1464 }, 1465 { 1466 "op":"add", 1467 "path":"members", 1468 "value": [ 1469 { 1470 "display": "James Smith", 1471 "$ref":"https://example.com/v2/Users/08e1d05d...473d93df9210", 1472 "value": "08e1d05d...473d93df9210" 1473 } 1474 ] 1475 } 1476 ] 1477 } 1478 The following example shows how to replace all the members of a group 1479 with a different members list. Some text removed for readabilty 1480 ("..."): 1482 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1483 Host: example.com 1484 Accept: application/scim+json 1485 Content-Type: application/scim+json 1486 Authorization: Bearer h480djs93hd8 1487 If-Match: W/"a330bc54f0671c9" 1488 { 1489 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1490 "Operations": [ 1491 { 1492 "op":"remove","path":"members" 1493 }, 1494 { 1495 "op":"add", 1496 "path":"members", 1497 "value":[ 1498 { 1499 "display": "Babs Jensen", 1500 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1501 "value": "2819c223-7f76-453a-919d-413861904646" 1502 }, 1503 { 1504 "display": "James Smith", 1505 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1506 "value": "08e1d05d-121c-4561-8b96-473d93df9210" 1507 }] 1508 } 1509 ] 1510 } 1512 3.3.2.3. Replace Operation 1514 The "replace" operation replaces the value at the target location 1515 specified by the "path". The operation performs the following 1516 functions depending on the target location specified by "path" : 1518 o If the "path" parameter is omitted, the target is assumed to be 1519 the resource itself. In this case, the "value" attribute SHALL 1520 contain a list of one or more attributes that are to be replaced. 1522 o If the target location is a single-value attribute, the attributes 1523 value is replaced. 1525 o If the target location is a multi-valued attribute and no filter 1526 is specified, the attribute and all values are replaced. 1528 o If the target location specifies a complex attribute, a set of 1529 sub-attributes SHALL be specified in the "value" parameter which 1530 replaces any existing values or adds where an attribute did not 1531 previously exist. Sub-attributes that are not specified in the 1532 "value" parameter are left unchanged. 1534 o If the target location is a multi-valued attribute and a complex 1535 filter is specified comparing a "value", the values matched by the 1536 filter are replaced. 1538 o If the target location is a complex-multi-valued attribute and a 1539 complex filter is specified based on the attribute's sub- 1540 attributes, the matching records are replaced. 1542 o If the target location is a complex-multi-valued attribute with a 1543 complex filter and a specific sub-attribute (e.g. "addresses[type 1544 eq "work"].streetAddress" ), the matching sub-attribute of the 1545 matching record is replaced. 1547 The following example shows how to replace all the members of a group 1548 with a different members list in a single replace operation. Some 1549 text removed for readability ("..."): 1551 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1552 Host: example.com 1553 Accept: application/scim+json 1554 Content-Type: application/scim+json 1555 Authorization: Bearer h480djs93hd8 1556 If-Match: W/"a330bc54f0671c9" 1558 { 1559 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1560 "Operations": [{ 1561 "op":"replace", 1562 "path":"members", 1563 "value":[ 1564 { 1565 "display": "Babs Jensen", 1566 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1567 "value": "2819c223...413861904646" 1568 }, 1569 { 1570 "display": "James Smith", 1571 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1572 "value": "08e1d05d...473d93df9210" 1573 } 1574 ] 1575 }] 1576 } 1577 The following example shows how to change a User's entire "work" 1578 address. 1580 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1581 Host: example.com 1582 Accept: application/scim+json 1583 Content-Type: application/scim+json 1584 Authorization: Bearer h480djs93hd8 1585 If-Match: W/"a330bc54f0671c9" 1587 { 1588 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1589 "Operations": [{ 1590 "op":"replace", 1591 "path":"addresses[type eq \"work\"]", 1592 "value": 1593 { 1594 "type": "work", 1595 "streetAddress": "911 Universal City Plaza", 1596 "locality": "Hollywood", 1597 "region": "CA", 1598 "postalCode": "91608", 1599 "country": "US", 1600 "formatted": "911 Universal City Plaza\nHollywood, CA 91608 US", 1601 "primary": true 1602 } 1603 }] 1604 } 1606 The following example shows how to change a User's "work" email 1607 address: 1609 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1610 Host: example.com 1611 Accept: application/scim+json 1612 Content-Type: application/scim+json 1613 Authorization: Bearer h480djs93hd8 1614 If-Match: W/"a330bc54f0671c9" 1616 { 1617 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1618 "Operations": [{ 1619 "op":"replace", 1620 "path":"emails[type eq \"work\"].value", 1621 "value":"bjenson@example.com" 1622 }] 1623 } 1624 The following example shows how to replace one or more attributes of 1625 a User resource. 1627 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1628 Host: example.com 1629 Accept: application/scim+json 1630 Content-Type: application/scim+json 1631 Authorization: Bearer h480djs93hd8 1632 If-Match: W/"a330bc54f0671c9" 1634 { 1635 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1636 "Operations": [{ 1637 "op":"replace", 1638 "value":"{ 1639 "emails":[ 1640 { 1641 "value":"bjensen@example.com", 1642 "type":"work", 1643 "primary":true 1644 }, 1645 { 1646 "value":"babs@jensen.org", 1647 "type":"home" 1648 } 1649 ], 1650 "nickname":"Babs" 1651 }] 1652 } 1654 3.4. Deleting Resources 1656 Clients request resource removal via DELETE. Service providers MAY 1657 choose not to permanently delete the resource, but MUST return a 404 1658 error code for all operations associated with the previously deleted 1659 Id. Service providers MUST also omit the resource from future query 1660 results. In addition the service provider SHOULD NOT consider the 1661 deleted resource in conflict calculation. For example if a User 1662 resource is deleted, a CREATE request for a User resource with the 1663 same userName as the previously deleted resource should not fail with 1664 a 409 error due to userName conflict. 1666 DELETE /Users/2819c223-7f76-453a-919d-413861904646 1667 Host: example.com 1668 Authorization: Bearer h480djs93hd8 1669 If-Match: W/"c310cd84f0281b7" 1671 In response to a successful delete, the server SHALL respond with 1672 successful HTTP status 204 (No Content). A non-normative example 1673 response: 1675 HTTP/1.1 204 No Content 1677 Example: client attempt to retrieve the previously deleted User 1679 GET /Users/2819c223-7f76-453a-919d-413861904646 1680 Host: example.com 1681 Authorization: Bearer h480djs93hd8 1683 Server Response: 1685 HTTP/1.1 404 NOT FOUND 1687 { 1688 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 1689 "Errors":[ 1690 { 1691 "description": 1692 "Resource 2819c223-7f76-453a-919d-413861904646 not found", 1693 "code":"404" 1694 } 1695 ] 1696 } 1698 3.5. Bulk Operations 1700 The SCIM bulk operation is an optional server feature that enables 1701 clients to send a potentially large collection of resource operations 1702 in a single request. The body of a a bulk operation contains a set 1703 of HTTP resource operations using one of the API supported HTTP 1704 methods; i.e., POST, PUT, PATCH or DELETE. 1706 Bulk requests are identified using the following URI: 1707 "urn:ietf:params:scim:api:messages:2.0:BulkRequest". Bulk responses 1708 are identified using the following URI: 1709 "urn:ietf:params:scim:api:messages:2.0:BulkResponse". Bulk requests 1710 and bulk responses share many attributes. Unless otherwise 1711 specified, each attribute below is present in both bulk requests and 1712 bulk responses. 1714 The following Singular Attribute is defined in addition to the common 1715 attributes defined in SCIM core schema. 1717 failOnErrors 1718 An Integer specifying the number of errors that the service 1719 provider will accept before the operation is terminated and an 1720 error response is returned. OPTIONAL in a request. Not valid in 1721 a response. 1723 The following Complex Multi-valued Attribute is defined in addition 1724 to the common attributes defined in core schema. 1726 Operations 1727 Defines operations within a bulk job. Each operation corresponds 1728 to a single HTTP request against a resource endpoint. REQUIRED. 1729 Operations has the following sub-attributes: 1731 method The HTTP method of the current operation. Possible values 1732 are POST, PUT, PATCH or DELETE. REQUIRED. 1734 bulkId The transient identifier of a newly created resource, 1735 unique within a bulk request and created by the client. The 1736 bulkId serves as a surrogate resource id enabling clients to 1737 uniquely identify newly created resources in the Response and 1738 cross reference new resources in and across operations within a 1739 bulk request. REQUIRED when method is POST. 1741 version The current resource version. Version is MAY be used if 1742 the service provider supports ETags and the method is PUT, 1743 PATCH, or DELETE. 1745 path The resource's relative path. If the method is POST the 1746 value must specify a resource type endpoint; e.g., /Users or 1747 /Groups whereas all other method values must specify the path 1748 to a specific resource; e.g., /Users/2819c223-7f76-453a-919d- 1749 413861904646. REQUIRED in a request. 1751 data The resource data as it would appear for a single POST, PUT 1752 or PATCH resource operation. REQUIRED in a request when method 1753 is POST, PUT and PATCH. 1755 location The resource endpoint URL. REQUIRED in a response, 1756 except in the event of a POST failure. 1758 response The HTTP response body to the specified request 1759 operation. When indicating a response with an HTTP status 1760 other than a 200 series response, the response body MUST be 1761 included. For normal completion, the server MAY elect to omit 1762 the response body. 1764 status The HTTP response status code to the requested operation. 1765 When indicating an error, the "response" attribute MUST contain 1766 the detailed error response as per Section 3.10. 1768 If a bulk job is processed successfully the HTTP response code 200 OK 1769 MUST be returned, otherwise an appropriate HTTP error code MUST be 1770 returned. 1772 The service provider MUST continue performing as many changes as 1773 possible and disregard partial failures. The client MAY override 1774 this behavior by specifying a value for the "failOnErrors" attribute. 1775 The failOnErrors attribute defines the number of errors that the 1776 service provider should accept before failing the remaining 1777 operations returning the response. 1779 To be able to reference a newly created resource the attribute bulkId 1780 MUST be specified when creating new resources. The "bulkId" is 1781 defined by the client as a surrogate identifier in a POST operation 1782 (see Section 3.5.2). The service provider MUST return the same 1783 "bulkId" together with the newly created resource. The "bulkId" can 1784 then be used by the client to map the service provider id with the 1785 "bulkId" of the created resource. 1787 A SCIM service provider MAY elect to optimize a sequence operations 1788 received (e.g. to improve processing performance). When doing so, 1789 the service provider MUST ensure the clients intent is preserved and 1790 the same stateful result is achieved as for non-optimized processing. 1791 For example, before a "User" can be added to a "Group", they must 1792 first be created. Processing these requests out of order, might 1793 result in a failure to add the new "User" to the "Group". 1795 3.5.1. Circular Reference Processing 1797 The service provider MUST try to resolve circular cross references 1798 between resources in a single bulk job but MAY stop after a failed 1799 attempt and instead return the status code 409 Conflict. The 1800 following example exhibits the potential conflict. 1802 POST /v2/Bulk 1803 Host: example.com 1804 Accept: application/scim+json 1805 Content-Type: application/scim+json 1806 Authorization: Bearer h480djs93hd8 1807 Content-Length: ... 1809 { 1810 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 1811 "Operations": [ 1812 { 1813 "method": "POST", 1814 "path": "/Groups", 1815 "bulkId": "qwerty", 1816 "data": { 1817 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1818 "displayName": "Group A", 1819 "members": [ 1820 { 1821 "type": "Group", 1822 "value": "bulkId:ytrewq" 1823 } 1824 ] 1825 } 1826 }, 1827 { 1828 "method": "POST", 1829 "path": "/Groups", 1830 "bulkId": "ytrewq", 1831 "data": { 1832 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1833 "displayName": "Group B", 1834 "members": [ 1835 { 1836 "type": "Group", 1837 "value": "bulkId:qwerty" 1838 } 1839 ] 1840 } 1841 } 1842 ] 1843 } 1845 If the service provider resolved the above circular references the 1846 following is returned from a subsequent GET request. 1848 GET /v2/Groups?filter=displayName sw 'Group' 1849 Host: example.com 1850 Accept: application/scim+json 1851 Authorization: Bearer h480djs93hd8 1853 HTTP/1.1 200 OK 1854 Content-Type: application/scim+json 1856 { 1857 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 1858 "totalResults": 2, 1859 "Resources": [ 1860 { 1861 "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1862 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1863 "displayName": "Group A", 1864 "meta": { 1865 "resourceType": "Group", 1866 "created": "2011-08-01T18:29:49.793Z", 1867 "lastModified": "2011-08-01T18:29:51.135Z", 1868 "location": 1869 "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1870 "version": "W\/\"mvwNGaxB5SDq074p\"" 1871 }, 1872 "members": [ 1873 { 1874 "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1875 "$ref": 1876 "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1877 "type": "Group" 1878 } 1879 ] 1880 }, 1881 { 1882 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1883 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1884 "displayName": "Group B", 1885 "meta": { 1886 "resourceType": "Group", 1887 "created": "2011-08-01T18:29:50.873Z", 1888 "lastModified": "2011-08-01T18:29:50.873Z", 1889 "location": 1890 "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1891 "version": "W\/\"wGB85s2QJMjiNnuI\"" 1892 }, 1893 "members": [ 1894 { 1895 "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1896 "$ref": 1897 "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1898 "type": "Group" 1899 } 1900 ] 1901 } 1902 ] 1903 } 1905 3.5.2. BulkdId Temporary Identifiers 1907 A SCIM client can, within one bulk operation, create a new "User", a 1908 new "Group" and add the newly created "User" to the newly created 1909 "Group". In order to add the new "User" to the "Group" the client 1910 must use the surrogate id attribute, "bulkId", to reference the User. 1911 The "bulkId" attribute value must be pre-pended with the literal 1912 "bulkId:"; e.g., if the bulkId is 'qwerty', the value is 1913 "bulkId:qwerty". The service provider MUST replace the string 1914 "bulkId:qwerty" with the permanent resource id once created. 1916 To create multiple distinct requests, each with their own "bulkId", 1917 the SCIM client specifies different "bulkId" values for each separate 1918 request. 1920 The following example creates a User with the "userName" 'Alice' and 1921 a "Group" with the "displayName" 'Tour Guides' with Alice as a 1922 member. Notice that each operation has its own "bulkId" value. 1923 However, the second operation (whose "bulkId" is "ytrewq") refers to 1924 the "bulkId" of "qwerty" in order to add Alice to new 'Tour Guides' 1925 group. 1927 POST /v2/Bulk 1928 Host: example.com 1929 Accept: application/scim+json 1930 Content-Type: application/scim+json 1931 Authorization: Bearer h480djs93hd8 1932 Content-Length: ... 1934 { 1935 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 1936 "Operations": [ 1937 { 1938 "method": "POST", 1939 "path": "/Users", 1940 "bulkId": "qwerty", 1941 "data": { 1942 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 1943 "userName": "Alice" 1944 } 1945 }, 1946 { 1947 "method": "POST", 1948 "path": "/Groups", 1949 "bulkId": "ytrewq", 1950 "data": { 1951 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1952 "displayName": "Tour Guides", 1953 "members": [ 1954 { 1955 "type": "User", 1956 "value": "bulkId:qwerty" 1957 } 1958 ] 1959 } 1960 } 1961 ] 1962 } 1963 The service provider returns the following response: 1965 HTTP/1.1 200 OK 1966 Content-Type: application/json 1968 { 1969 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 1970 "Operations": [ 1971 { 1972 "location": 1973 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1974 "method": "POST", 1975 "bulkId": "qwerty", 1976 "version": "W\/\"4weymrEsh5O6cAEK\"", 1977 "status": { 1978 "code": "201" 1979 } 1980 }, 1981 { 1982 "location": 1983 "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1984 "method": "POST", 1985 "bulkId": "ytrewq", 1986 "version": "W\/\"lha5bbazU3fNvfe5\"", 1987 "status": { 1988 "code": "201" 1989 } 1990 } 1991 ] 1992 } 1994 In the above example, the Alice User resource has an "id" of 1995 "92b725cd-9465-4e7d-8c16-01f8e146b87a" and the Tour Guides Group has 1996 an "id" of "e9e30dba-f08f-4109-8486-d5c6a331660a". 1998 A subsequent GET request for the 'Tour Guides' Group (with an "id" 1999 of"e9e30dba-f08f-4109-8486-d5c6a331660a") returns the following with 2000 Alice's "id" as the value for the member in the Group 'Tour Guides': 2002 HTTP/1.1 200 OK 2003 Content-Type: application/scim+json 2004 Location: 2005 https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 2006 ETag: W/"lha5bbazU3fNvfe5" 2008 { 2009 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 2010 "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", 2011 "displayName": "Tour Guides", 2012 "meta": { 2013 "resourceType": "Group", 2014 "created": "2011-08-01T18:29:49.793Z", 2015 "lastModified": "2011-08-01T20:31:02.315Z", 2016 "location": 2017 "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 2018 "version": "W\/\"lha5bbazU3fNvfe5\"" 2019 }, 2020 "members": [ 2021 { 2022 "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", 2023 "$ref": 2024 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2025 "type": "User" 2026 } 2027 ] 2028 } 2030 Extensions that include references to other resources MUST be handled 2031 in the same way by the service provider. The following example uses 2032 the bulkId attribute within the enterprise extension managerId 2033 attribute. 2035 POST /v2/Bulk 2036 Host: example.com 2037 Accept: application/scim+json 2038 Content-Type: application/scim+json 2039 Authorization: Bearer h480djs93hd8 2040 Content-Length: ... 2042 { 2043 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 2044 "Operations": [ 2045 { 2046 "method": "POST", 2047 "path": "/Users", 2048 "bulkId": "qwerty", 2049 "data": { 2050 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 2051 "userName": "Alice" 2052 } 2053 }, 2054 { 2055 "method": "POST", 2056 "path": "/Users", 2057 "bulkId": "ytrewq", 2058 "data": { 2059 "schemas": [ 2060 "urn:ietf:params:scim:schemas:core:2.0:User", 2061 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" 2062 ], 2063 "userName": "Bob", 2064 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { 2065 "employeeNumber": "11250", 2066 "manager": { 2067 "managerId": "batchId:qwerty", 2068 "displayName": "Alice" 2069 } 2070 } 2071 } 2072 } 2073 ] 2074 } 2076 3.5.3. Response and Error Handling 2078 The service provider response MUST include the result of all 2079 processed operations. A "location" attribute that includes the 2080 resource's endpoint MUST be returned for all operations excluding 2081 failed POSTs. The status attribute includes information about the 2082 success or failure of one operation within the bulk job. The 2083 attribute status MUST include the code attribute that holds the HTTP 2084 response code that would have been returned if a single HTTP request 2085 would have been used. If an error occurred the status MUST also 2086 include the description attribute containing a human readable 2087 explanation of the error. 2089 "status": "201" 2091 The following is an example of a status in a failed operation. 2093 "status": "400", 2094 "response":{ 2095 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2096 "scimType":"invalidSyntax" 2097 "detail": 2098 "Request is unparseable, syntactically incorrect, or violates schema.", 2099 "status":"400" 2100 } 2102 The following example shows how to add, update, and remove a user. 2103 The "failOnErrors" attribute is set to '1' indicating the service 2104 provider should return on the first error. The POST operation's 2105 bulkId value is set to 'qwerty' enabling the client to match the new 2106 User with the returned resource id '92b725cd-9465-4e7d- 2107 8c16-01f8e146b87a'. 2109 POST /v2/Bulk 2110 Host: example.com 2111 Accept: application/scim+json 2112 Content-Type: application/scim+json 2113 Authorization: Bearer h480djs93hd8 2114 Content-Length: ... 2116 { 2117 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 2118 "failOnErrors":1, 2119 "Operations":[ 2120 { 2121 "method":"POST", 2122 "path":"/Users", 2123 "bulkId":"qwerty", 2124 "data":{ 2125 "schemas": ["urn:ietf:params:scim:api:messages:2.0:User"], 2126 "userName":"Alice" 2127 } 2128 }, 2129 { 2130 "method":"PUT", 2131 "path":"/Users/b7c14771-226c-4d05-8860-134711653041", 2132 "version":"W\/\"3694e05e9dff591\"", 2133 "data":{ 2134 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 2135 "id":"b7c14771-226c-4d05-8860-134711653041", 2136 "userName":"Bob" 2137 } 2138 }, 2139 { 2140 "method": "PATCH", 2141 "path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2142 "version": "W/\"edac3253e2c0ef2\"", 2143 "data": {[ 2144 { 2145 "op": "remove", 2146 "path": "nickName" 2147 }, 2148 { 2149 "op": "add", 2150 "path": "userName", 2151 "value": "Dave" 2152 } 2153 ]} 2154 }, 2155 { 2156 "method":"DELETE", 2157 "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2158 "version":"W\/\"0ee8add0a938e1a\"" 2159 } 2160 ] 2161 } 2163 The service provider returns the following response. 2165 HTTP/1.1 200 OK 2166 Content-Type: application/scim+json 2168 { 2169 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2170 "Operations": [ 2171 { 2172 "location": 2173 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2174 "method": "POST", 2175 "bulkId": "qwerty", 2176 "version": "W\/\"oY4m4wn58tkVjJxK\"", 2177 "status": "201" 2178 }, 2179 { 2180 "location": 2181 "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 2182 "method": "PUT", 2183 "version": "W\/\"huJj29dMNgu3WXPD\"", 2184 "status": "200" 2185 }, 2186 { 2187 "location": 2188 "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2189 "method": "PATCH", 2190 "version": "W\/\"huJj29dMNgu3WXPD\"", 2191 "status": "200" 2192 }, 2193 { 2194 "location": 2195 "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2196 "method": "DELETE", 2197 "status": "204" 2198 } 2199 ] 2200 } 2202 The following response is returned if an error occurred when 2203 attempting to create the User 'Alice'. The service provider stops 2204 processing the bulk operation and immediately returns a response to 2205 the client. The response contains the error and any successful 2206 results prior to the error. 2208 HTTP/1.1 200 OK 2209 Content-Type: application/scim+json 2211 { 2212 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2213 "Operations": [ 2214 { 2215 "method": "POST", 2216 "bulkId": "qwerty", 2217 "status": "400", 2218 "response":{ 2219 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2220 "scimType":"invalidSyntax" 2221 "detail": 2222 "Request is unparseable, syntactically incorrect, or violates schema.", 2223 "status":"400" 2224 } 2225 } 2226 ] 2227 } 2229 If the "failOnErrors" attribute is not specified or the service 2230 provider has not reached the error limit defined by the client the 2231 service provider will continue to process all operations. The 2232 following is an example in which all operations failed. 2234 HTTP/1.1 200 OK 2235 Content-Type: application/scim+json 2237 { 2238 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2239 "Operations": [ 2240 { 2241 "method": "POST", 2242 "bulkId": "qwerty", 2243 "status": "400", 2244 "response":{ 2245 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2246 "scimType":"invalidSyntax" 2247 "detail": 2248 "Request is unparseable, syntactically incorrect, or violates schema.", 2249 "status":"400" 2250 } 2251 }, 2252 { 2253 "location": 2254 "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 2255 "method": "PUT", 2256 "status": "412", 2257 "response":{ 2258 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2259 "detail":"Failed to update. Resource changed on the server.", 2260 "status":"412" 2261 } 2262 }, 2263 { 2264 "location": 2265 "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2266 "method": "PATCH", 2267 "status": "412", 2268 "response":{ 2269 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2270 "detail":"Failed to update. Resource changed on the server.", 2271 "status":"412" 2272 } 2273 }, 2274 { 2275 "location": 2276 "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2277 "method": "DELETE", 2278 "status": "404", 2279 "response":{ 2280 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2281 "detail":"Resource does not exist.", 2282 "status":"404" 2283 } 2284 } 2285 ] 2286 } 2287 HTTP/1.1 200 OK 2288 Content-Type: application/scim+json 2290 { 2291 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2292 "Operations": [ 2293 { 2294 "location": 2295 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2296 "method": "POST", 2297 "bulkId": "qwerty", 2298 "version": "W\/\"4weymrEsh5O6cAEK\"", 2299 "status": "201" 2300 }, 2301 { 2302 "location": 2303 "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 2304 "method": "POST", 2305 "bulkId": "ytrewq", 2306 "version": "W\/\"lha5bbazU3fNvfe5\"", 2307 "status": "201" 2308 } 2309 ] 2310 } 2312 3.5.4. Maximum Operations 2314 The service provider MUST define the maximum number of operations and 2315 maximum payload size a client may send in a single request. These 2316 limits MAY be retrieved from the Service Provider Configuration (see 2317 'bulk' in Section 8 of [I-D.ietf-scim-core-schema]). If either 2318 limits are exceeded the service provider MUST return the HTTP 2319 response code 413 Request Entity Too Large. The returned response 2320 MUST specify the limit exceeded in the body of the error response. 2322 The following example the client sent a request exceeding the service 2323 provider's max payload size of 1 megabyte: 2325 POST /v2/Bulk 2326 Host: example.com 2327 Accept: application/scim+json 2328 Content-Type: application/scim+json 2329 Authorization: Bearer h480djs93hd8 2330 Content-Length: 4294967296 2332 ... 2334 In response to the over-sized request, the server responds with the 2335 following error: 2337 HTTP/1.1 413 Request Entity Too Large 2338 Content-Type: application/scim+json 2340 { 2341 "schemas":["urn:ietf:params:scim:api:messages:2.0:Error"], 2342 "status": "413", 2343 "detail": 2344 "The size of the bulk operation exceeds the maxPayloadSize (1048576)." 2345 } 2347 3.6. Data Input/Output Formats 2349 Servers MUST accept requests and respond with JSON structured 2350 responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default 2351 encoding format. 2353 Clients using other encodings MUST specify the format in which the 2354 data is submitted via HTTP header "Content-Type" as specified in 2355 Section 3.1.1.5 [RFC7231] and MAY specify the desired response data 2356 format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g., 2357 "Accept: application/scim+json" or via URI suffix; e.g., 2359 GET /Users/2819c223-7f76-453a-919d-413861904646.scim 2360 Host: example.com 2362 Service providers MUST support the accept header "Accept: 2363 application/scim+json" and SHOULD support header "Accept: 2364 application/json" both of which specify JSON documents conforming to 2365 [RFC7159]. The format defaults to "application/scim+json" if no 2366 format is specified. 2368 Singular attributes are encoded as string name-value-pairs in JSON; 2369 e.g., 2371 "attribute": "value" 2373 Multi-valued attributes in JSON are encoded as arrays; e.g., 2375 "attributes": [ "value1", "value2" ] 2377 Elements with nested elements are represented as objects in JSON; 2378 e.g, 2380 "attribute": { "subattribute1": "value1", "subattribute2": "value2" } 2382 3.7. Additional Operation Response Parameters 2384 For any SCIM operation where a resource representation is returned 2385 (e.g. HTTP GET), the attributes returned are defined as the minimum 2386 attribute set plus default attributes set. The minimum set are those 2387 attributes whose schema have "returned" set to "always". The default 2388 attribute set are those attributes whose schema have "returned" set 2389 to "default". 2391 Clients MAY request a partial resource representation on any 2392 operation that returns a resource within the response by specifying 2393 either of the mutually exclusive URL query parameters "attributes" OR 2394 "excludedAtributes" as follows: 2396 attributes When specified the default list of attributes SHALL be 2397 overridden and each resource returned MUST contain the 2398 minimum set of resource attributes and any attributes or sub- 2399 attributes explicitly requested by the "attributes" 2400 parameter. The query parameter attributes value is a comma 2401 separated list of resource attribute names in standard 2402 attribute notation (Section 3.8) form (e.g. userName, name, 2403 emails). 2405 excludedAttributes When specified, each resource returned MUST 2406 contain the minimal set of resource attributes. 2407 Additionally, the default set of attributes minus those 2408 attributes listed in "excludedAttributes" are also returned. 2409 The query parameter attributes value is a comma separated 2410 list of resource attribute names in standard attribute 2411 notation (Section 3.8) form (e.g. userName, name, emails). 2413 . 2415 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName 2416 Host: example.com 2417 Accept: application/scim+json 2418 Authorization: Bearer h480djs93hd8 2420 Giving the response 2421 HTTP/1.1 200 OK 2422 Content-Type: application/scim+json 2423 Location: 2424 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2425 ETag: W/"a330bc54f0671c9" 2427 { 2428 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2429 "id":"2819c223-7f76-453a-919d-413861904646", 2430 "userName":"bjensen", 2431 "meta":{ 2432 "resourceType": "User", 2433 "created":"2011-08-01T18:29:49.793Z", 2434 "lastModified":"2011-08-01T18:29:49.793Z", 2435 "location": 2436 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2437 "version":"W\/\"a330bc54f0671c9\"" 2438 } 2439 } 2441 3.8. Attribute Notation 2443 All operations share a common scheme for referencing simple and 2444 complex attributes. In general, attributes are identified by 2445 prefixing the attribute name with its schema URN separated by a ':' 2446 character; e.g., the core User resource attribute 'userName' is 2447 identified as "urn:ietf:params:scim:schemas:core:2.0:User:userName". 2448 Clients MAY omit core schema attribute URN prefixes though MUST fully 2449 qualify extended attributes with the associated resource URN; e.g., 2450 the attribute 'age' defined in 2451 "urn:ietf:params:scim:schemas:exampleCo:2.0:hr" is fully encoded as 2452 "urn:ietf:params:scim:schemas:exampleCo:2.0:hr:age". A Complex 2453 attributes' Sub-Attributes are referenced via nested, dot ('.') 2454 notation; i.e., {urn}:{Attribute name}.{Sub-Attribute name}. For 2455 example, the fully qualified path for a User's givenName is 2456 "urn:ietf:params:scim:schemas:core:2.0:User:name.givenName" All 2457 facets (URN, attribute and Sub-Attribute name) of the fully encoded 2458 Attribute name are case insensitive. 2460 3.9. "/Me" Authenticated Subject Alias 2462 A client MAY use a URL of the form "/Me" as a URI alias for 2463 the User or other resource associated with the currently 2464 authenticated subject for any SCIM operation. A service provider MAY 2465 respond in ONE of 3 ways: 2467 o A service provider that does NOT support this feature SHOULD 2468 respond with status 403 (FORBIDDEN). 2470 o A service provider MAY choose to redirect the client using HTTP 2471 status 308 to the resource associated with the authenticated 2472 subject. The client MAY then repeat the request at the indicated 2473 location. 2475 o A service provider MAY process the SCIM request directly. In any 2476 response, the HTTP "Location" header MUST be the permanent 2477 location of the aliased resource associated with the authenticated 2478 subject. 2480 When using the SCIM Create Resource command (HTTP POST) with the 2481 "/Me" alias, the desired resourceType being created is at the 2482 discretion of the service provider based on the authenticated subject 2483 (if not anonymous) making the request and any request body attributes 2484 (e.g. "schemas"). See Section 6.3 for information on security 2485 considerations related to this operation. 2487 3.10. HTTP Status and Error Response Handling 2489 The SCIM Protocol uses the HTTP status response status codes defined 2490 in Section 6 [RFC7231] to indicate operation success or failure. In 2491 addition to returning a HTTP response code implementers MUST return 2492 the errors in the body of the response in the client requested format 2493 containing the error response and, per the HTTP specification, human- 2494 readable explanations. Error responses are identified using the 2495 following "schema" URI: 2496 "urn:ietf:params:scim:api:messages:2.0:Error". The following 2497 attributes are defined for a SCIM error response using a JSON body: 2499 status 2500 The HTTP status code (see Section 6 [RFC7231]). REQUIRED 2502 scimType 2503 A SCIM detailed error keyword. See Table 8. OPTIONAL 2505 detail 2506 A detailed, human readable message. OPTIONAL 2508 Implementers SHOULD handle the identified HTTP status codes as 2509 described below. 2511 +--------------+---------------+------------------------------------+ 2512 | Status | Applicability | Suggested Explanation | 2513 +--------------+---------------+------------------------------------+ 2514 | 307 | GET, POST, | The client is directed to repeat | 2515 | TEMPORARY | PUT, PATCH, | the same HTTP request at the | 2516 | REDIRECT | DELETE | location identified. The client | 2517 | | | SHOULD NOT use the location | 2518 | | | provided in the response as a | 2519 | | | permanent reference to the | 2520 | | | resource and SHOULD continue to | 2521 | | | use the original request URI | 2522 | | | [RFC7231]. | 2523 | 308 | GET, POST, | The client is directed to repeat | 2524 | PERMANENT | PUT, PATCH, | the same HTTP request at the | 2525 | REDIRECT | DELETE | location identified. The client | 2526 | | | SHOULD use the location provided | 2527 | | | in the response as the permanent | 2528 | | | reference to the resource | 2529 | | | [RFC7238]. | 2530 | 400 BAD | GET, POST, | Request is unparseable, | 2531 | REQUEST | PUT, PATCH, | syntactically incorrect, or | 2532 | | DELETE | violates schema | 2533 | 401 | GET, POST, | Authorization failure | 2534 | UNAUTHORIZED | PUT, PATCH, | | 2535 | | DELETE | | 2536 | 403 | GET, POST, | Server does not support requested | 2537 | FORBIDDEN | PUT, PATCH, | operation | 2538 | | DELETE | | 2539 | 404 NOT | GET, PUT, | Specified resource (e.g., User) or | 2540 | FOUND | PATCH, DELETE | end-point, does not exist | 2541 | 409 CONFLICT | POST, PUT, | The specified version number does | 2542 | | PATCH, DELETE | not match the resource's latest | 2543 | | | version number or a service | 2544 | | | provider refused to create a new, | 2545 | | | duplicate resource | 2546 | 412 | PUT, PATCH,D | Failed to update as resource {id} | 2547 | PRECONDITION | ELETE | changed on the server last | 2548 | FAILED | | retrieved | 2549 | 413 REQUEST | POST | {"maxOperations": | 2550 | ENTITY TOO | | 1000,"maxPayload": 1048576} | 2551 | LARGE | | | 2552 | 500 INTERNAL | GET, POST, | An internal error. Implementers | 2553 | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive | 2554 | | DELETE | debugging advice | 2555 | 501 NOT | GET, POST, | Service Provider does not support | 2556 | IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH | 2557 | | DELETE | | 2558 +--------------+---------------+------------------------------------+ 2560 Table 7: SCIM HTTP Status Code Usage 2562 For HTTP Status 400 (Bad Request) responses, the following detail 2563 error types are defined: 2565 +--------------+------------------------------+---------------------+ 2566 | scimType | Description | Applicability | 2567 +--------------+------------------------------+---------------------+ 2568 | invalidFilte | The specified filter syntax | GET(Section 3.2.2), | 2569 | r | was invalid (does not comply | POST (Search - | 2570 | | with Figure 1) or the | Section 3.2.3), | 2571 | | specified attribute and | PATCH (Path Filter | 2572 | | filter comparison | - Section 3.3.2) | 2573 | | combination is not | | 2574 | | supported. | | 2575 | tooMany | The specified filter yields | GET(Section 3.2.2), | 2576 | | many more results than the | POST (Search - | 2577 | | server is willing calculate | Section 3.2.3) | 2578 | | or process. For example, a | | 2579 | | filter such as "(userName | | 2580 | | pr)" by itself would return | | 2581 | | all entries with a | | 2582 | | "userName" and MAY not be | | 2583 | | acceptable to the service | | 2584 | | provider. | | 2585 | uniqueness | One or more of attribute | POST (Create - | 2586 | | values is already in use or | Section 3.1), PUT | 2587 | | is reserved. | (Section 3.3.1), | 2588 | | | PATCH (Section | 2589 | | | 3.3.2) | 2590 | mutability | The attempted modification | PUT (Section | 2591 | | is not compatible with the | 3.3.1), PATCH | 2592 | | target attributes mutability | (Section 3.3.2) | 2593 | | or current state (e.g. | | 2594 | | modification of an immutable | | 2595 | | attribute with an existing | | 2596 | | value). | | 2597 | invalidSynta | The request body message | POST (Search - | 2598 | x | structure was invalid or did | Section 3.2.2, | 2599 | | not conform to the request | Create - Section | 2600 | | schema. | 3.1, Bulk - Section | 2601 | | | 3.5), PUT (Section | 2602 | | | 3.3.1) | 2603 | invalidPath | The path attribute was | PATCH (Section | 2604 | | invalid or malformed (see | 3.3.2) | 2605 | | Figure 6). | | 2606 | noTarget | The specified "path" did not | PATCH (Section | 2607 | | yield an attribute or | 3.3.2) | 2608 | | attribute value that could | | 2609 | | be operated on. This occurs | | 2610 | | when the specified "path" | | 2611 | | value contains a filter that | | 2612 | | yields no match. | | 2613 | invalidValue | A required value was | GET (Section | 2614 | | missing, or the value | 3.2.2), POST | 2615 | | specified was not compatible | (Create - Section | 2616 | | with the operation or | 3.1, Query - | 2617 | | attribute type (see Section | Section 3.2.2), PUT | 2618 | | 2.1 [I-D.ietf-scim-core-sche | (Section 3.3.1), | 2619 | | ma]), or schema (see Section | PATCH (Section | 2620 | | 4 [I-D.ietf-scim-core-schema | 3.3.2) | 2621 | | ]). | | 2622 | invalidVers | The specified SCIM protocol | GET (Section | 2623 | | version is not supported | 3.2.2), POST (ALL), | 2624 | | (see Section 3.11). | PUT (Section | 2625 | | | 3.3.1), PATCH | 2626 | | | (Section 3.3.2), | 2627 | | | DELETE (Section | 2628 | | | 3.4) | 2629 +--------------+------------------------------+---------------------+ 2631 Table 8: Table of SCIM Detail Error Keyword Values 2633 Note that in the table above (Table 8), the applicability table 2634 applies to the normal HTTP method but MAY apply within a SCIM Bulk 2635 operation (via HTTP POST). 2637 Error example in response to a non-existent GET request. 2639 HTTP/1.1 404 NOT FOUND 2641 { 2642 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2643 "detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 2644 "status":"404 2645 } 2647 Error example in response to a PUT request. 2649 HTTP/1.1 400 BAD REQUEST 2651 { 2652 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2653 "scimType":"mutability" 2654 "detail":"Attribute 'id' is readOnly", 2655 "status":"400" 2656 } 2658 [[Editor's note: while the detail error codes seem to have consensus, 2659 there is a question about whether the error codes should be 2660 extensible so that individual service providers may define site 2661 specific codes. Should all scimTypes be URIs, so that scimTypes can 2662 be registered via IANA? Should there be a separate field defined for 2663 this purpose? Or, should custom signalling (for non-protocol/schema 2664 errors, be out of scope?]] 2666 3.11. API Versioning 2668 The Base URL MAY be appended with a version identifier as a separate 2669 segment in the URL path. At this time of this specification, the 2670 identifier is 'v2'. If specified, the version identifier MUST appear 2671 in the URL path immediately preceding the resource endpoint and 2672 conform to the following scheme: the character 'v' followed by the 2673 desired SCIM version number; e.g., a version 'v2' User request is 2674 specified as /v2/Users. When specified service providers MUST 2675 perform the operation using the desired version or reject the 2676 request. When omitted service providers SHOULD perform the operation 2677 using the most recent SCIM protocol version supported by the service 2678 provider. 2680 3.12. Versioning Resources 2682 The SCIM protocol supports resource versioning via standard HTTP 2683 ETags Section 2.3 [RFC7233]. Service providers MAY support weak 2684 ETags as the preferred mechanism for performing conditional 2685 retrievals and ensuring clients do not inadvertently overwrite each 2686 others changes, respectively. When supported SCIM ETags MUST be 2687 specified as an HTTP header and SHOULD be specified within the 2688 'version' attribute contained in the resource's 'meta' attribute. 2690 Example: 2692 POST /Users HTTP/1.1 2693 Host: example.com 2694 Content-Type: application/scim+json 2695 Authorization: Bearer h480djs93hd8 2696 Content-Length: ... 2698 { 2699 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2700 "userName":"bjensen", 2701 "externalId":"bjensen", 2702 "name":{ 2703 "formatted":"Ms. Barbara J Jensen III", 2704 "familyName":"Jensen", 2705 "givenName":"Barbara" 2706 } 2707 } 2709 The server responds with an ETag in the response header and meta 2710 structure. 2712 HTTP/1.1 201 Created 2713 Content-Type: application/scim+json 2714 Location: 2715 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2716 ETag: W/"e180ee84f0671b1" 2718 { 2719 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2720 "id":"2819c223-7f76-453a-919d-413861904646", 2721 "meta":{ 2722 "resourceType":"User", 2723 "created":"2011-08-01T21:32:44.882Z", 2724 "lastModified":"2011-08-01T21:32:44.882Z", 2725 "location": 2726 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2727 "version":"W\/\"e180ee84f0671b1\"" 2728 }, 2729 "name":{ 2730 "formatted":"Ms. Barbara J Jensen III", 2731 "familyName":"Jensen", 2732 "givenName":"Barbara" 2733 }, 2734 "userName":"bjensen" 2735 } 2737 With the returned ETag, clients MAY choose to retrieve the resource 2738 only if the resource has been modified. 2740 Conditional retrieval example using If-None-Match Section 3.2 2741 [RFC7233] header: 2743 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName 2744 Host: example.com 2745 Accept: application/scim+json 2746 Authorization: Bearer h480djs93hd8 2747 If-None-Match: W/"e180ee84f0671b1" 2749 If the resource has not changed the service provider simply returns 2750 an empty body with a 304 "Not Modified" response code. 2752 If the service providers supports versioning of resources the client 2753 MAY supply an If-Match Section 3.1 [RFC7233] header for PUT and PATCH 2754 operations to ensure that the requested operation succeeds only if 2755 the supplied ETag matches the latest service provider resource; e.g., 2756 If-Match: W/"e180ee84f0671b1" 2758 4. Preparation and Comparison of Internationalized Strings 2760 To increase the likelihood that the input and comparison of unicode 2761 usernames and passwords will work in ways that make sense for typical 2762 users throughout the world there are special string preparation and 2763 comparison methods (PRECIS) that MUST be followed for usernames and 2764 passwords. Before comparing or evaluating uniqueness of a "userName" 2765 or "password" attribute, service providers MUST use the "PRECIS" 2766 profile described in Sections 4 and 5 respectively of 2767 [I-D.ietf-precis-saslprepbis] and is based on the "PRECIS" framework 2768 specification [I-D.ietf-precis-framework]. 2770 5. Multi-Tenancy 2772 A single service provider may expose the SCIM protocol to multiple 2773 clients. Depending on the nature of the service, the clients may 2774 have authority to access and alter resources initially created by 2775 other clients. Alternatively, clients may expect to access disjoint 2776 sets of resources, and may expect that their resources are 2777 inaccessible by other clients. These scenarios are called "multi- 2778 tenancy", where each client is understood to be or represent a 2779 "tenant" of the service provider. Clients may also be multi- 2780 tenanted. 2782 The following common cases may occur: 2784 1. All clients share all resources (no tenancy) 2785 2. Each single client creates and accesses a private subset of 2786 resources (1 client:1 Tenant) 2788 3. Sets of clients share sets of resources (M clients:1 Tenant) 2790 4. One client to Multiple Tenants (1 client:M Tenants) 2792 Service providers may implement any subset of the above cases. 2794 Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a 2795 scheme for multi-tenancy. 2797 The SCIM protocol does not prescribe the mechanisms whereby clients 2798 and service providers interact for: 2800 o Registering or provisioning Tenants 2802 o Associating a subset of clients with a subset of the Tenants 2804 o Indicating which tenant is associated with the data in a request 2805 or response, or indicating which Tenant is the subject of a query 2807 5.1. Associating Clients to Tenants 2809 The service provider MAY use the authentication mechanism (Section 2) 2810 to determine the identity of the client, and thus infer the 2811 associated Tenant. 2813 For implementations where a client is associated with more than one 2814 Tenant, the service provider MAY use one of the following methods for 2815 explicit specification of the Tenant. 2817 If any of these methods of allowing the client to explicitly specify 2818 the Tenant are employed, the service provider should ensure that 2819 access controls are in place to prevent or allow cross-tenant use 2820 cases. 2822 The service provider should consider precedence in cases where a 2823 client may explicitly specify a Tenant while being implicitly 2824 associated with a different Tenant. 2826 In all of these methods, the {tenant_id} is a unique identifier for 2827 the Tenant as defined by the service provider. 2829 o A URL prefix: "https://www.example.com/Tenants/{tenant_id}/v2/ 2830 Users" 2832 o A sub-domain: "https://{tenant_id}.example.com/v2/Groups" 2833 o The service provider may recognize a {tenant_id} provided by the 2834 client in an HTTP Header as the indicator of the desired target 2835 Tenant. 2837 5.2. SCIM Identifiers with Multiple Tenants 2839 Considerations for a Multi-Tenant Implementation: 2841 The service provider may choose to implement SCIM ids which are 2842 unique across all resources for all Tenants, but this is not 2843 required. 2845 The externalId, defined by the client, is required to be unique ONLY 2846 within the resources associated with the associated Tenant. 2848 6. Security Considerations 2850 6.1. TLS Support 2852 The SCIM Protocol layers on top of Hypertext Transfer Protocol and 2853 thus subject to the security considerations of HTTP Section 9 2854 [RFC7230] and its related specifications. 2856 SCIM resources (e.g., Users and Groups) can contain sensitive 2857 information. Therefore, SCIM clients and service providers MUST 2858 implement TLS. Which version(s) ought to be implemented will vary 2859 over time, and depend on the widespread deployment and known security 2860 vulnerabilities at the time of implementation. At the time of this 2861 writing, TLS version 1.2 [RFC5246] is the most recent version, but 2862 has very limited actual deployment, and might not be readily 2863 available in implementation toolkits. TLS version 1.0 [RFC5246] is 2864 the most widely deployed version, and will give the broadest 2865 interoperability. 2867 6.2. Disclosure of Sensitive Information in URIs 2869 As mentioned in ,Section 9.4 [RFC7231], SCIM clients requesting 2870 information using query filters using HTTP GET SHOULD give 2871 consideration to the information content of the filters and whether 2872 their exposure in a URI would represent a breach of security or 2873 confidentiality through leakage in a web browsers or server logs. 2874 This is particularly true for information that is legally considered 2875 "personally identifiable information" or is otherwise restricted by 2876 privacy laws. In these situations to ensure maximum security and 2877 confidentiality, clients SHOULD query using HTTP POST (see 2878 Section 3.2.3 ). 2880 Servers that receive HTTP GET requests using filters that contain 2881 restricted or confidential information SHOULD respond with HTTP 2882 status 403 indicating the operation is FORBIDDEN. A detailed error, 2883 "confidential_restricted" may be returned indicating the request must 2884 be submitted using POST. A non-normative example: 2886 HTTP/1.1 403 FORBIDDEN 2888 { 2889 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2890 "Errors":[ 2891 { 2892 "description": 2893 "Query filter involving 'name' is restricted or confidential", 2894 "error":"confidential_restricted" 2895 } 2896 ] 2897 } 2899 6.3. Anonymous Requests 2901 If a SCIM service provider accepts anonymous requests such as SCIM 2902 resource creation requests (via HTTP POST), appropriate security 2903 measures should be put in place to prevent or limit exposure to 2904 attacks. The following counter-measures MAY be used: 2906 o Try to authenticate web UI components that forumulate the SCIM 2907 creation request. While the end-user MAY be anonymous, the web 2908 user interface component often has its own way to authenticate to 2909 the SCIM service provider (e.g. has an OAuth Client Credential 2910 [RFC6749]) and the web user interface component may implement its 2911 own measures (e.g. such as CAPTCHA) to ensure a ligitimate request 2912 is being made. 2914 o Limit the number of requests any particular client MAY make in a 2915 period of time. 2917 o For User resources, default newly created resource with an 2918 "active" setting of "false" and use a secondary confirmation 2919 process (e.g. email confirmation) to ensure the resource created 2920 is real. 2922 6.4. HTTP Considerations 2924 As an HTTP based protocol, implementers of SCIM SHOULD consider all 2925 security considerations of the HTTP/1.1 as enumerated in Section 1 2926 [RFC7230] 2927 As stated in Section 2.7.1 [RFC7230], a SCIM client MUST NOT generate 2928 the userinfo (i.e. username and password) component (and its "@" 2929 delimiter) when an "http" URI reference is generated with a message 2930 as they are now disallowed in HTTP. 2932 6.5. Secure Storage and Handling of Sensitive Data 2934 An attacker may obtain valid username/password combinations from the 2935 SCIM service provider's underlying database by gaining access to the 2936 database and/or launching injection attacks. This could lead to 2937 unintended disclosure of username/password combinations. The impact 2938 may extend beyond the domain of the SCIM service provider if the data 2939 was provisioned from other domains. 2941 Administrators should undertake industry best practices to protect 2942 the storage of credentials and in particular SHOULD follow 2943 recommendations outlines in Section 5.1.4.1 [RFC6819]. These 2944 recommendations include but are not limited to: 2946 o Provide injection attack counter measures (e.g. by validating all 2947 inputs and parameters), 2949 o No cleartext storage of credentials, 2951 o Store credentials using an encrypted protection mechanism, and 2953 o Avoid passwords and consider use of asymmetric cryptography based 2954 credentials. 2956 As outlined in Section 5.1.4.2 [RFC6819], adminitrators SHOULD take 2957 counter measures to prevent online attacks on secrets such as: 2959 o Utilize secure password policy in order to increase user password 2960 entrophy to hinder online attacks and password guessing, 2962 o Mitigate attacks on passwords by locking respective accounts have 2963 a number of failed attempts, 2965 o Use "tar pit" techniques by temporarily locking a respective 2966 account and delaying responses for a certain duration. The 2967 duration may increase with the number of failed attempts, and 2969 o Use authentication system that use CAPTCHA's and other factors for 2970 authenticating users further reducing the possibility of automated 2971 attacks. 2973 6.6. Case Insensitive Comparision & International Languages 2975 When comparing unicode strings such as in query filters or testing 2976 for uniqueness of usernames and passwords, strings MUST be 2977 appopriately prepared before comparison. See Section 4. 2979 7. IANA Considerations 2981 7.1. Media Type Registration 2983 To: ietf-types@iana.org 2985 Subject: Registration of media type application/scim+json 2987 Type name: application 2989 Subtype name: scim+json 2991 Required parameters: none 2993 Optional parameters: none 2995 Encoding considerations: 8bit 2997 Security considerations: See Section 6 2999 Interoperability considerations: The "application/scim+json" media 3000 type is intended to identify JSON structure data that conforms to 3001 the SCIM protocol and schema specifications. Older versions of 3002 SCIM are known to informally use "application/json". 3004 Published specification: [[this document]] 3006 Applications that use this media type: It is expected that 3007 applications that use this type may be special purpose 3008 applications intended for inter-domain provisioning. Clients may 3009 also be applications (e.g. mobile applications) that need to use 3010 SCIM for self-registration of user accounts. SCIM services may be 3011 offered by web applications that offer support for standards based 3012 provisioning or may be a dedicated SCIM service provider such as a 3013 "cloud directory". Content may be treated as equivalent to 3014 "application/json" type for the purpose of displaying in web 3015 browsers. 3017 Additional information: 3019 Magic number(s): 3021 File extension(s): .scim .scm 3023 Macintosh file type code(s): 3025 Person & email address to contact for futher information: SCIM 3026 mailing list "" 3028 Intended usage: COMMON* (see restrictions) 3030 Restrictions on usage: For most client types, it is sufficient to 3031 recognize the content as equivalent to "application/json". 3032 Applications intending to use SCIM protocol SHOULD use the 3033 application/scim+json media type. 3035 Author: Phil Hunt 3037 Change controller: IETF 3039 7.2. SCIM Message URI Registry 3041 As per the IANA SCIM Schema Registry in [I-D.ietf-scim-core-schema], 3042 the following registers and extends the SCIM Schema Registry to 3043 define SCIM protocol request/response JSON schema URN identifier 3044 prefix of "urn:ietf:params:scim:api:messages:2.0" which is part of 3045 the URN sub-Namespace for SCIM. There is no specific associated 3046 resource type. 3048 +---------------------------------+-----------------+---------------+ 3049 | Schema URI | Name | Reference | 3050 +---------------------------------+-----------------+---------------+ 3051 | urn:ietf:params:scim:api: | List/Query | See Section | 3052 | messages:2.0:ListResponse | Response | 3.2.2 | 3053 | urn:ietf:params:scim:api: | POST Query | See Section | 3054 | messages:2.0:SearchRequest | Request | 3.2.3 | 3055 | urn:ietf:params:scim:api: | Patch Operation | See Section | 3056 | messages:2.0:PatchOp | | 3.3.2 | 3057 | urn:ietf:params:scim:api: | Bulk Operations | See Section | 3058 | messages:2.0:BulkRequest | Request | 3.5 | 3059 | urn:ietf:params:scim:api: | Bulk Operations | See Section | 3060 | messages:2.0:BulkResponse | Response | 3.5 | 3061 | urn:ietf:params:scim:api: | Error Response | See Section | 3062 | messages:2.0:Error | | 3.10 | 3063 +---------------------------------+-----------------+---------------+ 3065 Table 9: SCIM Schema URIs for Data Resources 3067 8. References 3069 8.1. Normative References 3071 [I-D.ietf-precis-saslprepbis] 3072 Saint-Andre, P. and A. Melnikov, "Preparation, 3073 Enforcement, and Comparison of Internationalized Strings 3074 Representing Usernames and Passwords", draft-ietf-precis- 3075 saslprepbis-09 (work in progress), October 2014. 3077 [I-D.ietf-scim-core-schema] 3078 Hunt, P., Grizzle, K., Wahlstroem, E., and C. Mortimore, 3079 "System for Cross-Domain Identity Management: Core 3080 Schema", draft-ietf-scim-core-schema-13 (work in 3081 progress), November 2014. 3083 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3084 Requirement Levels", BCP 14, RFC 2119, March 1997. 3086 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3087 10646", STD 63, RFC 3629, November 2003. 3089 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3090 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3091 3986, January 2005. 3093 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 3094 Specifications: ABNF", STD 68, RFC 5234, January 2008. 3096 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3097 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3099 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 3100 5789, March 2010. 3102 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 3103 Interchange Format", RFC 7159, March 2014. 3105 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3106 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 3107 2014. 3109 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3110 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 3112 [RFC7233] Fielding, R., Lafon, Y., and J. Reschke, "Hypertext 3113 Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, 3114 June 2014. 3116 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3117 (HTTP/1.1): Authentication", RFC 7235, June 2014. 3119 8.2. Informative References 3121 [I-D.ietf-precis-framework] 3122 Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 3123 Preparation, Enforcement, and Comparison of 3124 Internationalized Strings in Application Protocols", 3125 draft-ietf-precis-framework-19 (work in progress), October 3126 2014. 3128 [OpenSearch] 3129 Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . 3131 [Order-Operations] 3132 Wikipedia, "Order of Operations: Programming Languages", . 3134 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 3135 6749, October 2012. 3137 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 3138 Framework: Bearer Token Usage", RFC 6750, October 2012. 3140 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 3141 Threat Model and Security Considerations", RFC 6819, 3142 January 2013. 3144 [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation 3145 (JSON) Patch", RFC 6902, April 2013. 3147 [RFC7238] Reschke, J., "The Hypertext Transfer Protocol Status Code 3148 308 (Permanent Redirect)", RFC 7238, June 2014. 3150 Appendix A. Contributors 3152 Samuel Erdtman (samuel@erdtman.se) 3154 Patrick Harding (pharding@pingidentity.com) 3156 Appendix B. Acknowledgments 3158 The editors would like to acknowledge the contribution and work of 3159 the past draft editors: 3161 Trey Drake, UnboundID 3163 Chuck Mortimore, Salesforce 3165 The editor would like to thank the participants in the the SCIM 3166 working group for their support of this specification. 3168 Appendix C. Change Log 3170 [[This section to be removed prior to publication as an RFC]] 3172 Draft 02 - KG - Addition of schema extensibility 3174 Draft 03 - PH - Revisions based on following tickets: 3176 24 - Add filter negation 3178 39 - Clarification on response for DELETE 3180 42 - Make root searches optional 3182 49 - Add "ew" filter 3184 50 - Filters for multi-valued complex attributes 3186 51 - Search by Schema 3188 53 - Standard use of term client (some was consumer) 3190 55 - Redirect support (3xx) 3192 56 - Make manager attribute consistent with other $ref attrs 3194 57 - Update all "/v1" examples to '/v2" 3196 59 - Fix capitalization per IETF editor practices 3198 60 - Changed tags to normal and tags 3200 Draft 04 - PH - Revisions based on the following tickets: 3202 18 - New PATCH command based on JSON Patch (RFC6902) 3204 - Provided ABNF specification for filters (used in PATCH) 3206 - Updated references to RFC4627 to RFC7159 3208 Draft 05 - PH - Revisions based on the following tickets: 3210 03 - Support for excludedAttributes parameter 3212 13 - Change client use of Etags from MUST to MAY (correction) 3213 23 - Clarifications regarding case exact processing. 3215 41 - Add IANA considerations 3217 65 - Removed X-HTTP-Method-Override support 3219 69 - Added clarifications to intro to align with draft-nottingham- 3220 uri-get-off-my-lawn 3222 70 - Remove SCIM_TENANT_ID header 3224 72 - Added text to indicate UTF-8 is default and mandatory 3225 encoding format per BCP18 3227 74 - Added security considerations for using GET with confidential 3228 attribute filters 3230 - corrected error response in JSON PATCH operation 3232 Draft 06 - PH - Revisions based on the following tickets and 3233 editorial changes 3235 41 - Revised content types from application/json to application/ 3236 scim+json, registered API schemas 3238 63 - Revised uri schema prefixes for API json message schemas 3240 66 - Updated references for RFC2616 to HTTPbis 3242 75 - Added security considerations for International Strings and 3243 "PRECIS" support 3245 76 - Clarified handling of PUT (& POST) with regards to mutability 3246 and default values 3248 - Corrected version numbers in sec 3.11 API Versioning to v2 (from 3249 v1) 3251 - Clarified that no filter matches should return success 3252 totalResults=0 3254 Draft 07 - PH - Revisions regarding support of detailed errors 3255 (Tickets 37, 46, 67) 3257 Draft 08 - PH - Revisions as follows 3259 - Added clarification on schemas handling during PATCH operation 3260 - Revised example URN in Attribute Notation section to comply with 3261 IANA namespace rules 3263 - Fixed typo in ABNF, attrExpr should be attrExp 3265 - Added more security considerations for HTTP and sensitive data 3267 - Revised authentication and authorization sections for greater 3268 clarity. 3270 - Replaced the word "search" with "query" for consistency 3272 - Clarified sucessful resource creation response 3274 - Added clarification on primary value handling in PATCH 3275 (consistent with draft 03) 3277 - Revised SCIM Bullk error handling to conform with draft 07 error 3278 handling 3280 Draft 09 - PH - Revisions as follows 3282 - Aligned API with new URN namespace per RFC3553 and IETF90 3283 meeting 3285 - Clarified URN usage within patch (what schema urn applies) 3287 - Made 'path' optional in PATCH for Add and Replace 3289 Draft 10 - PH - Revisions as follows 3291 Restructuring of Bulk into sub-sections 3293 General clarifications 3295 Improved Base URI section 3297 Authorization section clarifications 3299 Draft 11 - PH - Revisions as follows 3301 Made mutability processing rules for CREATE more editorially 3302 obvious 3304 Added clarfications and security considerations for Anonymous 3305 operations 3307 Added clarifications to "/Me" for POST requests 3308 Clarified use of bulkids with multiple requests 3310 Corrected JSON parsing issue by adding "Operations" attribute to 3311 PATCH operation 3313 Draft 12 - PH - Editorial NITs 3315 Fix line lengths in artwork to be 72 chars or less 3317 Remove unused references 3319 Fix normative terms per RFC2119 3321 Updated reference to draft-reschke-http-status-308 to RFC7238 3323 Draft 13 - PH - Added clarification to error response for improperly 3324 formated email/phonenumbers 3326 Authors' Addresses 3328 Phil Hunt (editor) 3329 Oracle Corporation 3331 Email: phil.hunt@yahoo.com 3333 Kelly Grizzle 3334 SailPoint 3336 Email: kelly.grizzle@sailpoint.com 3338 Morteza Ansari 3339 Cisco 3341 Email: morteza.ansari@cisco.com 3343 Erik Wahlstroem 3344 Technology Nexus 3346 Email: erik.wahlstrom@nexusgroup.com 3348 Chuck Mortimore 3349 Salesforce.com 3351 Email: cmortimore@salesforce.com