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