idnits 2.17.1 draft-ietf-scim-api-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 36 instances of too long lines in the document, the longest one being 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 1, 2014) is 3554 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 2832, but no explicit reference was found in the text == Unused Reference: 'RFC3454' is defined on line 2836, but no explicit reference was found in the text == Unused Reference: 'RFC2277' is defined on line 2892, 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-06 ** 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 2, 2015 SailPoint 6 M. Ansari 7 Cisco 8 E. Wahlstroem 9 Nexus Technology 10 C. Mortimore 11 Salesforce 12 August 1, 2014 14 System for Cross-Domain Identity Management:Protocol 15 draft-ietf-scim-api-08 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 2, 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 . . . . . . . . . . . . . . . . . . . 36 83 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 36 84 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 51 85 3.7. Additional Operation Response Parameters . . . . . . . . 52 86 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 53 87 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 54 88 3.10. HTTP Status and Error Response Handling . . . . . . . . . 54 89 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 58 90 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 58 91 4. Preparation and Comparison of Internationalized Strings . . . 60 92 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 60 93 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 61 94 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 62 95 6. Security Considerations . . . . . . . . . . . . . . . . . . . 62 96 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 62 97 6.2. Disclosure of Sensitive Information in URIs . . . . . . . 62 98 6.3. HTTP Considerations . . . . . . . . . . . . . . . . . . . 63 99 6.4. Secure Storage and Handling of Sensitive Data . . . . . . 63 100 6.5. Case Insensitive Comparision & International Languages . 64 101 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 64 102 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 64 103 7.2. SCIM API Message Schema Registry . . . . . . . . . . . . 65 104 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 66 105 8.1. Normative References . . . . . . . . . . . . . . . . . . 66 106 8.2. Informative References . . . . . . . . . . . . . . . . . 67 107 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 68 108 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 68 109 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 68 110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 71 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: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: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: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:scim:api:messages:2.0:ListResponse". The following attributes 408 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: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: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:scim:api:messages:2.0"], 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:scim:api:messages:2.0:SearchRequest'. The following attributes 887 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: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: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:scim:api:messages: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:scim:api:messages: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 Each operation object MUST contain the following "schemas" URI: 1112 "urn:scim:api:messages:2.0:PatchOp" 1114 Operation objects MUST have exactly one "path" member which is a 1115 "String" containing an attribute path as specified by the following 1116 ABNF syntax rule: 1118 PATH = attrPath / valuePath [subAttr] 1120 Figure 5: SCIM Patch PATH Rule 1122 The ABNF rules, "attrPath", "valuePath", and "subAttr" are defined in 1123 Section 3.2.2.2. The "valuePath" rule allows specific values of a 1124 complex, multi-valued attribute to be selected. 1126 Valid examples of "path" values are as follows: 1128 "path":"members" 1130 "path":"name.familyName" 1132 "path":"addresses[type eq \"work\"]" 1134 "path":"members[value eq 1135 \"2819c223-7f76-453a-919d-413861904646\"]" 1137 "path":"members[value eq 1138 \"2819c223-7f76-453a-919d-413861904646\"].displayName" 1140 Figure 6: Example Path Values 1142 Each operation against an attribute MUST be compatible with the 1143 attribute's mutability and schema as defined in the Attribute Types 1144 Section of [I-D.ietf-scim-core-schema]. For example, a client MAY 1145 NOT modify an attribute that has mutability "readOnly" or 1146 "immutable". However, a client MAY "add" a value to an "immutable" 1147 attribute if the attribute had no previous value. An operation that 1148 is not compatibile with an attribute's mutability or schema SHALL 1149 return the appropriate HTTP response status code and a JSON detail 1150 error response as defined in Section 3.10. 1152 The attribute notation rules described in Section 3.8 apply for 1153 describing attribute paths. For all operations, the value of the 1154 "schemas" attribute on the service provider's representation of the 1155 resource SHALL be assumed by default. If one of the PATCH operations 1156 modifies the "schemas" attribute, subsequent operations SHALL assume 1157 the modified state of the "schemas" attribute. Clients MAY 1158 implicitly modify the "schemas" attribute by adding (or replacing) an 1159 attribute with its fully qualified name including schema URN. For 1160 example, adding the attribute 1161 "urn:scim:schemas:extension:enterprise:2.0:User:employeeNumber", 1162 automatically adds the value 1163 "urn:scim:schemas:extension:enterprise:2.0:User" to the resource's 1164 "schemas" attribute. 1166 Each patch operation represents a single action to be applied to the 1167 same SCIM resource specified by the request URI. Operations are 1168 applied sequentially in the order they appear in the array. Each 1169 operation in the sequence is applied to the target resource; the 1170 resulting resource becomes the target of the next operation. 1171 Evaluation continues until all operations are successfully applied or 1172 until an error condition is encountered. 1174 For a multi-valued attributes, a patch operation that sets a value's 1175 "primary" attribute to "true", SHALL cause the server to 1176 automatically set "primary" to "false" for any other values in the 1177 array as only one value MAY be primary. 1179 A patch request, regardless of the number of operations, SHALL be 1180 treated as atomic. If a single operation encounters an error 1181 condition, the original SCIM resource MUST be restored, and a failure 1182 status SHALL be returned. 1184 If a request fails, the server SHALL return an HTTP response status 1185 code and a JSON detail error response as defined in Section 3.10. 1187 On successful completion, the server MUST return either a 200 OK 1188 response code and the entire resource (subject to the "attributes" 1189 query parameter - see Additional Retrieval Query Parameters 1190 (Section 3.7) ) within the response body, or a 204 No Content 1191 response code and the appropriate response headers for a successful 1192 patch request. The server MUST return a 200 OK if the "attributes" 1193 parameter is specified on the request. 1195 3.3.2.1. Add Operation 1197 The "add" operation is used to add a new attribute value to an 1198 existing resource. 1200 The operation MUST contain a "value" member whose content specifies 1201 the value to be added. The value MAY be a quoted value OR it may be 1202 a JSON object containing the sub-attributes of the complex attribute 1203 specified in the operation's "path". 1205 The result of the add operation depends upon what the target location 1206 indicated by "path" references: 1208 o If the target location does not exist, the attribute and value is 1209 added. 1211 o If the target location specifies a multi-valued attribute, a new 1212 value is added to the attribute. 1214 o if the target location specifies a single-valued attribute, the 1215 existing value is replaced. 1217 o If the target location specifies an attribute that does not exist 1218 (has no value), the attribute is added with the new value. 1220 o If the target location exists, the value is replaced. 1222 o If the target location already contains the value specified, no 1223 changes SHOULD be made to the resource and a success response 1224 SHOULD be returned. Unless other operations change the resource, 1225 this operation SHALL NOT change the modify timestamp of the 1226 resource. 1228 The following example shows how to add a member to a group. Some 1229 text removed for readability ("..."): 1231 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1232 Host: example.com 1233 Accept: application/scim+json 1234 Content-Type: application/scim+json 1235 Authorization: Bearer h480djs93hd8 1236 If-Match: W/"a330bc54f0671c9" 1238 { 1239 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1240 "op":"add", 1241 "path":"members", 1242 "value":[ 1243 { 1244 "display": "Babs Jensen", 1245 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1246 "value": "2819c223-7f76-453a-919d-413861904646" 1247 } 1248 ] 1249 } 1251 The "display" Sub-Attribute in this request is optional since the 1252 value attribute uniquely identifies the user to be added. If the 1253 user was already a member of this group, no changes should be made to 1254 the resource and a success response should be returned. The server 1255 responds with either the entire updated Group or no response body: 1257 HTTP/1.1 204 No Content 1258 Authorization: Bearer h480djs93hd8 1259 ETag: W/"b431af54f0671a2" 1260 Location: "https://example.com/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" 1262 3.3.2.2. Remove Operation 1264 The "remove" operation removes the value at the target location 1265 specified by the "path". The operation performs the following 1266 functions depending on the target location specified by "path" : 1268 o If the target location is a single-value attribute, the attribute 1269 and its associated value is removed and the attribute SHALL be 1270 considered unassigned. 1272 o If the target location is a multi-valued attribute and no filter 1273 is specified, the attribute and all values are removed and the 1274 attribute SHALL be considered unassigned. 1276 o If the target location is a multi-valued attribute and a complex 1277 filter is specified comparing a "value", the values matched by the 1278 filter are removed. If after removal of the selected values, no 1279 other values remain, the multi-valued attribute SHALL be 1280 considered unassigned. 1282 o If the target location is a complex-multi-valued attribute and a 1283 complex filter is specified based on the attribute's sub- 1284 attributes, the matching records are removed. Sub-attributes 1285 whose values have been removed SHALL be considered unassigned. If 1286 the complex-multi-valued attribute has no remaining records, the 1287 attribute SHALL be considered unassigned. 1289 If an attribute is removed or becomes unassigned and is defined as a 1290 required attribute or a read-only attribute, the server SHALL return 1291 an HTTP response status code and a JSON detail error response as 1292 defined in Section 3.10 with a "scimType" error of "mutability". 1294 The following example shows how to remove a member from a group. As 1295 with the previous example, the "display" sub-attribute is optional. 1296 If the user was not a member of this group, no changes should be made 1297 to the resource and a success response should be returned. 1299 Note that server responses have been omitted for the rest of the 1300 PATCH examples. 1302 Remove a single member from a group. Some text removed for 1303 readability ("..."): 1305 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1306 Host: example.com 1307 Accept: application/scim+json 1308 Content-Type: application/scim+json 1309 Authorization: Bearer h480djs93hd8 1310 If-Match: W/"a330bc54f0671c9" 1312 { 1313 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1314 "op":"remove", 1315 "path":"members[value eq \"2819c223-7f76-...413861904646\"]" 1316 } 1318 Remove all members of a group: 1320 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1321 Host: example.com 1322 Accept: application/scim+json 1323 Content-Type: application/scim+json 1324 Authorization: Bearer h480djs93hd8 1325 If-Match: W/"a330bc54f0671c9" 1327 { "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1328 "op":"remove","path":"members"} 1330 Removal of a value from a complex-multi-valued attribute (request 1331 headers removed for brevity): 1333 { 1334 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1335 "op":"remove", 1336 "path":"emails[type eq \"work\" and value ew \"example.com\"]" 1337 } 1338 Example request to remove and add a member. Some text removed for 1339 readability ("..."): 1341 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1342 Host: example.com 1343 Accept: application/scim+json 1344 Content-Type: application/scim+json 1345 Authorization: Bearer h480djs93hd8 1346 If-Match: W/"a330bc54f0671c9" 1348 [ 1349 { 1350 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1351 "op":"remove", 1352 "path":"members[value eq\"2819c223...919d-413861904646\"]" 1353 }, 1354 { 1355 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1356 "op":"add", 1357 "path":"members", 1358 "value": [ 1359 { 1360 "display": "James Smith", 1361 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1362 "value": "08e1d05d...473d93df9210" 1363 } 1364 ] 1365 } 1366 ] 1367 The following example shows how to replace all the members of a group 1368 with a different members list. Some text removed for readabilty 1369 ("..."): 1371 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1372 Host: example.com 1373 Accept: application/scim+json 1374 Content-Type: application/scim+json 1375 Authorization: Bearer h480djs93hd8 1376 If-Match: W/"a330bc54f0671c9" 1378 [ 1379 { "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1380 "op":"remove","path":"members"}, 1381 { 1382 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1383 "op":"add", 1384 "path":"members", 1385 "value":[ 1386 { 1387 "display": "Babs Jensen", 1388 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1389 "value": "2819c223-7f76-453a-919d-413861904646" 1390 }, 1391 { 1392 "display": "James Smith", 1393 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1394 "value": "08e1d05d-121c-4561-8b96-473d93df9210" 1395 }] 1396 } 1397 ] 1399 3.3.2.3. Replace Operation 1401 The "replace" operation replaces the value at the target location 1402 specified by the "path". The operation performs the following 1403 functions depending on the target location specified by "path" : 1405 o If the target location is a single-value attribute, the attributes 1406 value is replaced. 1408 o If the target location is a multi-valued attribute and no filter 1409 is specified, the attribute and all values are replaced. 1411 o If the target location is a multi-valued attribute and a complex 1412 filter is specified comparing a "value", the values matched by the 1413 filter are replaced. 1415 o If the target location is a complex-multi-valued attribute and a 1416 complex filter is specified based on the attribute's sub- 1417 attributes, the matching records are replaced. 1419 o If the target location is a complex-multi-valued attribute with a 1420 complex filter and a specific sub-attribute (e.g. "addresses[type 1421 eq "work"].streetAddress" ), the matching sub-attribute of the 1422 matching record is replaced. 1424 The following example shows how to replace all the members of a group 1425 with a different members list in a single replace operation. Some 1426 text removed for readability ("..."): 1428 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1429 Host: example.com 1430 Accept: application/scim+json 1431 Content-Type: application/scim+json 1432 Authorization: Bearer h480djs93hd8 1433 If-Match: W/"a330bc54f0671c9" 1435 { 1436 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1437 "op":"replace", 1438 "path":"members", 1439 "value":[ 1440 { 1441 "display": "Babs Jensen", 1442 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1443 "value": "2819c223...413861904646" 1444 }, 1445 { 1446 "display": "James Smith", 1447 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1448 "value": "08e1d05d...473d93df9210" 1449 } 1450 ] 1451 } 1452 The following example shows how to change a User's entire "work" 1453 address. 1455 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1456 Host: example.com 1457 Accept: application/scim+json 1458 Content-Type: application/scim+json 1459 Authorization: Bearer h480djs93hd8 1460 If-Match: W/"a330bc54f0671c9" 1462 { 1463 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1464 "op":"replace", 1465 "path":"addresses[type eq \"work\"]", 1466 "value": 1467 { 1468 "type": "work", 1469 "streetAddress": "911 Universal City Plaza", 1470 "locality": "Hollywood", 1471 "region": "CA", 1472 "postalCode": "91608", 1473 "country": "US", 1474 "formatted": "911 Universal City Plaza\nHollywood, CA 91608 US", 1475 "primary": true 1476 } 1477 } 1479 The following example shows how to change a User's address. Since 1480 address does not have a value Sub-Attribute, the existing address 1481 must be removed and the modified address added. 1483 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1484 Host: example.com 1485 Accept: application/scim+json 1486 Content-Type: application/scim+json 1487 Authorization: Bearer h480djs93hd8 1488 If-Match: W/"a330bc54f0671c9" 1490 { 1491 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1492 "op":"replace", 1493 "path":"addresses[type eq \"work\"].streetAddress", 1494 "value":"911 Universal City Plaza" 1495 } 1497 3.4. Deleting Resources 1499 Clients request resource removal via DELETE. Service providers MAY 1500 choose not to permanently delete the resource, but MUST return a 404 1501 error code for all operations associated with the previously deleted 1502 Id. Service providers MUST also omit the resource from future query 1503 results. In addition the service provider SHOULD NOT consider the 1504 deleted resource in conflict calculation. For example if a User 1505 resource is deleted, a CREATE request for a User resource with the 1506 same userName as the previously deleted resource should not fail with 1507 a 409 error due to userName conflict. 1509 DELETE /Users/2819c223-7f76-453a-919d-413861904646 1510 Host: example.com 1511 Authorization: Bearer h480djs93hd8 1512 If-Match: W/"c310cd84f0281b7" 1514 In response to a successful delete, the server SHALL respond with 1515 successful HTTP status 204 (No Content). A non-normative example 1516 response: 1518 HTTP/1.1 204 No Content 1520 Example: client attempt to retrieve the previously deleted User 1522 GET /Users/2819c223-7f76-453a-919d-413861904646 1523 Host: example.com 1524 Authorization: Bearer h480djs93hd8 1526 Server Response: 1528 HTTP/1.1 404 NOT FOUND 1530 { 1531 "schemas": ["urn:scim:api:messages:2.0:Error"], 1532 "Errors":[ 1533 { 1534 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 1535 "code":"404" 1536 } 1537 ] 1538 } 1540 3.5. Bulk 1542 The SCIM bulk operation is an optional server feature that enables 1543 clients to send a potentially large collection of resource operations 1544 in a single request. The body of a a bulk operation contains a set 1545 of HTTP resource operations using one of the API supported HTTP 1546 methods; i.e., POST, PUT, PATCH or DELETE. 1548 Bulk requests are identified using the following URI: 1549 'urn:scim:api:messages:2.0:BulkRequest'. Bulk responses are 1550 identified using the following URI: 1551 'urn:scim:api:messages:2.0:BulkResponse'. Bulk requests and bulk 1552 responses share many attributes. Unless otherwise specified, each 1553 attribute below is present in both bulk requests and bulk responses. 1555 The following Singular Attribute is defined in addition to the common 1556 attributes defined in SCIM core schema. 1558 failOnErrors An Integer specifying the number of errors that the 1559 service provider will accept before the operation is terminated 1560 and an error response is returned. OPTIONAL in a request. Not 1561 valid in a response. 1563 The following Complex Multi-valued Attribute is defined in addition 1564 to the common attributes defined in core schema. 1566 Operations Defines operations within a bulk job. Each operation 1567 corresponds to a single HTTP request against a resource endpoint. 1568 REQUIRED. 1570 method The HTTP method of the current operation. Possible values 1571 are POST, PUT, PATCH or DELETE. REQUIRED. 1573 bulkId The transient identifier of a newly created resource, 1574 unique within a bulk request and created by the client. The 1575 bulkId serves as a surrogate resource id enabling clients to 1576 uniquely identify newly created resources in the Response and 1577 cross reference new resources in and across operations within a 1578 bulk request. REQUIRED when method is POST. 1580 version The current resource version. Version is MAY be used if 1581 the service provider supports ETags and the method is PUT, 1582 PATCH, or DELETE. 1584 path The resource's relative path. If the method is POST the 1585 value must specify a resource type endpoint; e.g., /Users or 1586 /Groups whereas all other method values must specify the path 1587 to a specific resource; e.g., /Users/2819c223-7f76-453a-919d- 1588 413861904646. REQUIRED in a request. 1590 data The resource data as it would appear for a single POST, PUT 1591 or PATCH resource operation. REQUIRED in a request when method 1592 is POST, PUT and PATCH. 1594 location The resource endpoint URL. REQUIRED in a response, 1595 except in the event of a POST failure. 1597 response The HTTP response body to the specified request 1598 operation. When indicating a response with an HTTP status 1599 other than a 200 series response, the response body MUST be 1600 included. For normal completion, the server MAY elect to omit 1601 the response body. 1603 status The HTTP response status code to the requested operation. 1604 When indicating an error, the "response" attribute MUST contain 1605 the detailed error response as per Section 3.10. 1607 If a bulk job is processed successfully the HTTP response code 200 OK 1608 MUST be returned, otherwise an appropriate HTTP error code MUST be 1609 returned. 1611 The service provider MUST continue performing as many changes as 1612 possible and disregard partial failures. The client MAY override 1613 this behavior by specifying a value for the "failOnErrors" attribute. 1614 The failOnErrors attribute defines the number of errors that the 1615 service provider should accept before failing the remaining 1616 operations returning the response. 1618 To be able to reference a newly created resource the attribute bulkId 1619 MUST be specified when creating new resources. The bulkId is defined 1620 by the client as a surrogate identifier in a POST operation. The 1621 service provider MUST return the same bulkId together with the newly 1622 created resource. The bulkId can then be used by the client to map 1623 the service provider id with the bulkId of the created resource. 1625 A SCIM service provider MAY elect to optimize a sequence operations 1626 received (e.g. to improve processing performance). When doing so, 1627 the service provider MUST ensure the clients intent is preserved and 1628 the same stateful result is achieved as for non-optimized processing. 1629 For example, before a "User" can be added to a "Group", they must 1630 first be created. Processing these requests out of order, might 1631 result in a failure to add the new "User" to the "Group". 1633 The service provider response MUST include the result of all 1634 processed operations. A "location" attribute that includes the 1635 resource's endpoint MUST be returned for all operations excluding 1636 failed POSTs. The status attribute includes information about the 1637 success or failure of one operation within the bulk job. The 1638 attribute status MUST include the code attribute that holds the HTTP 1639 response code that would have been returned if a single HTTP request 1640 would have been used. If an error occurred the status MUST also 1641 include the description attribute containing a human readable 1642 explanation of the error. 1644 "status": "201" 1646 The following is an example of a status in a failed operation. 1648 "status": "400", 1649 "response":{ 1650 "schemas": ["urn:scim:api:messages:2.0:Error"], 1651 "scimType":"invalidSyntax" 1652 "detail":"Request is unparseable, syntactically incorrect, or violates schema.", 1653 "status":"400" 1654 } 1656 The following example shows how to add, update, and remove a user. 1657 The failOnErrors attribute is set to '1' indicating the service 1658 provider should return on the first error. The POST operation's 1659 bulkId value is set to 'qwerty' enabling the client to match the new 1660 User with the returned resource id '92b725cd-9465-4e7d- 1661 8c16-01f8e146b87a'. 1663 POST /v2/Bulk 1664 Host: example.com 1665 Accept: application/scim+json 1666 Content-Type: application/scim+json 1667 Authorization: Bearer h480djs93hd8 1668 Content-Length: ... 1670 { 1671 "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], 1672 "failOnErrors":1, 1673 "Operations":[ 1674 { 1675 "method":"POST", 1676 "path":"/Users", 1677 "bulkId":"qwerty", 1678 "data":{ 1679 "schemas": ["urn:scim:api:messages:2.0:User"], 1680 "userName":"Alice" 1681 } 1682 }, 1683 { 1684 "method":"PUT", 1685 "path":"/Users/b7c14771-226c-4d05-8860-134711653041", 1686 "version":"W\/\"3694e05e9dff591\"", 1687 "data":{ 1688 "schemas": ["urn:scim:api:messages:2.0:User"], 1689 "id":"b7c14771-226c-4d05-8860-134711653041", 1690 "userName":"Bob" 1691 } 1692 }, 1693 { 1694 "method": "PATCH", 1695 "path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1696 "version": "W/\"edac3253e2c0ef2\"", 1697 "data": {[ 1698 { 1699 "op": "remove", 1700 "path": "nickName" 1701 }, 1702 { 1703 "op": "add", 1704 "path": "userName", 1705 "value": "Dave" 1706 } 1707 ]} 1708 }, 1709 { 1710 "method":"DELETE", 1711 "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1712 "version":"W\/\"0ee8add0a938e1a\"" 1713 } 1714 ] 1715 } 1717 The service provider returns the following response. 1719 HTTP/1.1 200 OK 1720 Content-Type: application/scim+json 1722 { 1723 "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], 1724 "Operations": [ 1725 { 1726 "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1727 "method": "POST", 1728 "bulkId": "qwerty", 1729 "version": "W\/\"oY4m4wn58tkVjJxK\"", 1730 "status": "201" 1731 }, 1732 { 1733 "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 1734 "method": "PUT", 1735 "version": "W\/\"huJj29dMNgu3WXPD\"", 1736 "status": "200" 1737 }, 1738 { 1739 "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1740 "method": "PATCH", 1741 "version": "W\/\"huJj29dMNgu3WXPD\"", 1742 "status": "200" 1743 }, 1744 { 1745 "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1746 "method": "DELETE", 1747 "status": "204" 1748 } 1749 ] 1750 } 1752 The following response is returned if an error occurred when 1753 attempting to create the User 'Alice'. The service provider stops 1754 processing the bulk operation and immediately returns a response to 1755 the client. The response contains the error and any successful 1756 results prior to the error. 1758 HTTP/1.1 200 OK 1759 Content-Type: application/scim+json 1761 { 1762 "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], 1763 "Operations": [ 1764 { 1765 "method": "POST", 1766 "bulkId": "qwerty", 1767 "status": "400", 1768 "response":{ 1769 "schemas": ["urn:scim:api:messages:2.0:Error"], 1770 "scimType":"invalidSyntax" 1771 "detail":"Request is unparseable, syntactically incorrect, or violates schema.", 1772 "status":"400" 1773 } 1774 } 1775 ] 1776 } 1778 If the failOnErrors attribute is not specified or the service 1779 provider has not reached the error limit defined by the client the 1780 service provider will continue to process all operations. The 1781 following is an example in which all operations failed. 1783 HTTP/1.1 200 OK 1784 Content-Type: application/scim+json 1786 { 1787 "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], 1788 "Operations": [ 1789 { 1790 "method": "POST", 1791 "bulkId": "qwerty", 1792 "status": "400", 1793 "response":{ 1794 "schemas": ["urn:scim:api:messages:2.0:Error"], 1795 "scimType":"invalidSyntax" 1796 "detail":"Request is unparseable, syntactically incorrect, or violates schema.", 1797 "status":"400" 1798 } 1799 }, 1800 { 1801 "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 1802 "method": "PUT", 1803 "status": "412", 1804 "response":{ 1805 "schemas": ["urn:scim:api:messages:2.0:Error"], 1806 "detail":"Failed to update as user changed on the server since you last retrieved it.", 1807 "status":"412" 1808 } 1809 }, 1810 { 1811 "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1812 "method": "PATCH", 1813 "status": "412", 1814 "response":{ 1815 "schemas": ["urn:scim:api:messages:2.0:Error"], 1816 "detail":"Failed to update as user changed on the server since you last retrieved it.", 1817 "status":"412" 1818 } 1819 }, 1820 { 1821 "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1822 "method": "DELETE", 1823 "status": "404", 1824 "response":{ 1825 "schemas": ["urn:scim:api:messages:2.0:Error"], 1826 "detail":"Resource does not exist.", 1827 "status":"404" 1828 } 1829 } 1830 ] 1831 } 1833 The client can, within one bulk operation, create a new User, a new 1834 Group and add the newly created User to the newly created Group. In 1835 order to add the new User to the Group the client must use the 1836 surrogate id attribute, bulkId, to reference the User. The bulkId 1837 attribute value must be pre-pended with the literal "bulkId:"; e.g., 1838 if the bulkId is 'qwerty' the value is "bulkId:qwerty". The service 1839 provider MUST replace the string "bulkId:qwerty" with the permanent 1840 resource id once created. 1842 The following example creates a User with the userName 'Alice' and a 1843 Group with the displayName 'Tour Guides' with Alice as a member. 1845 POST /v2/Bulk 1846 Host: example.com 1847 Accept: application/scim+json 1848 Content-Type: application/scim+json 1849 Authorization: Bearer h480djs93hd8 1850 Content-Length: ... 1852 { 1853 "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], 1854 "Operations": [ 1855 { 1856 "method": "POST", 1857 "path": "/Users", 1858 "bulkId": "qwerty", 1859 "data": { 1860 "schemas": ["urn:scim:schemas:core:2.0:User"], 1861 "userName": "Alice" 1862 } 1863 }, 1864 { 1865 "method": "POST", 1866 "path": "/Groups", 1867 "bulkId": "ytrewq", 1868 "data": { 1869 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1870 "displayName": "Tour Guides", 1871 "members": [ 1872 { 1873 "type": "User", 1874 "value": "bulkId:qwerty" 1875 } 1876 ] 1877 } 1878 } 1879 ] 1880 } 1882 The service provider returns the following response. 1884 HTTP/1.1 200 OK 1885 Content-Type: application/scim+json 1887 { 1888 "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], 1889 "Operations": [ 1890 { 1891 "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1892 "method": "POST", 1893 "bulkId": "qwerty", 1894 "version": "W\/\"4weymrEsh5O6cAEK\"", 1895 "status": "201" 1896 }, 1897 { 1898 "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1899 "method": "POST", 1900 "bulkId": "ytrewq", 1901 "version": "W\/\"lha5bbazU3fNvfe5\"", 1902 "status": "201" 1903 } 1904 ] 1905 } 1907 A subsequent request for the 'Tour Guides' Group ('e9e30dba-f08f- 1908 4109-8486-d5c6a331660a') returns the following: 1910 GET /v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1911 Host: example.com 1912 Accept: application/scim+json 1913 Authorization: Bearer h480djs93hd8 1915 HTTP/1.1 200 OK 1916 Content-Type: application/scim+json 1917 Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1918 ETag: W/"lha5bbazU3fNvfe5" 1920 { 1921 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1922 "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", 1923 "displayName": "Tour Guides", 1924 "meta": { 1925 "resourceType": "Group", 1926 "created": "2011-08-01T18:29:49.793Z", 1927 "lastModified": "2011-08-01T20:31:02.315Z", 1928 "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1929 "version": "W\/\"lha5bbazU3fNvfe5\"" 1930 }, 1931 "members": [ 1932 { 1933 "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", 1934 "$ref": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1935 "type": "User" 1936 } 1937 ] 1938 } 1940 Extensions that include references to other resources MUST be handled 1941 in the same way by the service provider. The following example uses 1942 the bulkId attribute within the enterprise extension managerId 1943 attribute. 1945 POST /v2/Bulk 1946 Host: example.com 1947 Accept: application/scim+json 1948 Content-Type: application/scim+json 1949 Authorization: Bearer h480djs93hd8 1950 Content-Length: ... 1952 { 1953 "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], 1954 "Operations": [ 1955 { 1956 "method": "POST", 1957 "path": "/Users", 1958 "bulkId": "qwerty", 1959 "data": { 1960 "schemas": ["urn:scim:schemas:core:2.0:User"], 1961 "userName": "Alice" 1962 } 1963 }, 1964 { 1965 "method": "POST", 1966 "path": "/Users", 1967 "bulkId": "ytrewq", 1968 "data": { 1969 "schemas": [ 1970 "urn:scim:schemas:core:2.0:User", 1971 "urn:scim:schemas:extension:enterprise:2.0:User" 1972 ], 1973 "userName": "Bob", 1974 "urn:scim:schemas:extension:enterprise:2.0:User": { 1975 "employeeNumber": "11250", 1976 "manager": { 1977 "managerId": "batchId:qwerty", 1978 "displayName": "Alice" 1979 } 1980 } 1981 } 1982 } 1983 ] 1984 } 1986 The service provider MUST try to resolve circular cross references 1987 between resources in a single bulk job but MAY stop after a failed 1988 attempt and instead return the status code 409 Conflict. The 1989 following example exhibits the potential conflict. 1991 POST /v2/Bulk 1992 Host: example.com 1993 Accept: application/scim+json 1994 Content-Type: application/scim+json 1995 Authorization: Bearer h480djs93hd8 1996 Content-Length: ... 1998 { 1999 "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], 2000 "Operations": [ 2001 { 2002 "method": "POST", 2003 "path": "/Groups", 2004 "bulkId": "qwerty", 2005 "data": { 2006 "schemas": ["urn:scim:schemas:core:2.0:Group"], 2007 "displayName": "Group A", 2008 "members": [ 2009 { 2010 "type": "Group", 2011 "value": "bulkId:ytrewq" 2012 } 2013 ] 2014 } 2015 }, 2016 { 2017 "method": "POST", 2018 "path": "/Groups", 2019 "bulkId": "ytrewq", 2020 "data": { 2021 "schemas": ["urn:scim:schemas:core:2.0:Group"], 2022 "displayName": "Group B", 2023 "members": [ 2024 { 2025 "type": "Group", 2026 "value": "bulkId:qwerty" 2027 } 2028 ] 2029 } 2030 } 2031 ] 2032 } 2034 If the service provider resolved the above circular references the 2035 following is returned from a subsequent GET request. 2037 GET /v2/Groups?filter=displayName sw 'Group' 2038 Host: example.com 2039 Accept: application/scim+json 2040 Authorization: Bearer h480djs93hd8 2042 HTTP/1.1 200 OK 2043 Content-Type: application/scim+json 2045 { 2046 "schemas": ["urn:scim:api:messages:2.0:ListResponse"], 2047 "totalResults": 2, 2048 "Resources": [ 2049 { 2050 "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 2051 "schemas": ["urn:scim:schemas:core:2.0:Group"], 2052 "displayName": "Group A", 2053 "meta": { 2054 "resourceType": "Group", 2055 "created": "2011-08-01T18:29:49.793Z", 2056 "lastModified": "2011-08-01T18:29:51.135Z", 2057 "location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 2058 "version": "W\/\"mvwNGaxB5SDq074p\"" 2059 }, 2060 "members": [ 2061 { 2062 "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 2063 "$ref": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 2064 "type": "Group" 2065 } 2066 ] 2067 }, 2068 { 2069 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 2070 "schemas": ["urn:scim:schemas:core:2.0:Group"], 2071 "displayName": "Group B", 2072 "meta": { 2073 "resourceType": "Group", 2074 "created": "2011-08-01T18:29:50.873Z", 2075 "lastModified": "2011-08-01T18:29:50.873Z", 2076 "location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 2077 "version": "W\/\"wGB85s2QJMjiNnuI\"" 2078 }, 2079 "members": [ 2080 { 2081 "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 2082 "$ref": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 2083 "type": "Group" 2084 } 2085 ] 2086 } 2087 ] 2088 } 2089 The service provider MUST define the maximum number of operations and 2090 maximum payload size a client may send in a single request. If 2091 either limits are exceeded the service provider MUST return the HTTP 2092 response code 413 Request Entity Too Large. The returned response 2093 MUST specify the limit exceeded in the body of the error response. 2095 The following example the client sent a request exceeding the service 2096 provider's max payload size of 1 megabyte. 2098 POST /v2/Bulk 2099 Host: example.com 2100 Accept: application/scim+json 2101 Content-Type: application/scim+json 2102 Authorization: Bearer h480djs93hd8 2103 Content-Length: 4294967296 2105 ... 2107 HTTP/1.1 413 Request Entity Too Large 2108 Content-Type: application/scim+json 2110 { 2111 "schemas":["urn:scim:api:messages:2.0:Error"], 2112 "status": "413", 2113 "detail":"The size of the bulk operation exceeds the maxPayloadSize (1048576)." 2114 } 2116 3.6. Data Input/Output Formats 2118 Servers MUST accept requests and respond with JSON structured 2119 responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default 2120 encoding format. 2122 Clients using other encodings MUST specify the format in which the 2123 data is submitted via HTTP header "Content-Type" as specified in 2124 Section 3.1.1.5 [RFC7231] and MAY specify the desired response data 2125 format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g., 2126 "Accept: application/scim+json" or via URI suffix; e.g., 2128 GET /Users/2819c223-7f76-453a-919d-413861904646.scim 2129 Host: example.com 2131 Service providers MUST support the accept header "Accept: 2132 application/scim+json" and SHOULD support header "Accept: 2133 application/json" both of which specify JSON documents conforming to 2135 [RFC7159]. The format defaults to "application/scim+json" if no 2136 format is specified. 2138 Singular attributes are encoded as string name-value-pairs in JSON; 2139 e.g., 2141 "attribute": "value" 2143 Multi-valued attributes in JSON are encoded as arrays; e.g., 2145 "attributes": [ "value1", "value2" ] 2147 Elements with nested elements are represented as objects in JSON; 2148 e.g, 2150 "attribute": { "subattribute1": "value1", "subattribute2": "value2" } 2152 3.7. Additional Operation Response Parameters 2154 For any SCIM operation where a resource representation is returned 2155 (e.g. HTTP GET), the attributes returned are defined as the minimum 2156 attribute set plus default attributes set. The minimum set are those 2157 attributes whose schema have "returned" set to "always". The default 2158 attribute set are those attributes whose schema have "returned" set 2159 to "default". 2161 Clients MAY request a partial resource representation on any 2162 operation that returns a resource within the response by specifying 2163 either of the mutually exclusive URL query parameters "attributes" OR 2164 "excludedAtributes" as follows: 2166 attributes When specified the default list of attributes SHALL be 2167 overridden and each resource returned MUST contain the 2168 minimum set of resource attributes and any attributes or sub- 2169 attributes explicitly requested by the "attributes" 2170 parameter. The query parameter attributes value is a comma 2171 separated list of resource attribute names in standard 2172 attribute notation (Section 3.8) form (e.g. userName, name, 2173 emails). 2175 excludedAttributes When specified, each resource returned MUST 2176 contain the minimal set of resource attributes. 2177 Additionally, the default set of attributes minus those 2178 attributes listed in "excludedAttributes" are also returned. 2179 The query parameter attributes value is a comma separated 2180 list of resource attribute names in standard attribute 2181 notation (Section 3.8) form (e.g. userName, name, emails). 2183 . 2185 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName 2186 Host: example.com 2187 Accept: application/scim+json 2188 Authorization: Bearer h480djs93hd8 2190 Giving the response 2192 HTTP/1.1 200 OK 2193 Content-Type: application/scim+json 2194 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2195 ETag: W/"a330bc54f0671c9" 2197 { 2198 "schemas":["urn:scim:schemas:core:2.0:User"], 2199 "id":"2819c223-7f76-453a-919d-413861904646", 2200 "userName":"bjensen", 2201 "meta":{ 2202 "resourceType": "User", 2203 "created":"2011-08-01T18:29:49.793Z", 2204 "lastModified":"2011-08-01T18:29:49.793Z", 2205 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2206 "version":"W\/\"a330bc54f0671c9\"" 2207 } 2208 } 2210 3.8. Attribute Notation 2212 All operations share a common scheme for referencing simple and 2213 complex attributes. In general, attributes are identified by 2214 prefixing the attribute name with its schema URN separated by a ':' 2215 character; e.g., the core User resource attribute 'userName' is 2216 identified as 'urn:scim:schemas:core:2.0:User:userName'. Clients MAY 2217 omit core schema attribute URN prefixes though MUST fully qualify 2218 extended attributes with the associated resource URN; e.g., the 2219 attribute 'age' defined in 'urn:scim:schemas:exampleCo:2.0:hr' is 2220 fully encoded as 'urn:scim:schemas:exampleCo:2.0:hr:age'. A Complex 2221 attributes' Sub-Attributes are referenced via nested, dot ('.') 2222 notation; i.e., {urn}:{Attribute name}.{Sub-Attribute name}. For 2223 example, the fully qualified path for a User's givenName is 2224 urn:scim:schemas:core:2.0:User:name.givenName All facets (URN, 2225 attribute and Sub-Attribute name) of the fully encoded Attribute name 2226 are case insensitive. 2228 3.9. "/Me" Authenticated Subject Alias 2230 A client MAY use a URL of the form "/Me" as a URI alias for 2231 the User or other resource associated with the currently 2232 authenticated subject for any SCIM operation. A service provider MAY 2233 respond in ONE of 3 ways: 2235 o A service provider that does NOT support this feature SHOULD 2236 respond with status 403 (FORBIDDEN). 2238 o A service provider MAY choose to redirect the client using HTTP 2239 status 308 to the resource associated with the authenticated 2240 subject. The client MAY then repeat the request at the indicated 2241 location. 2243 o A service provider MAY process the SCIM request directly. In any 2244 response, the HTTP "Location" header MUST be the permanent 2245 location of the aliased resource associated with the authenticated 2246 subject. 2248 3.10. HTTP Status and Error Response Handling 2250 The SCIM Protocol uses the HTTP status response status codes defined 2251 in Section 6 [RFC7231] to indicate operation success or failure. In 2252 addition to returning a HTTP response code implementers MUST return 2253 the errors in the body of the response in the client requested format 2254 containing the error response and, per the HTTP specification, human- 2255 readable explanations. Error responses are identified using the 2256 following "schema" URI: "urn:scim:api:messages:2.0:Error". The 2257 following attributes are defined for a SCIM error response using a 2258 JSON body: 2260 status 2261 The HTTP status code (see Section 6 [RFC7231]). REQUIRED 2263 scimType 2264 A SCIM detailed error keyword. See Table 8. OPTIONAL 2266 detail 2267 A detailed, human readable message. OPTIONAL 2269 Implementers SHOULD handle the identified HTTP status codes as 2270 described below. 2272 +--------------+---------------+------------------------------------+ 2273 | Status | Applicability | Suggested Explanation | 2274 +--------------+---------------+------------------------------------+ 2275 | 307 | GET, POST, | The client is directed to repeat | 2276 | TEMPORARY | PUT, PATCH, | the same HTTP request at the | 2277 | REDIRECT | DELETE | location identified. The client | 2278 | | | SHOULD NOT use the location | 2279 | | | provided in the response as a | 2280 | | | permanent reference to the | 2281 | | | resource and SHOULD continue to | 2282 | | | use the original request URI | 2283 | | | [RFC7231]. | 2284 | 308 | GET, POST, | The client is directed to repeat | 2285 | PERMANENT | PUT, PATCH, | the same HTTP request at the | 2286 | REDIRECT | DELETE | location identified. The client | 2287 | | | SHOULD use the location provided | 2288 | | | in the response as the permanent | 2289 | | | reference to the resource | 2290 | | | [I-D.reschke-http-status-308]. | 2291 | 400 BAD | GET, POST, | Request is unparseable, | 2292 | REQUEST | PUT, PATCH, | syntactically incorrect, or | 2293 | | DELETE | violates schema | 2294 | 401 | GET, POST, | Authorization failure | 2295 | UNAUTHORIZED | PUT, PATCH, | | 2296 | | DELETE | | 2297 | 403 | GET, POST, | Server does not support requested | 2298 | FORBIDDEN | PUT, PATCH, | operation | 2299 | | DELETE | | 2300 | 404 NOT | GET, PUT, | Specified resource (e.g., User) or | 2301 | FOUND | PATCH, DELETE | end-point, does not exist | 2302 | 409 CONFLICT | POST, PUT, | The specified version number does | 2303 | | PATCH, DELETE | not match the resource's latest | 2304 | | | version number or a service | 2305 | | | provider refused to create a new, | 2306 | | | duplicate resource | 2307 | 412 | PUT, PATCH,D | Failed to update as resource {id} | 2308 | PRECONDITION | ELETE | changed on the server last | 2309 | FAILED | | retrieved | 2310 | 413 REQUEST | POST | {"maxOperations": | 2311 | ENTITY TOO | | 1000,"maxPayload": 1048576} | 2312 | LARGE | | | 2313 | 500 INTERNAL | GET, POST, | An internal error. Implementers | 2314 | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive | 2315 | | DELETE | debugging advice | 2316 | 501 NOT | GET, POST, | Service Provider does not support | 2317 | IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH | 2318 | | DELETE | | 2319 +--------------+---------------+------------------------------------+ 2321 Table 7: SCIM HTTP Status Code Usage 2323 For HTTP Status 400 (Bad Request) responses, the following detail 2324 error types are defined: 2326 +--------------+------------------------------+---------------------+ 2327 | scimType | Description | Applicability | 2328 +--------------+------------------------------+---------------------+ 2329 | invalidFilte | The specified filter syntax | GET(Section 3.2.2), | 2330 | r | was invalid (does not comply | POST (Search - | 2331 | | with Figure 1) or the | Section 3.2.3), | 2332 | | specified attribute and | PATCH (Path Filter | 2333 | | filter comparison | - Section 3.3.2) | 2334 | | combination is not | | 2335 | | supported. | | 2336 | tooMany | The specified filter yields | GET(Section 3.2.2), | 2337 | | many more results than the | POST (Search - | 2338 | | server is willing calculate | Section 3.2.3) | 2339 | | or process. For example, a | | 2340 | | filter such as "(userName | | 2341 | | pr)" by itself would return | | 2342 | | all entries with a | | 2343 | | "userName" and MAY not be | | 2344 | | acceptable to the service | | 2345 | | provider. | | 2346 | uniqueness | One or more of attribute | POST (Create - | 2347 | | values is already in use or | Section 3.1), PUT | 2348 | | is reserved. | (Section 3.3.1), | 2349 | | | PATCH (Section | 2350 | | | 3.3.2) | 2351 | mutability | The attempted modification | PUT (Section | 2352 | | is not compatible with the | 3.3.1), PATCH | 2353 | | target attributes mutability | (Section 3.3.2) | 2354 | | or current state (e.g. | | 2355 | | modification of an immutable | | 2356 | | attribute with an existing | | 2357 | | value). | | 2358 | invalidSynta | The request body message | POST (Search - | 2359 | x | structure was invalid or did | Section 3.2.2, | 2360 | | not conform to the request | Create - Section | 2361 | | schema. | 3.1, Bulk - Section | 2362 | | | 3.5), PUT (Section | 2363 | | | 3.3.1) | 2364 | invalidPath | The path attribute was | PATCH (Section | 2365 | | invalid or malformed (see | 3.3.2) | 2366 | | Figure 5). | | 2367 | noTarget | The specified "path" did not | PATCH (Section | 2368 | | yield an attribute or | 3.3.2) | 2369 | | attribute value that could | | 2370 | | be operated on. This occurs | | 2371 | | when the specified "path" | | 2372 | | value contains a filter that | | 2373 | | yields no match. | | 2374 | invalidValue | A required value was | GET (Section | 2375 | | missing, or the value | 3.2.2), POST | 2376 | | specified was not compatible | (Create - Section | 2377 | | with the operation or | 3.1, Query - | 2378 | | attribute type (see Section | Section 3.2.2), PUT | 2379 | | 2.1 [I-D.ietf-scim-core-sche | (Section 3.3.1), | 2380 | | ma]). | PATCH (Section | 2381 | | | 3.3.2) | 2382 | invalidVers | The specified SCIM protocol | GET (Section | 2383 | | version is not supported | 3.2.2), POST (ALL), | 2384 | | (see Section 3.11). | PUT (Section | 2385 | | | 3.3.1), PATCH | 2386 | | | (Section 3.3.2), | 2387 | | | DELETE (Section | 2388 | | | 3.4) | 2389 +--------------+------------------------------+---------------------+ 2391 Table 8: Table of SCIM Detail Error Keyword Values 2393 Note that in the table above (Table 8), the applicability table 2394 applies to the normal HTTP method but MAY apply within a SCIM Bulk 2395 operation (via HTTP POST). 2397 Error example in response to a non-existent GET request. 2399 HTTP/1.1 404 NOT FOUND 2401 { 2402 "schemas": ["urn:scim:api:messages:2.0:Error"], 2403 "detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 2404 "status":"404 2405 } 2407 Error example in response to a PUT request. 2409 HTTP/1.1 400 BAD REQUEST 2411 { 2412 "schemas": ["urn:scim:api:messages:2.0:Error"], 2413 "scimType":"mutability" 2414 "detail":"Attribute 'id' is readOnly", 2415 "status":"400" 2416 } 2418 [[Editor's note: while the detail error codes seem to have consensus, 2419 there is a question about whether the error codes should be 2420 extensible so that individual service providers may define site 2421 specific codes. Should all scimTypes be URIs, so that scimTypes can 2422 be registered via IANA? Should there be a separate field defined for 2423 this purpose? Or, should custom signalling (for non-protocol/schema 2424 errors, be out of scope?]] 2426 3.11. API Versioning 2428 The Base URL MAY be appended with a version identifier as a separate 2429 segment in the URL path. At this time of this specification, the 2430 identifier is 'v2'. If specified, the version identifier MUST appear 2431 in the URL path immediately preceding the resource endpoint and 2432 conform to the following scheme: the character 'v' followed by the 2433 desired SCIM version number; e.g., a version 'v2' User request is 2434 specified as /v2/Users. When specified service providers MUST 2435 perform the operation using the desired version or reject the 2436 request. When omitted service providers SHOULD perform the operation 2437 using the most recent SCIM protocol version supported by the service 2438 provider. 2440 3.12. Versioning Resources 2442 The SCIM protocol supports resource versioning via standard HTTP 2443 ETags Section 2.3 [RFC7233]. Service providers MAY support weak 2444 ETags as the preferred mechanism for performing conditional 2445 retrievals and ensuring clients do not inadvertently overwrite each 2446 others changes, respectively. When supported SCIM ETags MUST be 2447 specified as an HTTP header and SHOULD be specified within the 2448 'version' attribute contained in the resource's 'meta' attribute. 2450 Example: 2452 POST /Users HTTP/1.1 2453 Host: example.com 2454 Content-Type: application/scim+json 2455 Authorization: Bearer h480djs93hd8 2456 Content-Length: ... 2458 { 2459 "schemas":["urn:scim:schemas:core:2.0:User"], 2460 "userName":"bjensen", 2461 "externalId":"bjensen", 2462 "name":{ 2463 "formatted":"Ms. Barbara J Jensen III", 2464 "familyName":"Jensen", 2465 "givenName":"Barbara" 2466 } 2467 } 2469 The server responds with an ETag in the response header and meta 2470 structure. 2472 HTTP/1.1 201 Created 2473 Content-Type: application/scim+json 2474 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2475 ETag: W/"e180ee84f0671b1" 2477 { 2478 "schemas":["urn:scim:schemas:core:2.0:User"], 2479 "id":"2819c223-7f76-453a-919d-413861904646", 2480 "meta":{ 2481 "resourceType":"User", 2482 "created":"2011-08-01T21:32:44.882Z", 2483 "lastModified":"2011-08-01T21:32:44.882Z", 2484 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2485 "version":"W\/\"e180ee84f0671b1\"" 2486 }, 2487 "name":{ 2488 "formatted":"Ms. Barbara J Jensen III", 2489 "familyName":"Jensen", 2490 "givenName":"Barbara" 2491 }, 2492 "userName":"bjensen" 2493 } 2495 With the returned ETag, clients MAY choose to retrieve the resource 2496 only if the resource has been modified. 2498 Conditional retrieval example using If-None-Match Section 3.2 2499 [RFC7233] header: 2501 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName 2502 Host: example.com 2503 Accept: application/scim+json 2504 Authorization: Bearer h480djs93hd8 2505 If-None-Match: W/"e180ee84f0671b1" 2507 If the resource has not changed the service provider simply returns 2508 an empty body with a 304 "Not Modified" response code. 2510 If the service providers supports versioning of resources the client 2511 MAY supply an If-Match Section 3.1 [RFC7233] header for PUT and PATCH 2512 operations to ensure that the requested operation succeeds only if 2513 the supplied ETag matches the latest service provider resource; e.g., 2514 If-Match: W/"e180ee84f0671b1" 2516 4. Preparation and Comparison of Internationalized Strings 2518 To increase the likelihood that the input and comparison of unicode 2519 usernames and passwords will work in ways that make sense for typical 2520 users throughout the world there are special string preparation and 2521 comparison methods (PRECIS) that MUST be followed for usernames and 2522 passwords. Before comparing or evaluating uniqueness of a "userName" 2523 or "password" attribute, service providers MUST use the "PRECIS" 2524 profile described in Sections 4 and 5 respectively of 2525 [I-D.ietf-precis-saslprepbis] and is based on the "PRECIS" framework 2526 specification [I-D.ietf-precis-framework]. 2528 5. Multi-Tenancy 2530 A single service provider may expose the SCIM protocol to multiple 2531 clients. Depending on the nature of the service, the clients may 2532 have authority to access and alter resources initially created by 2533 other clients. Alternatively, clients may expect to access disjoint 2534 sets of resources, and may expect that their resources are 2535 inaccessible by other clients. These scenarios are called "multi- 2536 tenancy", where each client is understood to be or represent a 2537 "tenant" of the service provider. Clients may also be multi- 2538 tenanted. 2540 The following common cases may occur: 2542 1. All clients share all resources (no tenancy) 2544 2. Each single client creates and accesses a private subset of 2545 resources (1 client:1 Tenant) 2547 3. Sets of clients share sets of resources (M clients:1 Tenant) 2548 4. One client to Multiple Tenants (1 client:M Tenants) 2550 Service providers may implement any subset of the above cases. 2552 Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a 2553 scheme for multi-tenancy. 2555 The SCIM protocol does not prescribe the mechanisms whereby clients 2556 and service providers interact for: 2558 o Registering or provisioning Tenants 2560 o Associating a subset of clients with a subset of the Tenants 2562 o Indicating which tenant is associated with the data in a request 2563 or response, or indicating which Tenant is the subject of a query 2565 5.1. Associating Clients to Tenants 2567 The service provider MAY use the authentication mechanism (Section 2) 2568 to determine the identity of the client, and thus infer the 2569 associated Tenant. 2571 For implementations where a client is associated with more than one 2572 Tenant, the service provider MAY use one of the following methods for 2573 explicit specification of the Tenant. 2575 If any of these methods of allowing the client to explicitly specify 2576 the Tenant are employed, the service provider should ensure that 2577 access controls are in place to prevent or allow cross-tenant use 2578 cases. 2580 The service provider should consider precedence in cases where a 2581 client may explicitly specify a Tenant while being implicitly 2582 associated with a different Tenant. 2584 In all of these methods, the {tenant_id} is a unique identifier for 2585 the Tenant as defined by the service provider. 2587 o A URL prefix: "https://www.example.com/Tenants/{tenant_id}/v2/ 2588 Users" 2590 o A sub-domain: "https://{tenant_id}.example.com/v2/Groups" 2592 o The service provider may recognize a {tenant_id} provided by the 2593 client in an HTTP Header as the indicator of the desired target 2594 Tenant. 2596 5.2. SCIM Identifiers with Multiple Tenants 2598 Considerations for a Multi-Tenant Implementation: 2600 The service provider may choose to implement SCIM ids which are 2601 unique across all resources for all Tenants, but this is not 2602 required. 2604 The externalId, defined by the client, is required to be unique ONLY 2605 within the resources associated with the associated Tenant. 2607 6. Security Considerations 2609 6.1. TLS Support 2611 The SCIM Protocol layers on top of Hypertext Transfer Protocol and 2612 thus subject to the security considerations of HTTP Section 9 2613 [RFC7230] and its related specifications. 2615 SCIM resources (e.g., Users and Groups) can contain sensitive 2616 information. Therefore, SCIM clients and service providers MUST 2617 implement TLS. Which version(s) ought to be implemented will vary 2618 over time, and depend on the widespread deployment and known security 2619 vulnerabilities at the time of implementation. At the time of this 2620 writing, TLS version 1.2 [RFC5246] is the most recent version, but 2621 has very limited actual deployment, and might not be readily 2622 available in implementation toolkits. TLS version 1.0 [RFC2246] is 2623 the most widely deployed version, and will give the broadest 2624 interoperability. 2626 6.2. Disclosure of Sensitive Information in URIs 2628 As mentioned in ,Section 9.4 [RFC7231], SCIM clients requesting 2629 information using query filters using HTTP GET SHOULD give 2630 consideration to the information content of the filters and whether 2631 their exposure in a URI would represent a breach of security or 2632 confidentiality through leakage in a web browsers or server logs. 2633 This is particularly true for information that is legally considered 2634 "personally identifiable information" or is otherwise restricted by 2635 privacy laws. In these situations to ensure maximum security and 2636 confidentiality, clients SHOULD query using HTTP POST (see 2637 Section 3.2.3 ). 2639 Servers that receive HTTP GET requests using filters that contain 2640 restricted or confidential information SHOULD respond with HTTP 2641 status 403 indicating the operation is FORBIDDEN. A detailed error, 2642 "confidential_restricted" may be returned indicating the request must 2643 be submitted using POST. A non-normative example: 2645 HTTP/1.1 403 FORBIDDEN 2647 { 2648 "schemas": ["urn:scim:api:messages:2.0:Error"], 2649 "Errors":[ 2650 { 2651 "description":"Query filter involving 'name' is restricted or confidential", 2652 "error":"confidential_restricted" 2653 } 2654 ] 2655 } 2657 6.3. HTTP Considerations 2659 As an HTTP based protocol, implementers of SCIM SHOULD consider all 2660 security considerations of the HTTP/1.1 as enumerated in Section 1 2661 [RFC7230] 2663 As stated in Section 2.7.1 [RFC7230], a SCIM client MUST NOT generate 2664 the userinfo (i.e. username and password) component (and its "@" 2665 delimiter) when an "http" URI reference is generated with a message 2666 as they are now disallowed in HTTP. 2668 6.4. Secure Storage and Handling of Sensitive Data 2670 An attacker may obtain valid username/password combinations from the 2671 SCIM service provider's underlying database by gaining access to the 2672 database and/or launching injection attacks. This could lead to 2673 unintended disclosure of username/password combinations. The impact 2674 may extend beyond the domain of the SCIM service provider if the data 2675 was provisioned from other domains. 2677 Administrators should undertake industry best practices to protect 2678 the storage of credentials and in particular SHOULD follow 2679 recommendations outlines in Section 5.1.4.1 [RFC6819]. These 2680 recommendations include but are not limited to: 2682 o Provide injection attack counter measures (e.g. by validating all 2683 inputs and parameters), 2685 o No cleartext storage of credentials, 2687 o Store credentials using an encrypted protection mechanism, and 2689 o Avoid passwords and consider use of asymmetric cryptography based 2690 credentials. 2692 As outlined in Section 5.1.4.2 [RFC6819], adminitrators SHOULD take 2693 counter measures to prevent online attacks on secrets such as: 2695 o Utilize secure password policy in order to increase user password 2696 entrophy to hinder online attacks and password guessing, 2698 o Mitigate attacks on passwords by locking respective accounts have 2699 a number of failed attempts, 2701 o Use "tar pit" techniques by temporarily locking a respective 2702 account and delaying responses for a certain duration. The 2703 duration may increase with the number of failed attempts, and 2705 o Use authentication system that use CAPTCHA's and other factors for 2706 authenticating users further reducing the possibility of automated 2707 attacks. 2709 6.5. Case Insensitive Comparision & International Languages 2711 When comparing unicode strings such as in query filters or testing 2712 for uniqueness of usernames and passwords, strings MUST be 2713 appopriately prepared before comparison. See Section 4. 2715 7. IANA Considerations 2717 7.1. Media Type Registration 2719 To: ietf-types@iana.org 2721 Subject: Registration of media type application/scim+json 2723 Type name: application 2725 Subtype name: scim+json 2727 Required parameters: none 2729 Optional parameters: none 2731 Encoding considerations: 8bit 2733 Security considerations: See Section 6 2735 Interoperability considerations: The "application/scim+json" media 2736 type is intended to identify JSON structure data that conforms to 2737 the SCIM protocol and schema specifications. Older versions of 2738 SCIM are known to informally use "application/json". 2740 Published specification: [[this document]] 2742 Applications that use this media type: It is expected that 2743 applications that use this type may be special purpose 2744 applications intended for inter-domain provisioning. Clients may 2745 also be applications (e.g. mobile applications) that need to use 2746 SCIM for self-registration of user accounts. SCIM services may be 2747 offered by web applications that offer support for standards based 2748 provisioning or may be a dedicated SCIM service provider such as a 2749 "cloud directory". Content may be treated as equivalent to 2750 "application/json" type for the purpose of displaying in web 2751 browsers. 2753 Additional information: 2755 Magic number(s): 2757 File extension(s): .scim .scm 2759 Macintosh file type code(s): 2761 Person & email address to contact for futher information: SCIM 2762 mailing list "" 2764 Intended usage: COMMON* (see restrictions) 2766 Restrictions on usage: For most client types, it is sufficient to 2767 recognize the content as equivalent to "application/json". 2768 Applications intending to use SCIM protocol SHOULD use the 2769 application/scim+json media type. 2771 Author: Phil Hunt 2773 Change controller: IETF 2775 7.2. SCIM API Message Schema Registry 2777 As per the IANA SCIM Schema Registry in [I-D.ietf-scim-core-schema], 2778 the following registers and extends the SCIM Schema Registry to 2779 define SCIM protocol request/response JSON schema URN identifier 2780 prefix of "urn:scim:api:messages:2.0" which is part of the URN sub- 2781 Namespace for SCIM. There is no specific associated resource type. 2783 +---------------------------------------+-----------+---------------+ 2784 | Schema URI | Name | Reference | 2785 +---------------------------------------+-----------+---------------+ 2786 | urn:scim:api:messages:2.0:ListRespons | List/Quer | See Section | 2787 | e | y | 3.2.2 | 2788 | | Response | | 2789 | urn:scim:api:messages:2.0:SearchReque | POST | See Section | 2790 | st | Query | 3.2.3 | 2791 | | Request | | 2792 | urn:scim:api:messages:2.0:PatchOp | Patch | See Section | 2793 | | Operation | 3.3.2 | 2794 | urn:scim:api:messages:2.0:BulkRequest | Bulk Oper | See Section | 2795 | | ations | 3.5 | 2796 | | Request | | 2797 | urn:scim:api:messages:2.0:BulkRespons | Bulk Oper | See Section | 2798 | e | ations | 3.5 | 2799 | | Response | | 2800 | urn:scim:api:messages:2.0:Error | Error | See Section | 2801 | | Response | 3.10 | 2802 +---------------------------------------+-----------+---------------+ 2804 SCIM Schema URIs for Data Resources 2806 8. References 2808 8.1. Normative References 2810 [I-D.ietf-precis-saslprepbis] 2811 Saint-Andre, P. and A. Melnikov, "Preparation and 2812 Comparison of Internationalized Strings Representing 2813 Usernames and Passwords", draft-ietf-precis-saslprepbis-07 2814 (work in progress), March 2014. 2816 [I-D.ietf-scim-core-schema] 2817 Grizzle, K., Hunt, P., Wahlstroem, E., and C. Mortimore, 2818 "System for Cross-Domain Identity Management: Core 2819 Schema", draft-ietf-scim-core-schema-06 (work in 2820 progress), June 2014. 2822 [IANA.Language] 2823 Internet Assigned Numbers Authority (IANA), "Language 2824 Subtag Registry", 2005. 2826 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2827 Requirement Levels", BCP 14, RFC 2119, March 1997. 2829 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2830 RFC 2246, January 1999. 2832 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2833 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2834 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2836 [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of 2837 Internationalized Strings ("stringprep")", RFC 3454, 2838 December 2002. 2840 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2841 10646", STD 63, RFC 3629, November 2003. 2843 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2844 Resource Identifier (URI): Generic Syntax", STD 66, RFC 2845 3986, January 2005. 2847 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2848 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2850 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2851 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2853 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 2854 5789, March 2010. 2856 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 2857 Interchange Format", RFC 7159, March 2014. 2859 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2860 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 2861 2014. 2863 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2864 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 2866 [RFC7233] Fielding, R., Lafon, Y., and J. Reschke, "Hypertext 2867 Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, 2868 June 2014. 2870 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2871 (HTTP/1.1): Authentication", RFC 7235, June 2014. 2873 8.2. Informative References 2875 [I-D.ietf-precis-framework] 2876 Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 2877 Preparation and Comparison of Internationalized Strings in 2878 Application Protocols", draft-ietf-precis-framework-17 2879 (work in progress), May 2014. 2881 [I-D.reschke-http-status-308] 2882 Reschke, J., "The Hypertext Transfer Protocol (HTTP) 2883 Status Code 308 (Permanent Redirect)", draft-reschke-http- 2884 status-308-07 (work in progress), March 2012. 2886 [OpenSearch] 2887 Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . 2889 [Order-Operations] 2890 Wikipedia, "Order of Operations: Programming Languages", . 2892 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 2893 Languages", BCP 18, RFC 2277, January 1998. 2895 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 2896 Framework: Bearer Token Usage", RFC 6750, October 2012. 2898 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 2899 Threat Model and Security Considerations", RFC 6819, 2900 January 2013. 2902 [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation 2903 (JSON) Patch", RFC 6902, April 2013. 2905 Appendix A. Contributors 2907 Samuel Erdtman (samuel@erdtman.se) 2909 Patrick Harding (pharding@pingidentity.com) 2911 Appendix B. Acknowledgments 2913 The editors would like to acknowledge the contribution and work of 2914 the past draft editors: 2916 Trey Drake, UnboundID 2918 Chuck Mortimore, Salesforce 2920 The editor would like to thank the participants in the the SCIM 2921 working group for their support of this specification. 2923 Appendix C. Change Log 2925 [[This section to be removed prior to publication as an RFC]] 2927 Draft 02 - KG - Addition of schema extensibility 2928 Draft 03 - PH - Revisions based on following tickets: 2930 24 - Add filter negation 2932 39 - Clarification on response for DELETE 2934 42 - Make root searches optional 2936 49 - Add "ew" filter 2938 50 - Filters for multi-valued complex attributes 2940 51 - Search by Schema 2942 53 - Standard use of term client (some was consumer) 2944 55 - Redirect support (3xx) 2946 56 - Make manager attribute consistent with other $ref attrs 2948 57 - Update all "/v1" examples to '/v2" 2950 59 - Fix capitalization per IETF editor practices 2952 60 - Changed tags to normal and tags 2954 Draft 04 - PH - Revisions based on the following tickets: 2956 18 - New PATCH command based on JSON Patch (RFC6902) 2958 - Provided ABNF specification for filters (used in PATCH) 2960 - Updated references to RFC4627 to RFC7159 2962 Draft 05 - PH - Revisions based on the following tickets: 2964 03 - Support for excludedAttributes parameter 2966 13 - Change client use of Etags from MUST to MAY (correction) 2968 23 - Clarifications regarding case exact processing. 2970 41 - Add IANA considerations 2972 65 - Removed X-HTTP-Method-Override support 2974 69 - Added clarifications to intro to align with draft-nottingham- 2975 uri-get-off-my-lawn 2976 70 - Remove SCIM_TENANT_ID header 2978 72 - Added text to indicate UTF-8 is default and mandatory 2979 encoding format per BCP18 2981 74 - Added security considerations for using GET with confidential 2982 attribute filters 2984 - corrected error response in JSON PATCH operation 2986 Draft 06 - PH - Revisions based on the following tickets and 2987 editorial changes 2989 41 - Revised content types from application/json to application/ 2990 scim+json, registered API schemas 2992 63 - Revised uri schema prefixes for API json message schemas 2994 66 - Updated references for RFC2616 to HTTPbis 2996 75 - Added security considerations for International Strings and 2997 "PRECIS" support 2999 76 - Clarified handling of PUT (& POST) with regards to mutability 3000 and default values 3002 - Corrected version numbers in sec 3.11 API Versioning to v2 (from 3003 v1) 3005 - Clarified that no filter matches should return success 3006 totalResults=0 3008 Draft 07 - PH - Revisions regarding support of detailed errors 3009 (Tickets 37, 46, 67) 3011 Draft 08 - PH - Revisions as follows 3013 - Added clarification on schemas handling during PATCH operation 3015 - Revised example URN in Attribute Notation section to comply with 3016 IANA namespace rules 3018 - Fixed typo in ABNF, attrExpr should be attrExp 3020 - Added more security considerations for HTTP and sensitive data 3022 - Revised authentication and authorization sections for greater 3023 clarity. 3025 - Replaced the word "search" with "query" for consistency 3027 - Clarified sucessful resource creation response 3029 - Added clarification on primary value handling in PATCH 3030 (consistent with draft 03) 3032 - Revised SCIM Bullk error handling to conform with draft 07 error 3033 handling 3035 Authors' Addresses 3037 Phil Hunt (editor) 3038 Oracle Corporation 3040 Email: phil.hunt@yahoo.com 3042 Kelly Grizzle 3043 SailPoint 3045 Email: kelly.grizzle@sailpoint.com 3047 Morteza Ansari 3048 Cisco 3050 Email: morteza.ansari@cisco.com 3052 Erik Wahlstroem 3053 Technology Nexus 3055 Email: erik.wahlstrom@nexusgroup.com 3057 Chuck Mortimore 3058 Salesforce.com 3060 Email: cmortimore@salesforce.com