idnits 2.17.1 draft-ietf-scim-api-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 36 instances of too long lines in the document, the longest one being 28 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: +------------+-------------------+----------------------------------+ | Parameter | Description | Default | +------------+-------------------+----------------------------------+ | startIndex | The 1-based index | 1 | | | of the first | | | | search result. | | | count | Non-negative | None. When specified the service | | | Integer. | provider MUST not return more | | | Specifies the | results than specified though | | | desired maximum | MAY return fewer results. If | | | number of search | unspecified, the maximum number | | | results per page; | of results is set by the service | | | e.g., 10. | provider. | +------------+-------------------+----------------------------------+ == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: Each operation against an attribute MUST be compatible with the attribute's mutability and schema as defined in the Attribute Types Section of [I-D.ietf-scim-core-schema]. For example, a client MAY NOT modify an attribute that has mutability "readOnly"or "immutable". However, a client MAY "add" a value to an"immutable" attribute if the attribute had no previous value. An operation that is not compatibile with an attribute's mutability or schema SHALL return an error as indicated below. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Clients request resource removal via DELETE. Service providers MAY choose not to permanently delete the resource, but MUST return a 404 error code for all operations associated with the previously deleted Id. Service providers MUST also omit the resource from future query results. In addition the service provider MUST not consider the deleted resource in conflict calculation. For example if a User resource is deleted, a CREATE request for a User resource with the same userName as the previously deleted resource should not fail with a 409 error due to userName conflict. -- The document date (May 13, 2014) is 3630 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC2277' is defined on line 2581, but no explicit reference was found in the text == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-25 == Outdated reference: A later version (-22) exists of draft-ietf-scim-core-schema-03 ** Downref: Normative reference to an Experimental draft: draft-reschke-http-status-308 (ref. 'I-D.reschke-http-status-308') ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 6 errors (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Hunt, Ed. 3 Internet-Draft Oracle 4 Intended status: Standards Track K. Grizzle 5 Expires: November 14, 2014 SailPoint 6 M. Ansari 7 Cisco 8 E. Wahlstroem 9 Technology Nexus 10 C. Mortimore 11 Salesforce 12 May 13, 2014 14 System for Cross-Domain Identity Management:Protocol 15 draft-ietf-scim-api-05 17 Abstract 19 The System for Cross-Domain Identity Management (SCIM) specification 20 is designed to make managing user identity in cloud based 21 applications and services easier. The specification suite seeks to 22 build upon experience with existing schemas and deployments, placing 23 specific emphasis on simplicity of development and integration, while 24 applying existing authentication, authorization, and privacy models. 25 It's intent is to reduce the cost and complexity of user management 26 operations by providing a common user schema and extension model, as 27 well as binding documents to provide patterns for exchanging this 28 schema using standard protocols. In essence, make it fast, cheap, 29 and easy to move users in to, out of, and around the cloud. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on November 14, 2014. 48 Copyright Notice 50 Copyright (c) 2014 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 66 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3 67 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3 68 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 69 2. Authentication and Authorization . . . . . . . . . . . . . . 4 70 3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 71 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 7 72 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 8 73 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 8 74 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 8 75 3.2.2. List/Query Resources . . . . . . . . . . . . . . . . 10 76 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 20 77 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 22 78 3.3.1. Modifying with PUT . . . . . . . . . . . . . . . . . 23 79 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 25 80 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 34 81 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 35 82 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 50 83 3.7. Additional Operation Response Parameters . . . . . . . . 51 84 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 52 85 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 53 86 3.10. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 53 87 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 55 88 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 55 89 4. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 57 90 4.1. Associating Clients to Tenants . . . . . . . . . . . . . 58 91 4.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 58 92 5. Security Considerations . . . . . . . . . . . . . . . . . . . 59 93 5.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 59 94 5.2. Querying Using HTTP GET . . . . . . . . . . . . . . . . . 59 95 5.3. Universal Identifiers . . . . . . . . . . . . . . . . . . 60 97 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 98 6.1. Media Type Registration . . . . . . . . . . . . . . . . . 60 99 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 61 100 7.1. Normative References . . . . . . . . . . . . . . . . . . 61 101 7.2. Informative References . . . . . . . . . . . . . . . . . 62 102 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 62 103 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 62 104 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 63 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 64 107 1. Introduction and Overview 109 The SCIM Protocol is an application-level, HTTP protocol for 110 provisioning and managing identity data on the web. The protocol 111 supports creation, modification, retrieval, and discovery of core 112 identity resources; i.e., Users and Groups, as well as custom 113 resource extensions. 115 1.1. Intended Audience 117 This document is intended as a guide to SCIM API usage for both 118 identity service providers and clients. 120 1.2. Notational Conventions 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 124 document are to be interpreted as described in [RFC2119]. These 125 keywords are capitalized when used to unambiguously specify 126 requirements of the protocol or application features and behavior 127 that affect the interoperability and security of implementations. 128 When these words are not capitalized, they are meant in their 129 natural-language sense. 131 For purposes of readability examples are not URL encoded. 132 Implementers MUST percent encode URLs as described in Section 2.1 133 [RFC3986]. 135 1.3. Definitions 137 Base URL: The SCIM HTTP API is always relative to a Base URL. The 138 Base URL MUST NOT contain a query string as clients may append 139 additional path information and query parameters as part of 140 forming the request. Example: "https://example.com/scim/" 142 For readability, all examples in this document are expressed 143 assuming the SCIM service root and the server root are the same. 144 It is expected that SCIM servers may be deployed using any URI 145 prefix. For example, a SCIM server might be have a prefix of 146 "https://example.com/", or "https://example.com/scim/tenancypath/ 147 ". Additionally client may also apply a version number to the 148 server root prefix (see Section 3.11). 150 2. Authentication and Authorization 152 The SCIM protocol does not define a scheme for authentication and 153 authorization therefore implementers are free to choose mechanisms 154 appropriate to their use cases. The choice of authentication 155 mechanism will impact interoperability. It is RECOMMENDED that 156 clients be implemented in such a way that new authentication schemes 157 can be deployed. Implementers SHOULD support existing authentication 158 /authorization schemes. In particular, OAuth2[RFC6750] is 159 RECOMMENDED. Appropriate security considerations of the selected 160 authentication and authorization schemes SHOULD be taken. Because 161 this protocol uses HTTP response status codes as the primary means of 162 reporting the result of a request, servers are advised to respond to 163 unauthorized or unauthenticated requests using the 401 response code 164 in accordance with section 10.4.2 of Section 10.4.2 [RFC2616]. 166 All examples assume OAuth2 bearer token [RFC6750]; e.g., 168 GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 169 Host: example.com 170 Authorization: Bearer h480djs93hd8 172 The context of the request (i.e. the user for whom data is being 173 requested) MUST be inferred by service providers. 175 3. API 177 The SCIM protocol specifies well known endpoints and HTTP methods for 178 managing resources defined in the core schema; i.e., "User" and 179 "Group" resources correspond to "/Users" and "/Groups" respectively. 180 Service providers that support extended resources SHOULD define 181 resource endpoints using the established convention; pluralize the 182 resource name defined in the extended schema by appending an 's'. 183 Given there are cases where resource pluralization is ambiguous; 184 e.g., a resource named "Person" is legitimately "Persons" and 185 "People" clients SHOULD discover resource endpoints via the "/ 186 ResourceTypes" endpoint . 188 GET Retrieves a complete or partial resource. 190 POST Create new resource, perform an extended Search, or bulk modify 191 resources. 193 PUT Modifies a resource with a complete, client specified resource 194 (replace). 196 PATCH Modifies a resource with a set of client specified changes 197 (partial update). 199 DELETE Deletes a resource. 201 +------------+--------------------+---------------+-----------------+ 202 | Resource | Endpoint | Operations | Description | 203 +------------+--------------------+---------------+-----------------+ 204 | User | /Users | GET (Section | Retrieve/Add/Mo | 205 | | | 3.2.1), POST | dify Users | 206 | | | (Section | | 207 | | | 3.1), PUT | | 208 | | | (Section | | 209 | | | 3.3.1), PATCH | | 210 | | | (Section | | 211 | | | 3.3.2), | | 212 | | | DELETE | | 213 | | | (Section 3.4) | | 214 | Group | /Groups | GET (Section | Retrieve/Add/Mo | 215 | | | 3.2.1), POST | dify Groups | 216 | | | (Section | | 217 | | | 3.1), PUT | | 218 | | | (Section | | 219 | | | 3.3.1), PATCH | | 220 | | | (Section | | 221 | | | 3.3.2), | | 222 | | | DELETE | | 223 | | | (Section 3.4) | | 224 | Service | /ServiceProviderCo | GET (Section | Retrieve the | 225 | Provider C | nfigs | 3.2.1) | service | 226 | onfigurati | | | provider's | 227 | on | | | configuration | 228 | Resource | /ResourceTypes | GET (Section | Retrieve the | 229 | Type | | 3.2.1) | supported | 230 | | | | resource types | 231 | Schema | /Schemas | GET (Section | Retrieve a | 232 | | | 3.2.1) | resource's | 233 | | | | schema | 234 | Bulk | /Bulk | POST (Section | Bulk modify | 235 | | | 3.5) | resources | 236 | Search | [prefix]/.search | POST (Section | Perform a | 237 | | | 3.2.3) | search at | 238 | | | | system root or | 239 | | | | within a | 240 | | | | resource | 241 | | | | endpoint for | 242 | | | | one or more | 243 | | | | resource types | 244 | | | | using POST. | 245 +------------+--------------------+---------------+-----------------+ 247 Table 1: Defined endpoints 249 All requests to the service provider are made via Section 9 [RFC2616] 250 on a URL derived from the Base URL. Responses are returned in the 251 body of the HTTP response, formatted as JSON. Response and error 252 codes SHOULD be transmitted via the HTTP status code of the response 253 (if possible), and SHOULD also be specified in the body of the 254 response. 256 3.1. Creating Resources 258 To create new resources, clients send POST requests to the resource 259 endpoint; i.e., "/Users" or "/Groups". 261 Successful resource creation is indicated with a 201 ("Created") 262 response code. Upon successful creation, the response body MUST 263 contain the newly created resource. Since the server is free to 264 alter and/or ignore POSTed content, returning the full representation 265 can be useful to the client, enabling it to correlate the client and 266 server views of the new resource. When a resource is created, its 267 URI must be returned in the response Location header. 269 If the service provider determines creation of the requested resource 270 conflicts with existing resources; e.g., a "User" resource with a 271 duplicate "userName", the service provider MUST return a 409 error 272 and SHOULD indicate the conflicting attribute(s) in the body of the 273 response. 275 Below, the client sends a POST request containing a user 277 POST /Users HTTP/1.1 278 Host: example.com 279 Accept: application/json 280 Content-Type: application/json 281 Authorization: Bearer h480djs93hd8 282 Content-Length: ... 284 { 285 "schemas":["urn:scim:schemas:core:2.0:User"], 286 "userName":"bjensen", 287 "externalId":"bjensen", 288 "name":{ 289 "formatted":"Ms. Barbara J Jensen III", 290 "familyName":"Jensen", 291 "givenName":"Barbara" 292 } 293 } 294 The server signals a successful creation with a status code of 201. 295 The response includes a Location header indicating the User URI, and 296 a representation of that user in the body of the response. 298 HTTP/1.1 201 Created 299 Content-Type: application/json 300 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 301 ETag: W/"e180ee84f0671b1" 303 { 304 "schemas":["urn:scim:schemas:core:2.0:User"], 305 "id":"2819c223-7f76-453a-919d-413861904646", 306 "externalId":"bjensen", 307 "meta":{ 308 "resourceType":"User", 309 "created":"2011-08-01T21:32:44.882Z", 310 "lastModified":"2011-08-01T21:32:44.882Z", 311 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 312 "version":"W\/\"e180ee84f0671b1\"" 313 }, 314 "name":{ 315 "formatted":"Ms. Barbara J Jensen III", 316 "familyName":"Jensen", 317 "givenName":"Barbara" 318 }, 319 "userName":"bjensen" 320 } 322 3.1.1. Resource Types 324 When adding a resource to a specific endpoint, the meta attribute 325 "resourceType" SHALL be set by the service provider to the 326 corresponding resource Type for the endpoint. For example, "/Users" 327 will set "resourceType" to "User", and "/Groups" will set 328 "resourceType" to "Group". 330 3.2. Retrieving Resources 332 "User" and "Group" resources are retrieved via opaque, unique URLs or 333 via Query. Service providers MAY choose to respond with a sub-set of 334 resource attributes, though MUST minimally return the resource id and 335 meta attributes. 337 3.2.1. Retrieving a known Resource 339 To retrieve a known resource, clients send GET requests to the 340 resource endpoint; e.g., "/Users/{id}" or "/Groups/{id}". 342 If the resource exists the server responds with a status code of 200 343 and includes the result in the body of the response. 345 The below example retrieves a single User via the "/Users" endpoint. 347 GET /Users/2819c223-7f76-453a-919d-413861904646 348 Host: example.com 349 Accept: application/json 350 Authorization: Bearer h480djs93hd8 352 The server responds with: 354 HTTP/1.1 200 OK 355 Content-Type: application/json 356 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 357 ETag: W/"f250dd84f0671c3" 359 { 360 "schemas":["urn:scim:schemas:core:2.0:User"], 361 "id":"2819c223-7f76-453a-919d-413861904646", 362 "externalId":"bjensen", 363 "meta":{ 364 "resourceType":"User", 365 "created":"2011-08-01T18:29:49.793Z", 366 "lastModified":"2011-08-01T18:29:49.793Z", 367 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 368 "version":"W\/\"f250dd84f0671c3\"" 369 }, 370 "name":{ 371 "formatted":"Ms. Barbara J Jensen III", 372 "familyName":"Jensen", 373 "givenName":"Barbara" 374 }, 375 "userName":"bjensen", 376 "phoneNumbers":[ 377 { 378 "value":"555-555-8377", 379 "type":"work" 380 } 381 ], 382 "emails":[ 383 { 384 "value":"bjensen@example.com", 385 "type":"work" 386 } 387 ] 388 } 389 3.2.2. List/Query Resources 391 SCIM defines a standard set of operations that can be used to filter, 392 sort, and paginate response results. The operations are specified by 393 adding query parameters to the resource's endpoint. Service 394 providers MAY support additional query parameters not specified here, 395 and Providers SHOULD ignore any query parameters they don't 396 recognize. 398 List and query responses MUST be identified using the following URI: 399 "urn:scim:schemas:core:2.0:ListResponse". The following attributes 400 are defined for list and query responses: 402 totalResults The total number of results returned by the list or 403 query operation. This may not be equal to the number of elements 404 in the resources attribute of the list response if pagination 405 (Section 3.2.2.4) is requested. REQUIRED. 407 Resources A multi-valued list of complex objects containing the 408 requested resources. This may be a subset of the full set of 409 resources if pagination (Section 3.2.2.4) is requested. REQUIRED. 411 startIndex The 1-based index of the first result in the current set 412 of list results. REQUIRED if pagination (Section 3.2.2.4) is 413 requested. 415 itemsPerPage The number of resources returned in a list response 416 page. REQUIRED if pagination (Section 3.2.2.4) is requested. 418 The query example below requests the userName for all Users: 420 GET /Users?attributes=userName 421 Host: example.com 422 Accept: application/json 423 Authorization: Bearer h480djs93hd8 424 The following is an example response to the query above: 426 HTTP/1.1 200 OK 427 Content-Type: application/json 429 { 430 "schemas":["urn:scim:schemas:core:2.0:ListResponse"], 431 "totalResults":2, 432 "Resources":[ 433 { 434 "userName":"bjensen" 435 }, 436 { 437 "userName":"jsmith" 438 } 439 ] 440 } 442 3.2.2.1. Query Endpoints 444 Queries MAY be performed against a SCIM resource object or a resource 445 type endpoint. For example: 447 "/Users/{userid}" 449 "/Users" 451 "/Groups" 453 A server MAY support searches against the server root (e.g. "/"). A 454 search against a server root indicates that ALL resources within the 455 server SHALL be included subject to filtering. A filter expression 456 using "meta.resourceType" MAY be used to restrict results to one or 457 more specific resource types (e.g. "User"). 459 When processing search operations across endpoints that include more 460 than one SCIM resource type (e.g. a search from the server root 461 endpoint), filters MUST be processed in the same fashion as outlined 462 in Section 3.2.2.2. For filtered attributes that are not part of a 463 particular resource type, the service provider SHALL treat the 464 attribute as if there is no attribute value. For example, a presence 465 or equality filter for an undefined attribute evaluates as FALSE. 467 3.2.2.2. Filtering 469 Filtering is OPTIONAL. Clients may request a subset of resources by 470 specifying the 'filter' URL query parameter containing a filter 471 expression. When specified only those resources matching the filter 472 expression SHALL be returned. The expression language that is used 473 in the filter parameter supports references to attributes and 474 literals. 476 The attribute name and attribute operator are case insensitive. For 477 example, the following two expressions will evaluate to the same 478 logical value: 480 filter=userName Eq "john" 482 filter=Username eq "john" 484 The filter parameter MUST contain at least one valid Boolean 485 expression. Each expression MUST contain an attribute name followed 486 by an attribute operator and optional value. Multiple expressions 487 MAY be combined using the two logical operators. Furthermore 488 expressions can be grouped together using "()". 490 The operators supported in the expression are listed in the following 491 table. 493 +----------+-------------+------------------------------------------+ 494 | Operator | Description | Behavior | 495 +----------+-------------+------------------------------------------+ 496 | eq | equal | The attribute and operator values must | 497 | | | be identical for a match. | 498 | ne | not equal | The attribute and operator values are | 499 | | | not identical. | 500 | co | contains | The entire operator value must be a | 501 | | | substring of the attribute value for a | 502 | | | match. | 503 | sw | starts with | The entire operator value must be a | 504 | | | substring of the attribute value, | 505 | | | starting at the beginning of the | 506 | | | attribute value. This criterion is | 507 | | | satisfied if the two strings are | 508 | | | identical. | 509 | ew | ends with | The entire operator value must be a | 510 | | | substring of the attribute value, | 511 | | | matching at the end of the attribute | 512 | | | value. This criterion is satisfied if | 513 | | | the two strings are identical. | 514 | pr | present | If the attribute has a non-empty value, | 515 | | (has value) | or if it contains a non-empty node for | 516 | | | complex attributes there is a match. | 517 | gt | greater | If the attribute value is greater than | 518 | | than | operator value, there is a match. The | 519 | | | actual comparison is dependent on the | 520 | | | attribute type. For string attribute | 521 | | | types, this is a lexicographical | 522 | | | comparison and for DateTime types, it is | 523 | | | a chronological comparison. | 524 | ge | greater | If the attribute value is greater than | 525 | | than or | or equal to the operator value, there is | 526 | | equal | a match. The actual comparison is | 527 | | | dependent on the attribute type. For | 528 | | | string attribute types, this is a | 529 | | | lexicographical comparison and for | 530 | | | DateTime types, it is a chronological | 531 | | | comparison. | 532 | lt | less than | If the attribute value is less than | 533 | | | operator value, there is a match. The | 534 | | | actual comparison is dependent on the | 535 | | | attribute type. For string attribute | 536 | | | types, this is a lexicographical | 537 | | | comparison and for DateTime types, it is | 538 | | | a chronological comparison. | 539 | le | less than | If the attribute value is less than or | 540 | | or equal | equal to the operator value, there is a | 541 | | | match. The actual comparison is | 542 | | | dependent on the attribute type. For | 543 | | | string attribute types, this is a | 544 | | | lexicographical comparison and for | 545 | | | DateTime types, it is a chronological | 546 | | | comparison. | 547 +----------+-------------+------------------------------------------+ 549 Table 2: Attribute Operators 551 +----------+-------------+------------------------------------------+ 552 | Operator | Description | Behavior | 553 +----------+-------------+------------------------------------------+ 554 | and | Logical And | The filter is only a match if both | 555 | | | expressions evaluate to true. | 556 | or | Logical or | The filter is a match if either | 557 | | | expression evaluates to true. | 558 | not | Not | The filter is a match if the expression | 559 | | function | evaluates to false. | 560 +----------+-------------+------------------------------------------+ 562 Table 3: Logical Operators 564 +----------+-------------+------------------------------------------+ 565 | Operator | Description | Behavior | 566 +----------+-------------+------------------------------------------+ 567 | ( ) | Precedence | Boolean expressions may be grouped using | 568 | | grouping | parentheses to change the standard order | 569 | | | of operations; i.e., evaluate OR logical | 570 | | | operators before logical AND operators. | 571 | [ ] | Complex | Service providers MAY support complex | 572 | | attribute | filters where expressions MUST be | 573 | | filter | applied to the same value of a parent | 574 | | grouping | attribute specified immediately before | 575 | | | the left square bracket ("["). The | 576 | | | expression within square brackets ("[" | 577 | | | and "]") MUST be a valid filter | 578 | | | expression based upon sub-attributes of | 579 | | | the parent attribute. Nested expressions | 580 | | | MAY be used. See examples below. | 581 +----------+-------------+------------------------------------------+ 583 Table 4: Grouping Operators 585 SCIM filters MUST conform to the following ABNF rules as per 586 [RFC5234] below: 588 FILTER = attrExp / logExp / valuePath / *1"not" "(" FILTER ")" 590 valuePath = attrPath "[" FILTER "]" 591 ; FILTER uses sub-attribs of a parent attrPath 593 ATTRNAME = ALPHA *(nameChar) 595 nameChar = "-" / "_" / DIGIT / ALPHA 597 attrPath = [URI ":"] ATTRNAME *1subAttr 598 ; SCIM attribute name 599 ; URI is SCIM "schema" URI 601 subAttr = "." ATTRNAME 602 ; a sub-attribute of a complex attribute 604 attrExpr = (attrPath SP "pr") / 605 (attrPath SP compareOp SP compValue) 607 compValue = false / null / true / number / string 608 ; rules from JSON (RFC7159) 610 compareOp = "eq" / "ne" / "co" / 611 "sw" / "ew" / 612 "gt" / "lt" / 613 "ge" / "le" 615 logExp = FILTER ("and" / "or") FILTER 617 Figure 1: ABNF Specification of SCIM Filters 619 In the above ABNF, the "compValue" (comparison value) rule is built 620 on JSON Data Interchange format ABNF rules as specified in [RFC7159], 621 "DIGIT" and "ALPHA" are defined per Appendix B.1 of [RFC5234] and, 622 "URI" is defined per Appendix A of [RFC3986]. 624 Filters MUST be evaluated using standard order of operations 625 [Order-Operations]. Attribute operators have the highest precedence, 626 followed by the grouping operator (i.e, parentheses), followed by the 627 logical AND operator, followed by the logical OR operator. 629 If the specified attribute in a filter expression is a multi-valued 630 attribute, the resource MUST match if any of the instances of the 631 given attribute match the specified criterion; e.g. if a User has 632 multiple emails values, only one has to match for the entire User to 633 match. For complex attributes, a fully qualified Sub-Attribute MUST 634 be specified using standard attribute notation (Section 3.8). For 635 example, to filter by userName the parameter value is userName and to 636 filter by first name, the parameter value is name.givenName. 638 Providers MAY support additional filter operations if they choose. 639 Providers MUST decline to filter results if the specified filter 640 operation is not recognized and return a HTTP 400 error with an 641 appropriate human readable response. For example, if a client 642 specified an unsupported operator named 'regex' the service provider 643 should specify an error response description identifying the client 644 error; e.g., 'The operator 'regex' is not supported.' 646 String type attributes are case insensitive by default unless the 647 attribute type is defined as case exact. Attribute comparison 648 operators 'eq', 'co', and 'sw' MUST perform caseIgnore matching for 649 all string attributes unless the attribute is defined as case exact. 650 By default all string attributes are case insensitive. 652 Clients MAY search by schema or schema extensions by using a filter 653 expression including the "schemas" attribute. 655 The following are examples of valid filters. Some attributes (e.g. 656 rooms and rooms.number) are hypothetical extensions and are not part 657 of SCIM core schema: 659 filter=userName eq "bjensen" 661 filter=name.familyName co "O'Malley" 663 filter=userName sw "J" 665 filter=title pr 667 filter=meta.lastModified gt "2011-05-13T04:42:34Z" 669 filter=meta.lastModified ge "2011-05-13T04:42:34Z" 671 filter=meta.lastModified lt "2011-05-13T04:42:34Z" 673 filter=meta.lastModified le "2011-05-13T04:42:34Z" 675 filter=title pr and userType eq "Employee" 677 filter=title pr or userType eq "Intern" 679 filter=schemas eq "urn:scim:schemas:extension:enterprise:2.0:User" 681 filter=userType eq "Employee" and (emails co "example.com" or emails 682 co "example.org") 684 filter=userType ne "Employee" and not (emails co "example.com" or 685 emails co "example.org") 687 filter=userType eq "Employee" and (emails.type eq "work") 689 filter=userType eq "Employee" and emails[type eq "work" and 690 value co "@example.com"] 692 filter=emails[type eq "work" and value co "@example.com"] or 693 ims[type eq "xmpp" and value co "@foo.com"] 695 filter=addresses[state eq "CA" and rooms[type eq "bedroom" and 696 number gt 2]] 698 Example Filters 700 3.2.2.3. Sorting 702 Sort is OPTIONAL. Sorting allows clients to specify the order in 703 which resources are returned by specifying a combination of sortBy 704 and sortOrder URL parameters. 706 sortBy: The sortBy parameter specifies the attribute whose value 707 SHALL be used to order the returned responses. If the sortBy 708 attribute corresponds to a singular attribute, resources are 709 sorted according to that attribute's value; if it's a multi-valued 710 attribute, resources are sorted by the value of the primary 711 attribute, if any, or else the first value in the list, if any. 712 If the attribute is complex the attribute name must be a path to a 713 sub-attribute in standard attribute notation (Section 3.8) ; e.g., 714 "sortBy=name.givenName". For all attribute types, if there is no 715 data for the specified "sortBy" value they are sorted via the 716 "sortOrder" parameter; i.e., they are ordered last if ascending 717 and first if descending. 719 sortOrder: The order in which the sortBy parameter is applied. 720 Allowed values are "ascending" and "descending". If a value for 721 sortBy is provided and no sortOrder is specified, the sortOrder 722 SHALL default to ascending. String type attributes are case 723 insensitive by default unless the attribute type is defined as a 724 case exact string. "sortOrder" MUST sort according to the 725 attribute type; i.e., for caee insensitive attributes, sort the 726 result using case insensitive, unicode alphabetic sort order, with 727 no specific locale implied and for case exact attribute types, 728 sort the result using case sensitive, Unicode alphabetic sort 729 order. 731 3.2.2.4. Pagination 733 Pagination parameters can be used together to "page through" large 734 numbers of resources so as not to overwhelm the client or service 735 provider. Pagination is not session based hence clients SHOULD never 736 assume repeatable results. For example, a request for a list of 10 737 resources beginning with a startIndex of 1 may return different 738 results when repeated as a resource in the original result could be 739 deleted or new ones could be added in-between requests. Pagination 740 parameters and general behavior are derived from the OpenSearch 741 Protocol [OpenSearch]. 743 The following table describes the URL pagination parameters. 745 +------------+-------------------+----------------------------------+ 746 | Parameter | Description | Default | 747 +------------+-------------------+----------------------------------+ 748 | startIndex | The 1-based index | 1 | 749 | | of the first | | 750 | | search result. | | 751 | count | Non-negative | None. When specified the service | 752 | | Integer. | provider MUST not return more | 753 | | Specifies the | results than specified though | 754 | | desired maximum | MAY return fewer results. If | 755 | | number of search | unspecified, the maximum number | 756 | | results per page; | of results is set by the service | 757 | | e.g., 10. | provider. | 758 +------------+-------------------+----------------------------------+ 760 Table 5: Pagination Request parameters 762 The following table describes the query response pagination 763 attributes specified by the service provider. 765 +--------------+----------------------------------------------------+ 766 | Element | Description | 767 +--------------+----------------------------------------------------+ 768 | itemsPerPage | Non-negative Integer. Specifies the number of | 769 | | search results returned in a query response page; | 770 | | e.g., 10. | 771 | totalResults | Non-negative Integer. Specifies the total number | 772 | | of results matching the client query; e.g., 1000. | 773 | startIndex | The 1-based index of the first result in the | 774 | | current set of search results; e.g., 1. | 775 +--------------+----------------------------------------------------+ 777 Table 6: Pagination Response Elements 779 For example, to retrieve the first 10 Users set the startIndex to 1 780 and the count to 10: 782 GET /Users?startIndex=1&count=10 783 Host: example.com 784 Accept: application/json 785 Authorization: Bearer h480djs93hd8 786 The response to the query above returns metadata regarding paging 787 similar to the following example (actual resources removed for 788 brevity): 790 { 791 "totalResults":100, 792 "itemsPerPage":10, 793 "startIndex":1, 794 "schemas":["urn:scim:schemas:core:2.0"], 795 "Resources":[{ 796 ... 797 }] 798 } 800 Given the example above, to continue paging set the startIndex to 11 801 and re-fetch; i.e., /Users?startIndex=11&count=10 803 3.2.3. Querying Resources Using HTTP POST 805 Clients MAY execute queries without passing parameters on the URL by 806 using the HTTP POST verb combined with the '/.search' path extension. 807 The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL 808 be used to indicate the HTTP POST verb is intended to be a query 809 operation. 811 To create a new search result set, a SCIM client sends an HTTP POST 812 request to the desired SCIM resource endpoint (ending in '/.search'). 813 The body of the POST request MAY include any of the parameters as 814 defined in Section 3.2.2. 816 Search requests MUST be identified using the following URI: 817 'urn:scim:schemas:core:2.0:SearchRequest'. The following attributes 818 are defined for search requests: 820 attributes A multi-valued list of strings indicating the names of 821 resource attributes to return in the response overriding the set 822 of attributes that would be returned by default. Attribute names 823 MUST be in standard attribute notation (Section 3.8) form. See 824 additional retrieval query parameters (Section 3.7). OPTIONAL. 826 excludedAttributes A multi-valued list of strings indicating the 827 names of resource attributes to be removed from the default set of 828 attributes to return. This parameter SHALL have no effect on 829 attributes whose schema "returned" setting is "always" see Server 830 Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in 831 standard attribute notation (Section 3.8) form. See additional 832 retrieval query parameters (Section 3.7). OPTIONAL. 834 filter The filter string used to request a subset of resources. The 835 filter string MUST be a valid filter (Section 3.2.2.2) expression. 836 OPTIONAL. 838 sortBy A string indicating the attribute whose value SHALL be used 839 to order the returned responses. The sortBy attribute MUST be in 840 standard attribute notation (Section 3.8) form. See sorting 841 (Section 3.2.2.3). OPTIONAL. 843 sortOrder A string indicating the order in which the sortBy 844 parameter is applied. Allowed values are "ascending" and 845 "descending". See sorting (Section 3.2.2.3). OPTIONAL. 847 startIndex An integer indicating the 1-based index of the first 848 search result. See pagination (Section 3.2.2.4). OPTIONAL. 850 count An integer indicating the desired maximum number of search 851 results per page. See pagination (Section 3.2.2.4). OPTIONAL. 853 After receiving a HTTP POST request, a response is returned as 854 specified in Section 3.2.2. 856 The following example shows an HTTP POST Search request with search 857 parameters attributes, filter, and count included: 859 POST /.search 860 Host: example.com 861 Accept: application/json 862 Content-Type: application/json 863 Authorization: Bearer h480djs93hd8 864 Content-Length: ... 866 { 867 "schemas": ["urn:scim:schemas:core:2.0:SearchRequest"], 868 "attributes": ["displayName", "userName"], 869 "filter": "displayName sw \"smith\"", 870 "startIndex": 1, 871 "count": 10 872 } 874 Figure 2: Example POST Search Request 876 A search response is shown with the first page of results. For 877 brevity reasons, only two matches are shown: one User and one Group. 879 HTTP/1.1 200 OK 880 Content-Type: application/json 881 Location: https://example.com/.search 882 { 883 "schemas": ["urn:scim:schemas:core:2.0:ListResponse"], 884 "totalResults":100, 885 "itemsPerPage":10, 886 "startIndex":1, 887 "Resources":[ 888 { 889 "meta":{ 890 "location": 891 "https://example.com/Users/2819c223-7f76-413861904646", 892 "resourceType":"User", 893 "lastModified": ... 894 }, 895 "userName":"jsmith", 896 "displayName":"Smith, James" 897 }, 898 { 899 "meta":{ 900 "location": 901 "https://example.com/Groups/c8596b90-7539-4f20968d1908", 902 "resourceType":"Group", 903 "lastModified": ... 904 }, 905 "displayName":"Smith Family" 906 }, 907 ... 908 ] 909 } 911 Figure 3: Example POST Search Response 913 3.3. Modifying Resources 915 Resources can be modified in whole or in part via PUT or PATCH, 916 respectively. Implementers MUST support PUT as specified in 917 Section 9.6 [RFC2616] . Resources such as Groups may be very large 918 hence implementers SHOULD support PATCH [RFC5789] to enable partial 919 resource modifications. 921 3.3.1. Modifying with PUT 923 PUT performs a full update. Clients MAY retrieve the entire resource 924 in advance, add the desired modifications and use HTTP PUT which will 925 overwrite all previously stored data. Since the PUT request performs 926 a full update, clients MAY send attributes of the retrieved resource 927 and the service provider MUST process according to attribute 928 mutability as follows: 930 readWrite, writeOnly Any values provided SHALL replace the existing 931 attribute values. Omitting the attribute or specific values means 932 the attribute or specific value SHALL be removed; 934 immutable If values are provided for elements already set in the 935 attribute they MUST match existing data or an error is returned. 936 If the service provider has no existing values, a new value(s) MAY 937 be specified; and, 939 readOnly Any values provided (e.g. meta.resourceType) SHALL be 940 ignored. 942 If an attribute is "required", the client MUST specify the attribute 943 in the PUT request. 945 If a value provided for an immutable attribute with an existing value 946 is NOT matched, the server SHALL respond with an HTTP response code 947 of 400 and an appropriate human readable message indicating an 948 attempt to change an immutable attribute. 950 Unless otherwise specified a successful PUT operation returns a 200 951 OK response code and the entire resource within the response body, 952 enabling the client to correlate the client's and Provider's views of 953 the updated resource. Example: 955 PUT /Users/2819c223-7f76-453a-919d-413861904646 956 Host: example.com 957 Accept: application/json 958 Content-Type: application/json 959 Authorization: Bearer h480djs93hd8 960 If-Match: W/"a330bc54f0671c9" 962 { 963 "schemas":["urn:scim:schemas:core:2.0:User"], 964 "id":"2819c223-7f76-453a-919d-413861904646", 965 "userName":"bjensen", 966 "externalId":"bjensen", 967 "name":{ 968 "formatted":"Ms. Barbara J Jensen III", 969 "familyName":"Jensen", 970 "givenName":"Barbara", 971 "middleName":"Jane" 972 }, 973 "emails":[ 974 { 975 "value":"bjensen@example.com" 976 }, 977 { 978 "value":"babs@jensen.org" 979 } 980 ] 981 } 982 The service responds with the entire, updated User: 984 HTTP/1.1 200 OK 985 Content-Type: application/json 986 ETag: W/"b431af54f0671a2" 987 Location:"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646" 988 { 989 "schemas":["urn:scim:schemas:core:2.0:User"], 990 "id":"2819c223-7f76-453a-919d-413861904646", 991 "userName":"bjensen", 992 "externalId":"bjensen", 993 "name":{ 994 "formatted":"Ms. Barbara J Jensen III", 995 "familyName":"Jensen", 996 "givenName":"Barbara", 997 "middleName":"Jane" 998 }, 999 "emails":[ 1000 { 1001 "value":"bjensen@example.com" 1002 }, 1003 { 1004 "value":"babs@jensen.org" 1005 } 1006 ], 1007 "meta": { 1008 "resourceType":"User", 1009 "created":"2011-08-08T04:56:22Z", 1010 "lastModified":"2011-08-08T08:00:12Z", 1011 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 1012 "version":"W\/\"b431af54f0671a2\"" 1013 } 1014 } 1016 3.3.2. Modifying with PATCH 1018 HTTP PATCH is an OPTIONAL server function that enables clients to 1019 update one or more attributes of a SCIM resource using a sequence of 1020 operations to "add", "remove", or "replace" values. The general form 1021 of the SCIM patch request is based on JavaScript Object Notation 1022 (JSON) Patch [RFC6902]. One difference between SCIM patch and JSON 1023 patch is that SCIM servers do not support array indexing and may not 1024 support all [RFC6902] operation types. 1026 The body of an HTTP PATCH request MUST contain one or more patch 1027 operation objects. A patch operation object MUST have exactly one 1028 "op" member, whose value indicates the operation to perform and MAY 1029 be one of "add", "remove", or "replace" . The semantics of each 1030 operation are defined below. 1032 Operation objects MUST have exactly one "path" member which is a 1033 "String" containing an attribute path as specified by the following 1034 ABNF syntax rule: 1036 PATH = attrPath / valuePath [subAttr] 1038 Figure 4: SCIM Patch PATH Rule 1040 The rules, "attrPath", "valuePath", and "subAttr" are defined in 1041 Section 3.2.2.2. The "valuePath" rule allows specific values of a 1042 complex, multi-valued attribute to be selected. 1044 Valid examples of "path" values are as follows: 1046 "path":"members" 1048 "path":"name.familyName" 1050 "path":"addresses[type eq \"work\"]" 1052 "path":"members[value eq 1053 \"2819c223-7f76-453a-919d-413861904646\"]" 1055 "path":"members[value eq 1056 \"2819c223-7f76-453a-919d-413861904646\"].displayName" 1058 Each operation against an attribute MUST be compatible with the 1059 attribute's mutability and schema as defined in the Attribute Types 1060 Section of [I-D.ietf-scim-core-schema]. For example, a client MAY 1061 NOT modify an attribute that has mutability "readOnly"or "immutable". 1062 However, a client MAY "add" a value to an"immutable" attribute if the 1063 attribute had no previous value. An operation that is not 1064 compatibile with an attribute's mutability or schema SHALL return an 1065 error as indicated below. 1067 Each patch operation represents a single action to be applied to the 1068 same SCIM resource specified by the request URI. Operations are 1069 applied sequentially in the order they appear in the array. Each 1070 operation in the sequence is applied to the target resource; the 1071 resulting resource becomes the target of the next operation. 1072 Evaluation continues until all operations are successfully applied or 1073 until an error condition is encountered. 1075 A patch request, regardless of the number of operations, SHALL be 1076 treated as atomic. If a single operation encounters an error 1077 condition, the original SCIM resource MUST be restored, and a failure 1078 status SHALL be returned. 1080 If a request fails. the server SHALL return an HTTP response status 1081 code of 400 and a JSON detail error response containing an "error" 1082 object that SHOULD be one of the following string values: 1084 malformed_operation 1085 The JSON operation elements could not successfully be parsed. 1086 This may be due to an invalid or missing operation attribute, or 1087 it could be due to a missing attribute required by a specific 1088 operation. 1090 mutability 1091 The operation requested is not compatible with the mutability of 1092 the selected attribute. 1094 invalid_path 1095 The path attribute was invalid or malformed. 1097 no_target 1098 The "path" specified did not return a target against which the 1099 operation could be performed. 1101 invalid_value 1102 The operation "value" was missing or was not compatable with the 1103 targeted attribute's type 1105 The following is a non-normative example of an error response to a 1106 patch request. 1108 HTTP/1.1 400 Bad Request 1109 Content-Type: application/json;charset=UTF-8 1110 Cache-Control: no-store 1111 Pragma: no-cache 1113 { 1114 "schemas": ["urn:scim:schemas:core:2.0:Error"], 1115 "Errors":[ 1116 { 1117 "error":"mutability", 1118 "error_description":"Attribute 'id' is readOnly." 1119 } 1120 ] 1121 } 1123 On successful completion, the server MUST return either a 200 OK 1124 response code and the entire resource (subject to the "attributes" 1125 query parameter - see Additional Retrieval Query Parameters 1126 (Section 3.7)) within the response body, or a 204 No Content response 1127 code and the appropriate response headers for a successful patch 1128 request. The server MUST return a 200 OK if the "attributes" 1129 parameter is specified on the request. 1131 3.3.2.1. Add Operation 1133 The "add" operation performs one of the following functions, 1134 depending upon what the target location indicated by "path" 1135 references: 1137 o If the target location does not exist, the attribute and value is 1138 added. 1140 o If the target location specifies a multi-valued attribute, a new 1141 value is added to the attribute. 1143 o if the target location specifies a single-valued attribute, the 1144 existing value is replaced. 1146 o If the target location specifies an attribute that does not exist 1147 (has no value), the attribute is added with the new value. 1149 o If the target location exists, the value is replaced. 1151 o If the target location already contains the value specified, no 1152 changes SHOULD be made to the resource and a success response 1153 SHOULD be returned. Unless other operations change the resource, 1154 this operation SHALL NOT change the modify timestamp of the 1155 resource. 1157 The operation MUST contain a "value" member whose content specifies 1158 the value to be added. The value MAY be a quoted value OR it may be 1159 a JSON object containing the sub-attributes of the complex attribute 1160 specified in the operation's "path". 1162 The following example shows how to add a member to a group. Some 1163 text removed for readability ("..."): 1165 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1166 Host: example.com 1167 Accept: application/json 1168 Content-Type: application/json 1169 Authorization: Bearer h480djs93hd8 1170 If-Match: W/"a330bc54f0671c9" 1172 { 1173 "op":"add", 1174 "path":"members", 1175 "value":[ 1176 { 1177 "display": "Babs Jensen", 1178 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1179 "value": "2819c223-7f76-453a-919d-413861904646" 1180 } 1181 ] 1182 } 1184 The "display" Sub-Attribute in this request is optional since the 1185 value attribute uniquely identifies the user to be added. If the 1186 user was already a member of this group, no changes should be made to 1187 the resource and a success response should be returned. The server 1188 responds with either the entire updated Group or no response body: 1190 HTTP/1.1 204 No Content 1191 Authorization: Bearer h480djs93hd8 1192 ETag: W/"b431af54f0671a2" 1193 Location: "https://example.com/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" 1195 3.3.2.2. Remove Operation 1197 The "remove" operation removes the value at the target location 1198 specified by the "path". The operation performs the following 1199 functions depending on the target location specified by "path": 1201 o If the target location is a single-value attribute, the attribute 1202 and its associated value is removed. 1204 o If the target location is a multi-valued attribute and no filter 1205 is specified, the attribute and all values are removed. 1207 o If the target location is a multi-valued attribute and a complex 1208 filter is specified comparing a "value", the values matched by the 1209 filter are removed. 1211 o If the target location is a complex-multi-valued attribute and a 1212 complex filter is specified based on the attribute's sub- 1213 attributes, the matching records are removed. 1215 The following example shows how to remove a member from a group. As 1216 with the previous example, the "display" Sub-Attribute is optional. 1217 If the user was not a member of this group, no changes should be made 1218 to the resource and a success response should be returned. 1220 Note that server responses have been omitted for the rest of the 1221 PATCH examples. 1223 Remove a single member from a group. Some text removed for 1224 readability ("..."): 1226 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1227 Host: example.com 1228 Accept: application/json 1229 Content-Type: application/json 1230 Authorization: Bearer h480djs93hd8 1231 If-Match: W/"a330bc54f0671c9" 1233 { 1234 "op":"remove", 1235 "path":"members[value eq \"2819c223-7f76-...413861904646\"]" 1236 } 1238 Remove all members of a group: 1240 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1241 Host: example.com 1242 Accept: application/json 1243 Content-Type: application/json 1244 Authorization: Bearer h480djs93hd8 1245 If-Match: W/"a330bc54f0671c9" 1247 { "op":"remove","path":"members"} 1249 Removal of a value from a complex-multi-valued attribute (request 1250 headers removed for brevity): 1252 { 1253 "op":"remove", 1254 "path":"emails[type eq \"work\" and value ew \"example.com\"]" 1255 } 1256 Example request to remove and add a member. Some text removed for 1257 readability ("..."): 1259 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1260 Host: example.com 1261 Accept: application/json 1262 Content-Type: application/json 1263 Authorization: Bearer h480djs93hd8 1264 If-Match: W/"a330bc54f0671c9" 1266 [ 1267 { 1268 "op":"remove", 1269 "path":"members[value eq\"2819c223...919d-413861904646\"]" 1270 }, 1271 { 1272 "op":"add", 1273 "path":"members", 1274 "value": [ 1275 { 1276 "display": "James Smith", 1277 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1278 "value": "08e1d05d...473d93df9210" 1279 } 1280 ] 1281 } 1282 ] 1283 The following example shows how to replace all the members of a group 1284 with a different members list. Some text removed for readabilty 1285 ("..."): 1287 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1288 Host: example.com 1289 Accept: application/json 1290 Content-Type: application/json 1291 Authorization: Bearer h480djs93hd8 1292 If-Match: W/"a330bc54f0671c9" 1294 [ 1295 { "op":"remove","path":"members"}, 1296 { 1297 "op":"add", 1298 "path":"members", 1299 "value":[ 1300 { 1301 "display": "Babs Jensen", 1302 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1303 "value": "2819c223-7f76-453a-919d-413861904646" 1304 }, 1305 { 1306 "display": "James Smith", 1307 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1308 "value": "08e1d05d-121c-4561-8b96-473d93df9210" 1309 }] 1310 } 1311 ] 1313 3.3.2.3. Replace Operation 1315 The "replace" operation replaces the value at the target location 1316 specified by the "path". The operation performs the following 1317 functions depending on the target location specified by "path": 1319 o If the target location is a single-value attribute, the attributes 1320 value is replaced. 1322 o If the target location is a multi-valued attribute and no filter 1323 is specified, the attribute and all values are replaced. 1325 o If the target location is a multi-valued attribute and a complex 1326 filter is specified comparing a "value", the values matched by the 1327 filter are replaced. 1329 o If the target location is a complex-multi-valued attribute and a 1330 complex filter is specified based on the attribute's sub- 1331 attributes, the matching records are replaced. 1333 o If the target location is a complex-multi-valued attribute with a 1334 complex filter and a specific sub-attribute (e.g. "addresses[type 1335 eq "work"].streetAddress"), the matching sub-attribute of the 1336 matching record is replaced. 1338 The following example shows how to replace all the members of a group 1339 with a different members list in a single replace operation. Some 1340 text removed for readability ("..."): 1342 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1343 Host: example.com 1344 Accept: application/json 1345 Content-Type: application/json 1346 Authorization: Bearer h480djs93hd8 1347 If-Match: W/"a330bc54f0671c9" 1349 { 1350 "op":"replace", 1351 "path":"members", 1352 "value":[ 1353 { 1354 "display": "Babs Jensen", 1355 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1356 "value": "2819c223...413861904646" 1357 }, 1358 { 1359 "display": "James Smith", 1360 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1361 "value": "08e1d05d...473d93df9210" 1362 } 1363 ] 1364 } 1365 The following example shows how to change a User's entire "work" 1366 address. 1368 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1369 Host: example.com 1370 Accept: application/json 1371 Content-Type: application/json 1372 Authorization: Bearer h480djs93hd8 1373 If-Match: W/"a330bc54f0671c9" 1375 { 1376 "op":"replace", 1377 "path":"addresses[type eq \"work\"]", 1378 "value": 1379 { 1380 "type": "work", 1381 "streetAddress": "911 Universal City Plaza", 1382 "locality": "Hollywood", 1383 "region": "CA", 1384 "postalCode": "91608", 1385 "country": "US", 1386 "formatted": "911 Universal City Plaza\nHollywood, CA 91608 US", 1387 "primary": true 1388 } 1389 } 1391 The following example shows how to change a User's address. Since 1392 address does not have a value Sub-Attribute, the existing address 1393 must be removed and the modified address added. 1395 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1396 Host: example.com 1397 Accept: application/json 1398 Content-Type: application/json 1399 Authorization: Bearer h480djs93hd8 1400 If-Match: W/"a330bc54f0671c9" 1402 { 1403 "op":"replace", 1404 "path":"addresses[type eq \"work\"].streetAddress", 1405 "value":"911 Universal City Plaza" 1406 } 1408 3.4. Deleting Resources 1410 Clients request resource removal via DELETE. Service providers MAY 1411 choose not to permanently delete the resource, but MUST return a 404 1412 error code for all operations associated with the previously deleted 1413 Id. Service providers MUST also omit the resource from future query 1414 results. In addition the service provider MUST not consider the 1415 deleted resource in conflict calculation. For example if a User 1416 resource is deleted, a CREATE request for a User resource with the 1417 same userName as the previously deleted resource should not fail with 1418 a 409 error due to userName conflict. 1420 DELETE /Users/2819c223-7f76-453a-919d-413861904646 1421 Host: example.com 1422 Authorization: Bearer h480djs93hd8 1423 If-Match: W/"c310cd84f0281b7" 1425 In response to a successful delete, the server SHALL respond with 1426 successful HTTP status 204 (No Content). A non-normative example 1427 response: 1429 HTTP/1.1 204 No Content 1431 Example: client attempt to retrieve the previously deleted User 1433 GET /Users/2819c223-7f76-453a-919d-413861904646 1434 Host: example.com 1435 Authorization: Bearer h480djs93hd8 1437 Server Response: 1439 HTTP/1.1 404 NOT FOUND 1441 { 1442 "schemas": ["urn:scim:schemas:core:2.0:Error"], 1443 "Errors":[ 1444 { 1445 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 1446 "code":"404" 1447 } 1448 ] 1449 } 1451 3.5. Bulk 1453 The SCIM bulk operation is an optional server feature that enables 1454 clients to send a potentially large collection of resource operations 1455 in a single request. The body of a a bulk operation contains a set 1456 of HTTP resource operations using one of the API supported HTTP 1457 methods; i.e., POST, PUT, PATCH or DELETE. 1459 Bulk requests are identified using the following URI: 1460 'urn:scim:schemas:core:2.0:BulkRequest'. Bulk responses are 1461 identified using the following URI: 1462 'urn:scim:schemas:core:2.0:BulkResponse'. Bulk requests and bulk 1463 responses share many attributes. Unless otherwise specified, each 1464 attribute below is present in both bulk requests and bulk responses. 1466 The following Singular Attribute is defined in addition to the common 1467 attributes defined in SCIM core schema. 1469 failOnErrors An Integer specifying the number of errors that the 1470 service provider will accept before the operation is terminated 1471 and an error response is returned. OPTIONAL in a request. Not 1472 valid in a response. 1474 The following Complex Multi-valued Attribute is defined in addition 1475 to the common attributes defined in core schema. 1477 Operations Defines operations within a bulk job. Each operation 1478 corresponds to a single HTTP request against a resource endpoint. 1479 REQUIRED. 1481 method The HTTP method of the current operation. Possible values 1482 are POST, PUT, PATCH or DELETE. REQUIRED. 1484 bulkId The transient identifier of a newly created resource, 1485 unique within a bulk request and created by the client. The 1486 bulkId serves as a surrogate resource id enabling clients to 1487 uniquely identify newly created resources in the Response and 1488 cross reference new resources in and across operations within a 1489 bulk request. REQUIRED when method is POST. 1491 version The current resource version. Version is REQUIRED if the 1492 service provider supports ETags and the method is PUT, DELETE, 1493 or PATCH. 1495 path The resource's relative path. If the method is POST the 1496 value must specify a resource type endpoint; e.g., /Users or / 1497 Groups whereas all other method values must specify the path to 1498 a specific resource; e.g., /Users/2819c223-7f76-453a- 1499 919d-413861904646. REQUIRED in a request. 1501 data The resource data as it would appear for a single POST, PUT 1502 or PATCH resource operation. REQUIRED in a request when method 1503 is POST, PUT and PATCH. 1505 location The resource endpoint URL. REQUIRED in a response, 1506 except in the event of a POST failure. 1508 status A complex type that contains information about the success 1509 or failure of one operation within the bulk job. REQUIRED in a 1510 response. 1512 code The HTTP response code that would have been returned if a 1513 a single HTTP request would have been used. REQUIRED. 1515 description A human readable error message. REQUIRED when an 1516 error occurred. 1518 If a bulk job is processed successfully the HTTP response code 200 OK 1519 MUST be returned, otherwise an appropriate HTTP error code MUST be 1520 returned. 1522 The service provider MUST continue performing as many changes as 1523 possible and disregard partial failures. The client MAY override 1524 this behavior by specifying a value for failOnErrors attribute. The 1525 failOnErrors attribute defines the number of errors that the service 1526 provider should accept before failing the remaining operations 1527 returning the response. 1529 To be able to reference a newly created resource the attribute bulkId 1530 MUST be specified when creating new resources. The bulkId is defined 1531 by the client as a surrogate identifier in a POST operation. The 1532 service provider MUST return the same bulkId together with the newly 1533 created resource. The bulkId can then be used by the client to map 1534 the service provider id with the bulkId of the created resource. 1536 There can be more then one operation per resource in each bulk job. 1537 The Service client MUST take notice of the unordered structure of 1538 JSON and the service provider can process operations in any order. 1539 For example, if the Service client sends two PUT operations in one 1540 request, the outcome is non-deterministic. 1542 The service provider response MUST include the result of all 1543 processed operations. A location attribute that includes the 1544 resource's end point MUST be returned for all operations excluding 1545 failed POSTs. The status attribute includes information about the 1546 success or failure of one operation within the bulk job. The 1547 attribute status MUST include the code attribute that holds the HTTP 1548 response code that would have been returned if a single HTTP request 1549 would have been used. If an error occurred the status MUST also 1550 include the description attribute containing a human readable 1551 explanation of the error. 1553 "status": { 1554 "code": "201" 1555 } 1557 The following is an example of a status in a failed operation. 1559 "status": { 1560 "code": "400", 1561 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1562 } 1564 The following example shows how to add, update, and remove a user. 1565 The failOnErrors attribute is set to '1' indicating the service 1566 provider should return on the first error. The POST operation's 1567 bulkId value is set to 'qwerty' enabling the client to match the new 1568 User with the returned resource id '92b725cd-9465-4e7d- 1569 8c16-01f8e146b87a'. 1571 POST /v2/Bulk 1572 Host: example.com 1573 Accept: application/json 1574 Content-Type: application/json 1575 Authorization: Bearer h480djs93hd8 1576 Content-Length: ... 1578 { 1579 "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], 1580 "failOnErrors":1, 1581 "Operations":[ 1582 { 1583 "method":"POST", 1584 "path":"/Users", 1585 "bulkId":"qwerty", 1586 "data":{ 1587 "schemas": ["urn:scim:schemas:core:2.0:User"], 1588 "userName":"Alice" 1589 } 1590 }, 1591 { 1592 "method":"PUT", 1593 "path":"/Users/b7c14771-226c-4d05-8860-134711653041", 1594 "version":"W\/\"3694e05e9dff591\"", 1595 "data":{ 1596 "schemas": ["urn:scim:schemas:core:2.0:User"], 1597 "id":"b7c14771-226c-4d05-8860-134711653041", 1598 "userName":"Bob" 1600 } 1601 }, 1602 { 1603 "method": "PATCH", 1604 "path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1605 "version": "W/\"edac3253e2c0ef2\"", 1606 "data": {[ 1607 { 1608 "op": "remove", 1609 "path": "nickName" 1610 }, 1611 { 1612 "op": "add", 1613 "path": "userName", 1614 "value": "Dave" 1615 } 1616 ]} 1617 }, 1618 { 1619 "method":"DELETE", 1620 "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1621 "version":"W\/\"0ee8add0a938e1a\"" 1622 } 1623 ] 1624 } 1626 The service provider returns the following response. 1628 HTTP/1.1 200 OK 1629 Content-Type: application/json 1631 { 1632 "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], 1633 "Operations": [ 1634 { 1635 "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1636 "method": "POST", 1637 "bulkId": "qwerty", 1638 "version": "W\/\"oY4m4wn58tkVjJxK\"", 1639 "status": { 1640 "code": "201" 1641 } 1642 }, 1643 { 1644 "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 1645 "method": "PUT", 1646 "version": "W\/\"huJj29dMNgu3WXPD\"", 1647 "status": { 1648 "code": "200" 1649 } 1650 }, 1651 { 1652 "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1653 "method": "PATCH", 1654 "version": "W\/\"huJj29dMNgu3WXPD\"", 1655 "status": { 1656 "code": "200" 1657 } 1658 }, 1659 { 1660 "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1661 "method": "DELETE", 1662 "status": { 1663 "code": "204" 1664 } 1665 } 1666 ] 1667 } 1669 The following response is returned if an error occurred when 1670 attempting to create the User 'Alice'. The service provider stops 1671 processing the bulk operation and immediately returns a response to 1672 the client. The response contains the error and any successful 1673 results prior to the error. 1675 HTTP/1.1 200 OK 1676 Content-Type: application/json 1678 { 1679 "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], 1680 "Operations": [ 1681 { 1682 "method": "POST", 1683 "bulkId": "qwerty", 1684 "status": { 1685 "code": "400", 1686 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1687 } 1688 } 1689 ] 1690 } 1692 If the failOnErrors attribute is not specified or the service 1693 provider has not reached the error limit defined by the client the 1694 service provider will continue to process all operations. The 1695 following is an example in which all operations failed. 1697 HTTP/1.1 200 OK 1698 Content-Type: application/json 1700 { 1701 "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], 1702 "Operations": [ 1703 { 1704 "method": "POST", 1705 "bulkId": "qwerty", 1706 "status": { 1707 "code": "400", 1708 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1709 } 1710 }, 1711 { 1712 "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 1713 "method": "PUT", 1714 "status": { 1715 "code": "412", 1716 "description": "Failed to update as user changed on the server since you last retrieved it." 1717 } 1718 }, 1719 { 1720 "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1721 "method": "PATCH", 1722 "status": { 1723 "code": "412", 1724 "description": "Failed to update as user changed on the server since you last retrieved it." 1725 } 1726 }, 1727 { 1728 "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1729 "method": "DELETE", 1730 "status": { 1731 "code": "404", 1732 "description": "Specified resource; e.g., User, does not exist." 1733 } 1734 } 1735 ] 1736 } 1738 The client can, within one bulk operation, create a new User, a new 1739 Group and add the newly created User to the newly created Group. In 1740 order to add the new User to the Group the client must use the 1741 surrogate id attribute, bulkId, to reference the User. The bulkId 1742 attribute value must be pre-pended with the literal "bulkId:"; e.g., 1743 if the bulkId is 'qwerty' the value is "bulkId:qwerty". The service 1744 provider MUST replace the string "bulkId:qwerty" with the permanent 1745 resource id once created. 1747 The following example creates a User with the userName 'Alice' and a 1748 Group with the displayName 'Tour Guides' with Alice as a member. 1750 POST /v2/Bulk 1751 Host: example.com 1752 Accept: application/json 1753 Content-Type: application/json 1754 Authorization: Bearer h480djs93hd8 1755 Content-Length: ... 1757 { 1758 "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], 1759 "Operations": [ 1760 { 1761 "method": "POST", 1762 "path": "/Users", 1763 "bulkId": "qwerty", 1764 "data": { 1765 "schemas": ["urn:scim:schemas:core:2.0:User"], 1766 "userName": "Alice" 1767 } 1768 }, 1769 { 1770 "method": "POST", 1771 "path": "/Groups", 1772 "bulkId": "ytrewq", 1773 "data": { 1774 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1775 "displayName": "Tour Guides", 1776 "members": [ 1777 { 1778 "type": "user", 1779 "value": "bulkId:qwerty" 1780 } 1781 ] 1782 } 1783 } 1784 ] 1785 } 1787 The service provider returns the following response. 1789 HTTP/1.1 200 OK 1790 Content-Type: application/json 1792 { 1793 "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], 1794 "Operations": [ 1795 { 1796 "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1797 "method": "POST", 1798 "bulkId": "qwerty", 1799 "version": "W\/\"4weymrEsh5O6cAEK\"", 1800 "status": { 1801 "code": "201" 1802 } 1803 }, 1804 { 1805 "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1806 "method": "POST", 1807 "bulkId": "ytrewq", 1808 "version": "W\/\"lha5bbazU3fNvfe5\"", 1809 "status": { 1810 "code": "201" 1811 } 1812 } 1813 ] 1814 } 1816 A subsequent request for the 'Tour Guides' Group ('e9e30dba- 1817 f08f-4109-8486-d5c6a331660a') returns the following: 1819 GET /v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1820 Host: example.com 1821 Accept: application/json 1822 Authorization: Bearer h480djs93hd8 1824 HTTP/1.1 200 OK 1825 Content-Type: application/json 1826 Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1827 ETag: W/"lha5bbazU3fNvfe5" 1829 { 1830 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1831 "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", 1832 "displayName": "Tour Guides", 1833 "meta": { 1834 "resourceType": "Group", 1835 "created": "2011-08-01T18:29:49.793Z", 1836 "lastModified": "2011-08-01T20:31:02.315Z", 1837 "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1838 "version": "W\/\"lha5bbazU3fNvfe5\"" 1839 }, 1840 "members": [ 1841 { 1842 "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", 1843 "$ref": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1844 "type": "User" 1845 } 1846 ] 1847 } 1849 Extensions that include references to other resources MUST be handled 1850 in the same way by the service provider. The following example uses 1851 the bulkId attribute within the enterprise extension managerId 1852 attribute. 1854 POST /v2/Bulk 1855 Host: example.com 1856 Accept: application/json 1857 Content-Type: application/json 1858 Authorization: Bearer h480djs93hd8 1859 Content-Length: ... 1861 { 1862 "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], 1863 "Operations": [ 1864 { 1865 "method": "POST", 1866 "path": "/Users", 1867 "bulkId": "qwerty", 1868 "data": { 1869 "schemas": ["urn:scim:schemas:core:2.0:User"], 1870 "userName": "Alice" 1871 } 1872 }, 1873 { 1874 "method": "POST", 1875 "path": "/Users", 1876 "bulkId": "ytrewq", 1877 "data": { 1878 "schemas": [ 1879 "urn:scim:schemas:core:2.0:User", 1880 "urn:scim:schemas:extension:enterprise:2.0:User" 1881 ], 1882 "userName": "Bob", 1883 "urn:scim:schemas:extension:enterprise:2.0:User": { 1884 "employeeNumber": "11250", 1885 "manager": { 1886 "managerId": "batchId:qwerty", 1887 "displayName": "Alice" 1888 } 1889 } 1890 } 1891 } 1892 ] 1893 } 1895 The service provider MUST try to resolve circular cross references 1896 between resources in a single bulk job but MAY stop after a failed 1897 attempt and instead return the status code 409 Conflict. The 1898 following example exhibits the potential conflict. 1900 POST /v2/Bulk 1901 Host: example.com 1902 Accept: application/json 1903 Content-Type: application/json 1904 Authorization: Bearer h480djs93hd8 1905 Content-Length: ... 1907 { 1908 "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], 1909 "Operations": [ 1910 { 1911 "method": "POST", 1912 "path": "/Groups", 1913 "bulkId": "qwerty", 1914 "data": { 1915 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1916 "displayName": "Group A", 1917 "members": [ 1918 { 1919 "type": "group", 1920 "value": "bulkId:ytrewq" 1921 } 1922 ] 1923 } 1924 }, 1925 { 1926 "method": "POST", 1927 "path": "/Groups", 1928 "bulkId": "ytrewq", 1929 "data": { 1930 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1931 "displayName": "Group B", 1932 "members": [ 1933 { 1934 "type": "group", 1935 "value": "bulkId:qwerty" 1936 } 1937 ] 1938 } 1939 } 1940 ] 1941 } 1943 If the service provider resolved the above circular references the 1944 following is returned from a subsequent GET request. 1946 GET /v2/Groups?filter=displayName sw 'Group' 1947 Host: example.com 1948 Accept: application/json 1949 Authorization: Bearer h480djs93hd8 1951 HTTP/1.1 200 OK 1952 Content-Type: application/json 1954 { 1955 "schemas": ["urn:scim:schemas:core:2.0:ListResponse"], 1956 "totalResults": 2, 1957 "Resources": [ 1958 { 1959 "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1960 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1961 "displayName": "Group A", 1962 "meta": { 1963 "resourceType": "Group", 1964 "created": "2011-08-01T18:29:49.793Z", 1965 "lastModified": "2011-08-01T18:29:51.135Z", 1966 "location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1967 "version": "W\/\"mvwNGaxB5SDq074p\"" 1968 }, 1969 "members": [ 1970 { 1971 "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1972 "$ref": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1973 "type": "Group" 1974 } 1975 ] 1976 }, 1977 { 1978 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1979 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1980 "displayName": "Group B", 1981 "meta": { 1982 "resourceType": "Group", 1983 "created": "2011-08-01T18:29:50.873Z", 1984 "lastModified": "2011-08-01T18:29:50.873Z", 1985 "location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1986 "version": "W\/\"wGB85s2QJMjiNnuI\"" 1987 }, 1988 "members": [ 1989 { 1990 "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1991 "$ref": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1992 "type": "Group" 1993 } 1994 ] 1995 } 1996 ] 1997 } 1998 The service provider MUST define the maximum number of operations and 1999 maximum payload size a client may send in a single request. If 2000 either limits are exceeded the service provider MUST return the HTTP 2001 response code 413 Request Entity Too Large. The returned response 2002 MUST specify the limit exceeded in the body of the error response. 2004 The following example the client sent a request exceeding the service 2005 provider's max payload size of 1 megabyte. 2007 POST /v2/Bulk 2008 Host: example.com 2009 Accept: application/json 2010 Content-Type: application/json 2011 Authorization: Bearer h480djs93hd8 2012 Content-Length: 4294967296 2014 ... 2016 HTTP/1.1 413 Request Entity Too Large 2017 Content-Type: application/json 2018 Location: https://example.com/v2/Bulk/yfCrVJhFIJagAHj8 2020 { 2021 "schemas":["urn:scim:schemas:core:2.0:Error"], 2022 "Errors":[ 2023 { 2024 "description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).", 2025 "code":"413" 2026 } 2027 ] 2028 } 2030 3.6. Data Input/Output Formats 2032 Servers MUST accept requests and respond with JSON structured 2033 responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default 2034 encoding format. 2036 Clients using other encodings MUST specify the format in which the 2037 data is submitted via Section 14.17 HTTP header content-type[RFC2616] 2038 and MAY specify the desired response data format via an HTTP Accept 2039 Header; e.g.,"Accept: application/json" or via URI suffix; e.g., 2041 GET /Users/2819c223-7f76-453a-919d-413861904646.json 2042 Host: example.com 2043 Service providers MUST support the Accept Headers "Accept: 2044 application/json" for [RFC7159]. The format defaults to JSON if no 2045 format is specified. 2047 Singular attributes are encoded as string name-value-pairs in JSON; 2048 e.g., 2050 "attribute": "value" 2052 Multi-valued attributes in JSON are encoded as arrays; e.g., 2054 "attributes": [ "value1", "value2" ] 2056 Elements with nested elements are represented as objects in JSON; 2057 e.g, 2059 "attribute": { "subattribute1": "value1", "subattribute2": "value2" } 2061 3.7. Additional Operation Response Parameters 2063 For any SCIM operation where a resource representation is returned 2064 (e.g. HTTP GET), the attributes normally returned are defined as the 2065 minimum attribute set plus default attributes. The minimum set are 2066 those attributes whose schema have "returned" set to "always". The 2067 defaut attribute set are those attributes whose schema have 2068 "returned" set to "default". 2070 Clients MAY request a partial resource representation on any 2071 operation that returns a resource within the response by specifying 2072 either of the mutually exclusive URL query parameters "attributes" OR 2073 "excludedAtributes" as follows: 2075 attributes When specified, each resource returned MUST contain the 2076 minimal set of resource attributes and MUST contain no other 2077 attributes or sub-attributes other than those explicitly 2078 requested. The query parameter attributes value is a comma 2079 separated list of resource attribute names in standard 2080 attribute notation (Section 3.8) form (e.g. userName, name, 2081 emails). 2083 excludedAttributes When specified, each resource returned MUST 2084 contain the minimal set of resource attributes. 2085 Additionally, the default set of attributes minus those 2086 attributes listed in "excludedAttributes"are also returned. 2087 The query parameter attributes value is a comma separated 2088 list of resource attribute names in standard attribute 2089 notation (Section 3.8) form (e.g. userName, name, emails). 2091 . 2093 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName 2094 Host: example.com 2095 Accept: application/json 2096 Authorization: Bearer h480djs93hd8 2098 Giving the response 2100 HTTP/1.1 200 OK 2101 Content-Type: application/json 2102 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2103 ETag: W/"a330bc54f0671c9" 2105 { 2106 "schemas":["urn:scim:schemas:core:2.0:User"], 2107 "id":"2819c223-7f76-453a-919d-413861904646", 2108 "userName":"bjensen", 2109 "meta":{ 2110 "resourceType": "User", 2111 "created":"2011-08-01T18:29:49.793Z", 2112 "lastModified":"2011-08-01T18:29:49.793Z", 2113 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2114 "version":"W\/\"a330bc54f0671c9\"" 2115 } 2116 } 2118 3.8. Attribute Notation 2120 All operations share a common scheme for referencing simple and 2121 complex attributes. In general, attributes are identified by 2122 prefixing the attribute name with its schema URN separated by a ':' 2123 character; e.g., the core User resource attribute 'userName' is 2124 identified as 'urn:scim:schemas:core:2.0:User:userName'. Clients MAY 2125 omit core schema attribute URN prefixes though MUST fully qualify 2126 extended attributes with the associated resource URN; e.g., the 2127 attribute 'age' defined in 'urn:hr:schemas:user' is fully encoded as 2128 'urn:hr:schemas:user:age'. A Complex attributes' Sub-Attributes are 2129 referenced via nested, dot ('.') notation; i.e., {urn}:{Attribute 2130 name}.{Sub-Attribute name}. For example, the fully qualified path for 2131 a User's givenName is urn:scim:schemas:core:2.0:User:name.givenName 2132 All facets (URN, attribute and Sub-Attribute name) of the fully 2133 encoded Attribute name are case insensitive. 2135 3.9. "/Me" Authenticated Subject Alias 2137 A client MAY use a URL of the form "/Me" as an URL alias 2138 for the User or other resource associated with the currently 2139 authenticated subject for any SCIM operation. A service provider MAY 2140 respond in ONE of 3 ways: 2142 o A service provider that does NOT support this feature SHOULD 2143 respond with status 403 (FORBIDDEN). 2145 o A service provider MAY choose to redirect the client using HTTP 2146 status 308 to the resource associated with the authenticated 2147 subject. The client MAY then repeat the request at the indicated 2148 location. 2150 o A service provider MAY process the SCIM request directly. In any 2151 response, the HTTP "Location" header MUST be the permanent 2152 location of the aliased resource associated with the authenticated 2153 subject. 2155 3.10. HTTP Response Codes 2157 The SCIM Protocol uses the response status codes defined in HTTP 2158 Section 10 [RFC2616] to indicate operation success or failure. In 2159 addition to returning a HTTP response code implementers MUST return 2160 the errors in the body of the response in the client requested format 2161 containing the error response and, per the HTTP specification, human- 2162 readable explanations. Error responses are identified using the 2163 following URI: 'urn:scim:schemas:core:2.0:Error'. The following 2164 multi-valued attribute is defined in addition to those attributes 2165 defined in SCIM Core Schema: 2167 Errors The list of errors encountered by the service provider. The 2168 value attribute is a complex type with the following sub- 2169 attributes. 2171 description A human-readable explanation of the error. REQUIRED. 2173 code A string indicating the HTTP response code. REQUIRED. 2175 Implementers SHOULD handle the identified errors as described below. 2177 +--------------+---------------+------------------------------------+ 2178 | Code | Applicability | Suggested Explanation | 2179 +--------------+---------------+------------------------------------+ 2180 | 307 | GET, POST, | The client is directed to repeat | 2181 | TEMPORARY | PUT, PATCH, | the same HTTP request at the | 2182 | REDIRECT | DELETE | location identified. The client | 2183 | | | SHOULD NOT use the location | 2184 | | | provided in the response as a | 2185 | | | permanent reference to the | 2186 | | | resource and SHOULD continue to | 2187 | | | use the original request URI | 2188 | | | [I-D.ietf-httpbis-p2-semantics]. | 2189 | 308 | GET, POST, | The client is directed to repeat | 2190 | PERMANENT | PUT, PATCH, | the same HTTP request at the | 2191 | REDIRECT | DELETE | location identified. The client | 2192 | | | SHOULD use the location provided | 2193 | | | in the response as the permanent | 2194 | | | reference to the resource | 2195 | | | [I-D.reschke-http-status-308]. | 2196 | 400 BAD | GET, POST, | Request is unparseable, | 2197 | REQUEST | PUT, PATCH, | syntactically incorrect, or | 2198 | | DELETE | violates schema | 2199 | 401 | GET, POST, | Authorization failure | 2200 | UNAUTHORIZED | PUT, PATCH, | | 2201 | | DELETE | | 2202 | 403 | GET, POST, | Server does not support requested | 2203 | FORBIDDEN | PUT, PATCH, | operation | 2204 | | DELETE | | 2205 | 404 NOT | GET, PUT, | Specified resource; e.g., User, | 2206 | FOUND | PATCH, DELETE | does not exist | 2207 | 409 CONFLICT | POST, PUT, | The specified version number does | 2208 | | PATCH, DELETE | not match the resource's latest | 2209 | | | version number or a service | 2210 | | | provider refused to create a new, | 2211 | | | duplicate resource | 2212 | 412 | PUT, PATCH,D | Failed to update as resource {id} | 2213 | PRECONDITION | ELETE | changed on the server last | 2214 | FAILED | | retrieved | 2215 | 413 REQUEST | POST | {"maxOperations": | 2216 | ENTITY TOO | | 1000,"maxPayload": 1048576} | 2217 | LARGE | | | 2218 | 500 INTERNAL | GET, POST, | An internal error. Implementers | 2219 | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive | 2220 | | DELETE | debugging advice | 2221 | 501 NOT | GET, POST, | Service Provider does not support | 2222 | IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH | 2223 | | DELETE | | 2224 +--------------+---------------+------------------------------------+ 2226 Table 7: Defined error cases 2228 Error example in response to a non-existent GET request. 2230 HTTP/1.1 404 NOT FOUND 2232 { 2233 "schemas": ["urn:scim:schemas:core:2.0:Error"], 2234 "Errors":[ 2235 { 2236 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 2237 "code":"404" 2238 } 2239 ] 2240 } 2242 3.11. API Versioning 2244 The Base URL MAY be appended with a version identifier as a separate 2245 segment in the URL path. At this time the only valid identifier is 2246 'v1'. If specified, the version identifier MUST appear in the URL 2247 path immediately preceding the resource endpoint and conform to the 2248 following scheme: the character 'v' followed by the desired SCIM 2249 version number; e.g., a version 'v1' User request is specified as /v2 2250 /Users. When specified service providers MUST perform the operation 2251 using the desired version or reject the request. When omitted 2252 service providers SHOULD perform the operation using the most recent 2253 API supported by the service provider. 2255 3.12. Versioning Resources 2257 The API supports resource versioning via standard HTTP 2258 ETagsSection 14.19 [RFC2616]. Service providers MAY support weak 2259 ETags as the preferred mechanism for performing conditional 2260 retrievals and ensuring clients do not inadvertently overwrite each 2261 others changes, respectively. When supported SCIM ETags MUST be 2262 specified as an HTTP header and SHOULD be specified within the 2263 'version' attribute contained in the resource's 'meta' attribute. 2265 Example: 2267 POST /Users HTTP/1.1 2268 Host: example.com 2269 Content-Type: application/json 2270 Authorization: Bearer h480djs93hd8 2271 Content-Length: ... 2273 { 2274 "schemas":["urn:scim:schemas:core:2.0:User"], 2275 "userName":"bjensen", 2276 "externalId":"bjensen", 2277 "name":{ 2278 "formatted":"Ms. Barbara J Jensen III", 2279 "familyName":"Jensen", 2280 "givenName":"Barbara" 2281 } 2282 } 2284 The server responds with an ETag in the response header and meta 2285 structure. 2287 HTTP/1.1 201 Created 2288 Content-Type: application/json 2289 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2290 ETag: W/"e180ee84f0671b1" 2292 { 2293 "schemas":["urn:scim:schemas:core:2.0:User"], 2294 "id":"2819c223-7f76-453a-919d-413861904646", 2295 "meta":{ 2296 "resourceType":"User", 2297 "created":"2011-08-01T21:32:44.882Z", 2298 "lastModified":"2011-08-01T21:32:44.882Z", 2299 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2300 "version":"W\/\"e180ee84f0671b1\"" 2301 }, 2302 "name":{ 2303 "formatted":"Ms. Barbara J Jensen III", 2304 "familyName":"Jensen", 2305 "givenName":"Barbara" 2306 }, 2307 "userName":"bjensen" 2308 } 2310 With the returned ETag, clients MAY choose to retrieve the resource 2311 only if the resource has been modified. 2313 Conditional retrieval example using If-None-Match Section 14.26 2314 [RFC2616] header: 2316 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName 2317 Host: example.com 2318 Accept: application/json 2319 Authorization: Bearer h480djs93hd8 2320 If-None-Match: W/"e180ee84f0671b1" 2322 If the resource has not changed the service provider simply returns 2323 an empty body with a 304 "Not Modified" response code. 2325 If the service providers supports versioning of resources the client 2326 MAY supply an If-Match Section 14.24 [RFC2616] header for PUT and 2327 PATCH operations to ensure that the requested operation succeeds only 2328 if the supplied ETag matches the latest service provider resource; 2329 e.g., If-Match: W/"e180ee84f0671b1" 2331 4. Multi-Tenancy 2333 A single service provider may expose the SCIM protocol to multiple 2334 clients. Depending on the nature of the service, the clients may 2335 have authority to access and alter resources initially created by 2336 other clients. Alternatively, clients may expect to access disjoint 2337 sets of resources, and may expect that their resources are 2338 inaccessible by other clients. These scenarios are called "multi- 2339 tenancy", where each client is understood to be or represent a 2340 "tenant" of the service provider. Clients may also be multi- 2341 tenanted. 2343 The following common cases may occur: 2345 1. All clients share all resources (no tenancy) 2347 2. Each single client creates and accesses a private subset of 2348 resources (1 client:1 Tenant) 2350 3. Sets of clients share sets of resources (M clients:1 Tenant) 2352 4. One client to Multiple Tenants (1 client:M Tenants) 2354 Service providers may implement any subset of the above cases. 2356 Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a 2357 scheme for multi-tenancy. 2359 The SCIM protocol does not prescribe the mechanisms whereby clients 2360 and service providers interact for: 2362 o Registering or provisioning Tenants 2363 o Associating a subset of clients with a subset of the Tenants 2365 o Indicating which tenant is associated with the data in a request 2366 or response, or indicating which Tenant is the subject of a query 2368 4.1. Associating Clients to Tenants 2370 The service provider MAY use the authentication mechanism (Section 2) 2371 to determine the identity of the client, and thus infer the 2372 associated Tenant. 2374 For implementations where a client is associated with more than one 2375 Tenant, the service provider MAY use one of the following methods for 2376 explicit specification of the Tenant. 2378 If any of these methods of allowing the client to explicitly specify 2379 the Tenant are employed, the service provider should ensure that 2380 access controls are in place to prevent or allow cross-tenant use 2381 cases. 2383 The service provider should consider precedence in cases where a 2384 client may explicitly specify a Tenant while being implicitly 2385 associated with a different Tenant. 2387 In all of these methods, the {tenant_id} is a unique identifier for 2388 the Tenant as defined by the service provider. 2390 o A URL prefix: "https://www.example.com/Tenants/{tenant_id}/v2/ 2391 Users" 2393 o A sub-domain: "https://{tenant_id}.example.com/v2/Groups" 2395 o The service provider may recognize a {tenant_id} provided by the 2396 client in an HTTP Header as the indicator of the desired target 2397 Tenant. 2399 4.2. SCIM Identifiers with Multiple Tenants 2401 Considerations for a Multi-Tenant Implementation: 2403 The service provider may choose to implement SCIM ids which are 2404 unique across all resources for all Tenants, but this is not 2405 required. 2407 The externalId, defined by the client, is required to be unique ONLY 2408 within the resources associated with the associated Tenant. 2410 5. Security Considerations 2412 5.1. TLS Support 2414 The SCIM Protocol is based on HTTP and thus subject to the security 2415 considerations found in Section 15 of [RFC2616]. SCIM resources 2416 (e.g., Users and Groups) can contain sensitive information. 2417 Therefore, SCIM clients and service providers MUST implement TLS. 2418 Which version(s) ought to be implemented will vary over time, and 2419 depend on the widespread deployment and known security 2420 vulnerabilities at the time of implementation. At the time of this 2421 writing, TLS version 1.2 [RFC5246] is the most recent version, but 2422 has very limited actual deployment, and might not be readily 2423 available in implementation toolkits. TLS version 1.0 [RFC2246] is 2424 the most widely deployed version, and will give the broadest 2425 interoperability. 2427 5.2. Querying Using HTTP GET 2429 Clients requesting information using query filters SHOULD give 2430 consideration to the information content of the filters and whether 2431 their exposure in a URL would represent a breach of security or 2432 confidentiality through leakage in a web browser or logs. This is 2433 particularly true for information that is legally considered 2434 "personally identifiable information" or is otherwise restricted by 2435 privacy laws. To ensure maximum security and confidentiality, 2436 clients SHOULD query using HTTP POST (see Section 3.2.3). 2438 Servers that receive HTTP GET requests using filters that contain 2439 restricted or confidential information SHOULD respond with HTTP 2440 status 403 indicating the operation is FORBIDDEN. A detialed error, 2441 "confidential_restricted" may be returned indicating the request must 2442 be submitted using POST. A non-normative example: 2444 HTTP/1.1 403 FORBIDDEN 2446 { 2447 "schemas": ["urn:scim:schemas:core:2.0:Error"], 2448 "Errors":[ 2449 { 2450 "description":"Query filter involving 'name' is restricted or confidential", 2451 "error":"confidential_restricted" 2452 } 2453 ] 2454 } 2455 5.3. Universal Identifiers 2457 6. IANA Considerations 2459 6.1. Media Type Registration 2461 To: ietf-types@iana.org 2463 Subject: Registration of media type application/scim+json 2465 Type name: application 2467 Subtype name: scim+json 2469 Required parameters: none 2471 Optional parameters: none 2473 Encoding considerations: 8bit 2475 Security considerations: See Section 5 2477 Interoperability considerations: The "application/scim+json" media 2478 type is intended to identify JSON structure data that conforms to 2479 the SCIM 2 api and schema specifications. Older versions of SCIM 2480 are known to informally use "application/json". 2482 Published specification: [[this document]] 2484 Applications that use this media type: It is expected that 2485 applications that use this type may be special purpose 2486 applications intended for inter-domain provisioning. Clients may 2487 also be applications (e.g. mobile applications) that need to use 2488 SCIM for self-registration of user accounts. SCIM services may be 2489 offered by web applications wishin to offer support for standards 2490 based provisioning or may be a dedicated SCIM service provider 2491 such as a "cloud directory". Content may be treated as equivalent 2492 to "application/json" type for the purpose of displaying in web 2493 browsers. 2495 Additional information: 2497 Magic number(s): 2499 File extension(s): .scim .scm 2501 Macintosh file type code(s): 2503 Person & email address to contact for futher information: SCIM 2504 mailing list "" 2506 Intended usage: COMMON* (see restrictions) 2508 Restrictions on usage: For most client types, it is sufficient to 2509 recognize the content as equivalent to "application/json". 2510 Applications intending to use the SCIM API SHOULD use the 2511 application/scim+json media type. 2513 Author: Phil Hunt 2515 Change controller: IETF 2517 7. References 2519 7.1. Normative References 2521 [I-D.ietf-httpbis-p2-semantics] 2522 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2523 (HTTP/1.1): Semantics and Content", draft-ietf- 2524 httpbis-p2-semantics-25 (work in progress), November 2013. 2526 [I-D.ietf-scim-core-schema] 2527 Grizzle, K., Hunt, P., Wahlstroem, E., and C. Mortimore, 2528 "System for Cross-Domain Identity Management: Core 2529 Schema", draft-ietf-scim-core-schema-03 (work in 2530 progress), February 2014. 2532 [I-D.reschke-http-status-308] 2533 Reschke, J., "The Hypertext Transfer Protocol (HTTP) 2534 Status Code 308 (Permanent Redirect)", draft-reschke-http- 2535 status-308-07 (work in progress), March 2012. 2537 [IANA.Language] 2538 Internet Assigned Numbers Authority (IANA), "Language 2539 Subtag Registry", 2005. 2541 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2542 Requirement Levels", BCP 14, RFC 2119, March 1997. 2544 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2545 RFC 2246, January 1999. 2547 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2548 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2549 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2551 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2552 10646", STD 63, RFC 3629, November 2003. 2554 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2555 Resource Identifier (URI): Generic Syntax", STD 66, RFC 2556 3986, January 2005. 2558 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2559 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2561 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2562 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2564 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 2565 5789, March 2010. 2567 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 2568 Framework: Bearer Token Usage", RFC 6750, October 2012. 2570 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 2571 Interchange Format", RFC 7159, March 2014. 2573 7.2. Informative References 2575 [OpenSearch] 2576 Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . 2578 [Order-Operations] 2579 Wikipedia, "Order of Operations: Programming Languages", . 2581 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 2582 Languages", BCP 18, RFC 2277, January 1998. 2584 [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation 2585 (JSON) Patch", RFC 6902, April 2013. 2587 Appendix A. Contributors 2589 Samuel Erdtman (samuel@erdtman.se) 2591 Patrick Harding (pharding@pingidentity.com) 2593 Appendix B. Acknowledgments 2595 The editors would like to acknowledge the contribution and work of 2596 the past draft editors: 2598 Trey Drake, UnboundID 2599 Chuck Mortimore, Salesforce 2601 The editor would like to thank the participants in the the SCIM 2602 working group for their support of this specification. 2604 Appendix C. Change Log 2606 [[This section to be removed prior to publication as an RFC]] 2608 Draft 02 - KG - Addition of schema extensibility 2610 Draft 03 - PH - Revisions based on following tickets: 2612 24 - Add filter negation 2614 39 - Clarification on response for DELETE 2616 42 - Make root searches optional 2618 49 - Add "ew" filter 2620 50 - Filters for multi-valued complex attributes 2622 51 - Search by Schema 2624 53 - Standard use of term client (some was consumer) 2626 55 - Redirect support (3xx) 2628 56 - Make manager attribute consistent with other $ref attrs 2630 57 - Update all "/v1" examples to '/v2" 2632 59 - Fix capitalization per IETF editor practices 2634 60 - Changed tags to normal and tags 2636 Draft 04 - PH - Revisions based on the following tickets: 2638 18 - New PATCH command based on JSON Patch (RFC6902) 2640 - Provided ABNF specification for filters (used in PATCH) 2642 - Updated references to RFC4627 to RFC7159 2644 Draft 05 - PH - Revisions based on the following tickets: 2646 03 - Support for excludedAttributes parameter 2647 13 - Change client use of Etags from MUST to MAY (correction) 2649 23 - Clarifications regarding case exact processing. 2651 41 - Add IANA considerations 2653 65 - Removed X-HTTP-Method-Override support 2655 69 - Added clarifications to intro to align with draft-nottingham- 2656 uri-get-off-my-lawn 2658 70 - Remove SCIM_TENANT_ID header 2660 72 - Added text to indicate UTF-8 is default and mandatory 2661 encoding format per BCP18 2663 74 - Added security considerations for using GET with confidential 2664 attribute filters 2666 - corrected error response in JSON PATCH operation 2668 Authors' Addresses 2670 Phil Hunt (editor) 2671 Oracle Corporation 2673 Email: phil.hunt@yahoo.com 2675 Kelly Grizzle 2676 SailPoint 2678 Email: kelly.grizzle@sailpoint.com 2680 Morteza Ansari 2681 Cisco 2683 Email: morteza.ansari@cisco.com 2685 Erik Wahlstroem 2686 Technology Nexus 2688 Email: erik.wahlstrom@nexussafe.com 2689 Chuck Mortimore 2690 Salesforce.com 2692 Email: cmortimore@salesforce.com