idnits 2.17.1 draft-ietf-scim-api-01.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: ---------------------------------------------------------------------------- == It seems as if not all pages are separated by form feeds - found 0 form feeds but 53 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 41 instances of too long lines in the document, the longest one being 28 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: +------------+-------------------+----------------------------------+ | Parameter | Description | Default | +------------+-------------------+----------------------------------+ | startIndex | The 1-based index | 1 | | | of the first | | | | search result. | | | count | Non-negative | None. When specified the | | | Integer. | Service Provider MUST not return | | | Specifies the | more results than specified | | | desired maximum | though MAY return fewer results. | | | number of search | If unspecified, the maximum | | | results per page; | number of results is set by the | | | e.g., 10. | Service Provider. | +------------+-------------------+----------------------------------+ == 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: Consumers request Resource removal via DELETE. Service Providers MAY choose not to permanently delete the Resource, but MUST return a 404 error code for all operations associated with the previously deleted Id. Service Providers MUST also omit the Resource from future query results. In addition the Service Provider MUST not consider the deleted resource in conflict calculation. For example if a User resource is deleted, a CREATE request for a User resource with the same userName as the previously deleted resource should not fail with a 409 error due to userName conflict. -- The document date (April 15, 2013) is 4028 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) -- Missing reference section? 'RFC2119' on line 122 looks like a reference -- Missing reference section? '1' on line 142 looks like a reference -- Missing reference section? '2' on line 441 looks like a reference -- Missing reference section? '3' on line 626 looks like a reference -- Missing reference section? '4' on line 763 looks like a reference -- Missing reference section? '5' on line 1825 looks like a reference -- Missing reference section? '6' on line 1896 looks like a reference -- Missing reference section? 'RFC2616' on line 2148 looks like a reference Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Drake, Ed. 3 Internet-Draft UnboundID 4 Intended status: Standards Track C. Mortimore 5 Expires: October 17, 2013 SalesForce 6 M. Ansari 7 Cisco 8 K. Grizzle 9 SailPoint 10 E. Wahlstroem 11 Technology Nexus 12 April 15, 2013 14 System for Cross-Domain Identity Management:Protocol 15 draft-ietf-scim-api-01 17 Abstract 19 The System for Cross-Domain Identity Management (SCIM) specification 20 is designed to make managing user identity in cloud based 21 applications and services easier. The specification suite seeks to 22 build upon experience with existing schemas and deployments, placing 23 specific emphasis on simplicity of development and integration, while 24 applying existing authentication, authorization, and privacy models. 25 It's intent is to reduce the cost and complexity of user management 26 operations by providing a common user schema and extension model, as 27 well as binding documents to provide patterns for exchanging this 28 schema using standard protocols. In essence, make it fast, cheap, 29 and easy to move users in to, out of, and around the cloud. 31 Status of this Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on October 17, 2013. 48 Copyright Notice 49 Copyright (c) 2013 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4 65 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 4 66 1.2. Notational Conventions . . . . . . . . . . . . . . . . . . 4 67 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 68 2. Authentication and Authorization . . . . . . . . . . . . . . . 4 69 3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 70 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . . 7 71 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . . 8 72 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . . 8 73 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 8 74 3.2.2. List/Query Resources . . . . . . . . . . . . . . . . . 10 75 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . . 17 76 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 19 77 3.3.1. Modifying with PUT . . . . . . . . . . . . . . . . . . 19 78 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . . 21 79 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . . 29 80 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 81 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 45 82 3.7. Additional retrieval query parameters . . . . . . . . . . 45 83 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . . 46 84 3.9. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 46 85 3.10. API Versioning . . . . . . . . . . . . . . . . . . . . . . 48 86 3.11. Versioning Resources . . . . . . . . . . . . . . . . . . . 48 87 3.12. HTTP Method Overloading . . . . . . . . . . . . . . . . . 50 88 4. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 50 89 4.1. Associating Consumers to Tenants . . . . . . . . . . . . . 51 90 4.1.1. URL Prefix Example . . . . . . . . . . . . . . . . . . 51 91 4.1.2. Subdomain Example . . . . . . . . . . . . . . . . . . 52 92 4.1.3. HTTP Header . . . . . . . . . . . . . . . . . . . . . 52 93 4.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . . 52 94 5. Security Considerations . . . . . . . . . . . . . . . . . . . 52 95 6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 52 96 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 53 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 53 99 1. Introduction and Overview 101 The SCIM Protocol is an application-level, REST protocol for 102 provisioning and managing identity data on the web. The protocol 103 supports creation, modification, retrieval, and discovery of core 104 identity Resources; i.e., Users and Groups, as well as custom 105 Resource extensions. 107 1.1. Intended Audience 109 This document is intended as a guide to SCIM API usage for both 110 identity Service Providers and Consumers. 112 1.2. Notational Conventions 114 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 115 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 116 document are to be interpreted as described in [RFC2119]. These 117 keywords are capitalized when used to unambiguously specify 118 requirements of the protocol or application features and behavior 119 that affect the interoperability and security of implementations. 120 When these words are not capitalized, they are meant in their 121 natural-language sense. 123 For purposes of readability examples are not URL encoded. 124 Implementers MUST percent encode URLs as described in RFC3896 2.1. 126 1.3. Definitions 128 Base URL: The SCIM REST API is always relative to a Base URL. The 129 Base URL MUST NOT contain a query string as Consumers may append 130 additional path information and query parameters as part of 131 forming the request. Example: https://example.com/scim/v1/ 133 2. Authentication and Authorization 135 The SCIM protocol does not define a scheme for authentication and 136 authorization therefore implementers are free to choose mechanisms 137 appropriate to their use cases. The choice of authentication 138 mechanism will impact interoperability. It is RECOMMENDED that 139 clients be implemented in such a way that new authentication schemes 140 can be deployed. Implementers SHOULD support existing 141 authentication/authorization schemes. In particular, OAuth2 Bearer 142 Token [1] is RECOMMENDED. Appropriate security considerations of the 143 selected authentication and authorization schemes SHOULD be taken. 144 Because this protocol uses HTTP response status codes as the primary 145 means of reporting the result of a request, servers are advised to 146 respond to unauthorized or unauthenticated requests using the 401 147 response code in accordance with section 10.4.2 of RFC2616. 149 All examples assume OAuth2 bearer token; e.g., 151 GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 152 Host: example.com 153 Authorization: Bearer h480djs93hd8 155 The context of the request (i.e. the user for whom data is being 156 requested) MUST be inferred by Service Providers. 158 3. API 160 The SCIM protocol specifies well known endpoints and HTTP methods for 161 managing Resources defined in the core schema; i.e., User and Group 162 Resources correspond to /Users and /Groups respectively. Service 163 Providers that support extended Resources SHOULD define Resource 164 endpoints using the established convention; pluralize the Resource 165 name defined in the extended schema by appending an 's'. Given there 166 are cases where Resource pluralization is ambiguous; e.g., a Resource 167 named 'person' is legitimately 'persons' and 'people' Consumers 168 SHOULD discover Resource endpoints via the Schema Sub-Attribute 169 'endpoint'. 171 GET Retrieves a complete or partial Resource. 173 POST Create new Resource, perform an extended Search, or bulk modify 174 Resources. 176 PUT Modifies a Resource with a complete, Consumer specified Resource 177 (replace). 179 PATCH Modifies a Resource with a set of Consumer specified changes 180 (partial update). 182 DELETE Deletes a Resource. 184 +------------+--------------------+---------------+-----------------+ 185 | Resource | Endpoint | Operations | Description | 186 +------------+--------------------+---------------+-----------------+ 187 | User | /Users | GET | Retrieve/Add/Mo | 188 | | | (Section 3.2. | dify Users | 189 | | | 1), POST | | 190 | | | (Section 3.1 | | 191 | | | ),PUT | | 192 | | | (Section 3. | | 193 | | | 3.1), PATCH | | 194 | | | (Section 3 | | 195 | | | .3.2), DELETE | | 196 | | | (Section | | 197 | | | 3.4) | | 198 | Group | /Groups | GET | Retrieve/Add/Mo | 199 | | | (Section 3.2. | dify Groups | 200 | | | 1), POST | | 201 | | | (Section 3.1 | | 202 | | | ),PUT | | 203 | | | (Section 3. | | 204 | | | 3.1), PATCH | | 205 | | | (Section 3 | | 206 | | | .3.2), DELETE | | 207 | | | (Section | | 208 | | | 3.4) | | 209 | Service | /ServiceProviderCo | GET | Retrieve the | 210 | Provider | nfigs | (Section 3.2. | Service | 211 | Configurat | | 1) | Provider's | 212 | ion | | | Configuration | 213 | Schema | /Schemas | GET | Retrieve a | 214 | | | (Section 3.2. | Resource's | 215 | | | 1) | Schema | 216 | Bulk | /Bulk | POST | Bulk modify | 217 | | | (Section 3.5) | Resources | 218 | Search | [prefix]/.search | POST | Perform a | 219 | | | (Section 3.2. | search at | 220 | | | 3) | system root or | 221 | | | | within a | 222 | | | | resource | 223 | | | | endpoint for | 224 | | | | one or more | 225 | | | | resource types | 226 | | | | using POST. | 227 +------------+--------------------+---------------+-----------------+ 229 Table 1: Defined endpoints 231 All requests to the Service Provider are made via HTTP operations on 232 a URL derived from the Base URL. Responses are returned in the body 233 of the HTTP response, formatted as JSON. Response and error codes 234 SHOULD be transmitted via the HTTP status code of the response (if 235 possible), and SHOULD also be specified in the body of the response. 237 3.1. Creating Resources 239 To create new Resources, clients send POST requests to the Resource 240 endpoint; i.e., /Users or /Groups. 242 Successful Resource creation is indicated with a 201 ("Created") 243 response code. Upon successful creation, the response body MUST 244 contain the newly created Resource. Since the server is free to 245 alter and/or ignore POSTed content, returning the full representation 246 can be useful to the client, enabling it to correlate the client and 247 server views of the new Resource. When a Resource is created, its 248 URI must be returned in the response Location header. 250 If the Service Provider determines creation of the requested Resource 251 conflicts with existing resources; e.g., a User Resource with a 252 duplicate userName, the Service Provider MUST return a 409 error and 253 SHOULD indicate the conflicting attribute(s) in the body of the 254 response. 256 Below, the client sends a POST request containing a User 258 POST /Users HTTP/1.1 259 Host: example.com 260 Accept: application/json 261 Content-Type: application/json 262 Authorization: Bearer h480djs93hd8 263 Content-Length: ... 265 { 266 "schemas":["urn:scim:schemas:core:1.0"], 267 "userName":"bjensen", 268 "externalId":"bjensen", 269 "name":{ 270 "formatted":"Ms. Barbara J Jensen III", 271 "familyName":"Jensen", 272 "givenName":"Barbara" 273 } 274 } 276 The server signals a successful creation with a status code of 201. 277 The response includes a Location header indicating the User URI, and 278 a representation of that User in the body of the response. 280 HTTP/1.1 201 Created 281 Content-Type: application/json 282 Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646 283 ETag: W/"e180ee84f0671b1" 285 { 286 "schemas":["urn:scim:schemas:core:1.0"], 287 "id":"2819c223-7f76-453a-919d-413861904646", 288 "externalId":"bjensen", 289 "meta":{ 290 "resourceType":"User", 291 "created":"2011-08-01T21:32:44.882Z", 292 "lastModified":"2011-08-01T21:32:44.882Z", 293 "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", 294 "version":"W\/\"e180ee84f0671b1\"" 295 }, 296 "name":{ 297 "formatted":"Ms. Barbara J Jensen III", 298 "familyName":"Jensen", 299 "givenName":"Barbara" 300 }, 301 "userName":"bjensen" 302 } 304 3.1.1. Resource Types 306 When adding a resource to a specific endpoint, the meta attribute 307 "resourceType" SHALL be set by the Service Provider to the 308 corresponding resource type for the endpoint and any extension types. 309 For example, "/Users" will set "resourceType" to "User", and 310 "/Groups" will set "resourceType" to "Group". 312 [TBD: For extended resource types, the "resourceType" attribute SHALL 313 be set by the Service Provider to have multiple values including the 314 base type plus any extneded types (e.g. 'User' and 'Employee').] 316 3.2. Retrieving Resources 318 Users and Group Resources are retrieved via opaque, unique URLs or 319 via Query. Service Providers MAY choose to respond with a sub-set of 320 Resource attributes, though MUST minimally return the Resource id and 321 meta attributes. 323 3.2.1. Retrieving a known Resource 325 To retrieve a known Resource, clients send GET requests to the 326 Resource endpoint; e.g., /Users/{id} or /Groups/{id}. 328 If the Resource exists the server responds with a status code of 200 329 and includes the result in the body of the response. 331 The below example retrieves a single User via the /Users endpoint. 333 GET /Users/2819c223-7f76-453a-919d-413861904646 334 Host: example.com 335 Accept: application/json 336 Authorization: Bearer h480djs93hd8 338 The server responds with: 340 HTTP/1.1 200 OK 341 Content-Type: application/json 342 Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646 343 ETag: W/"f250dd84f0671c3" 345 { 346 "schemas":["urn:scim:schemas:core:1.0"], 347 "id":"2819c223-7f76-453a-919d-413861904646, 348 "externalId":"bjensen", 349 "meta":{ 350 "resourceType":"User", 351 "created":"2011-08-01T18:29:49.793Z", 352 "lastModified":"2011-08-01T18:29:49.793Z", 353 "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", 354 "version":"W\/\"f250dd84f0671c3\"" 355 }, 356 "name":{ 357 "formatted":"Ms. Barbara J Jensen III", 358 "familyName":"Jensen", 359 "givenName":"Barbara" 360 }, 361 "userName":"bjensen", 362 "phoneNumbers":[ 363 { 364 "value":"555-555-8377", 365 "type":"work" 366 } 367 ], 368 "emails":[ 369 { 370 "value":"bjensen@example.com", 371 "type":"work" 372 } 373 ] 374 } 376 3.2.2. List/Query Resources 378 SCIM defines a standard set of operations that can be used to filter, 379 sort, and paginate response results. The operations are specified by 380 adding query parameters to the Resource's endpoint. Service 381 Providers MAY support additional query parameters not specified here, 382 and Providers SHOULD ignore any query parameters they don't 383 recognize. 385 The below example returns the userName for all Users: 387 GET /Users?attributes=userName 388 Host: example.com 389 Accept: application/json 390 Authorization: Bearer h480djs93hd8 392 HTTP/1.1 200 OK 393 Content-Type: application/json 395 { 396 "totalResults":2, 397 "schemas":["urn:scim:schemas:core:1.0"], 398 "Resources":[ 399 { 400 "userName":"bjensen" 401 }, 402 { 403 "userName":"jsmith" 404 } 405 ] 406 } 408 3.2.2.1. Query Endpoints 410 Queries MAY be performed against a SCIM: 412 Resource (e.g. /Users/{userid}), 414 Resource Type endpoint (e.g. /Users or /Groups), or 416 Server Root (e.g. /). 418 A search against a server root indicates that ALL resources within 419 the server SHALL be included subject to filtering. For example, a 420 filter against 'resourceType' could be used to restrict results to 421 one or more specific resource types. 423 When processing search operations across endpoints that include more 424 than one SCIM resource type (e.g. a search from the server root 425 endpoint), filters MUST be processed in the same fashion as outlined 426 in Section 3.2.2.2. For filtered attributes that are not part of a 427 particular resource type, the service provider SHALL treat the 428 attribute as if there is no attribute value. For example, a presence 429 or equality filter for an undefined attribute evaluates as FALSE. 431 3.2.2.2. Filtering 433 Filtering is OPTIONAL. Consumers may request a subset of Resources 434 by specifying the 'filter' URL query parameter containing a filter 435 expression. When specified only those Resources matching the filter 436 expression SHALL be returned. The expression language that is used 437 in the filter parameter supports references to attributes and 438 literals. The literal values can be strings enclosed in double 439 quotes, numbers, date times enclosed in double quotes, and Boolean 440 values; i.e., true or false. String literals MUST be valid JSON 441 strings [2]. 443 The attribute name and attribute operator are case insensitive. For 444 example, the following two expressions will evaluate to the same 445 logical value: 447 filter=userName Eq "john" 449 filter=Username eq "john" 451 The filter parameter MUST contain at least one valid Boolean 452 expression. Each expression MUST contain an attribute name followed 453 by an attribute operator and optional value. Multiple expressions 454 MAY be combined using the two logical operators. Furthermore 455 expressions can be grouped together using "()". 457 The operators supported in the expression are listed in the following 458 table. 460 +----------+-------------+------------------------------------------+ 461 | Operator | Description | Behavior | 462 +----------+-------------+------------------------------------------+ 463 | eq | equal | The attribute and operator values must | 464 | | | be identical for a match. | 465 | co | contains | The entire operator value must be a | 466 | | | substring of the attribute value for a | 467 | | | match. | 468 | sw | starts with | The entire operator value must be a | 469 | | | substring of the attribute value, | 470 | | | starting at the beginning of the | 471 | | | attribute value. This criterion is | 472 | | | satisfied if the two strings are | 473 | | | identical. | 474 | pr | present | If the attribute has a non-empty value, | 475 | | (has value) | or if it contains a non-empty node for | 476 | | | complex attributes there is a match. | 477 | gt | greater | If the attribute value is greater than | 478 | | than | operator value, there is a match. The | 479 | | | actual comparison is dependent on the | 480 | | | attribute type. For string attribute | 481 | | | types, this is a lexicographical | 482 | | | comparison and for DateTime types, it is | 483 | | | a chronological comparison. | 484 | ge | greater | If the attribute value is greater than | 485 | | than or | or equal to the operator value, there is | 486 | | equal | a match. The actual comparison is | 487 | | | dependent on the attribute type. For | 488 | | | string attribute types, this is a | 489 | | | lexicographical comparison and for | 490 | | | DateTime types, it is a chronological | 491 | | | comparison. | 492 | lt | less than | If the attribute value is less than | 493 | | | operator value, there is a match. The | 494 | | | actual comparison is dependent on the | 495 | | | attribute type. For string attribute | 496 | | | types, this is a lexicographical | 497 | | | comparison and for DateTime types, it is | 498 | | | a chronological comparison. | 499 | le | less than | If the attribute value is less than or | 500 | | or equal | equal to the operator value, there is a | 501 | | | match. The actual comparison is | 502 | | | dependent on the attribute type. For | 503 | | | string attribute types, this is a | 504 | | | lexicographical comparison and for | 505 | | | DateTime types, it is a chronological | 506 | | | comparison. | 507 +----------+-------------+------------------------------------------+ 509 Table 2: Attribute Operators 511 +----------+-------------+------------------------------------------+ 512 | Operator | Description | Behavior | 513 +----------+-------------+------------------------------------------+ 514 | and | Logical And | The filter is only a match if both | 515 | | | expressions evaluate to true. | 516 | or | Logical or | The filter is a match if either | 517 | | | expression evaluates to true. | 518 +----------+-------------+------------------------------------------+ 520 Table 3: Logical Operators 522 +----------+-------------+------------------------------------------+ 523 | Operator | Description | Behavior | 524 +----------+-------------+------------------------------------------+ 525 | () | Precedence | Boolean expressions may be grouped using | 526 | | grouping | parentheses to change the standard order | 527 | | | of operations; i.e., evaluate OR logical | 528 | | | operators before logical AND operators. | 529 +----------+-------------+------------------------------------------+ 531 Table 4: Grouping Operators 533 Filters MUST be evaluated using standard order of operations. 534 Attribute operators have the highest precedence, followed by the 535 grouping operator (i.e, parentheses), followed by the logical AND 536 operator, followed by the logical OR operator. 538 If the specified attribute in a filter expression is a multi-valued 539 attribute, the Resource MUST match if any of the instances of the 540 given attribute match the specified criterion; e.g. if a User has 541 multiple emails values, only one has to match for the entire User to 542 match. For complex attributes, a fully qualified Sub-Attribute MUST 543 be specified using standard attribute notation (Section 3.8). For 544 example, to filter by userName the parameter value is userName and to 545 filter by first name, the parameter value is name.givenName. 547 Providers MAY support additional filter operations if they choose. 548 Providers MUST decline to filter results if the specified filter 549 operation is not recognized and return a HTTP 400 error with an 550 appropriate human readable response. For example, if a Consumer 551 specified an unsupported operator named 'regex' the Service Provider 552 should specify an error response description identifying the Consumer 553 error; e.g., 'The operator 'regex' is not supported.' 555 String type attributes are case insensitive by default unless the 556 attribute type is defined as a caseExact string. Attribute operators 557 'eq', 'co', and 'sw' MUST perform caseIgnore matching for all string 558 attributes unless the attribute is defined as caseExact. By default 559 all string attributes are caseIgnore. 561 Examples: 563 filter=userName eq "bjensen" 565 filter=name.familyName co "O'Malley" 567 filter=userName sw "J" 569 filter=title pr 571 filter=meta.lastModified gt "2011-05-13T04:42:34Z" 573 filter=meta.lastModified ge "2011-05-13T04:42:34Z" 575 filter=meta.lastModified lt "2011-05-13T04:42:34Z" 577 filter=meta.lastModified le "2011-05-13T04:42:34Z" 579 filter=title pr and userType eq "Employee" 581 filter=title pr or userType eq "Intern" 583 filter=userType eq "Employee" and (emails co "example.com" or emails 584 co "example.org") 586 3.2.2.3. Sorting 588 Sort is OPTIONAL. Sorting allows Consumers to specify the order in 589 which Resources are returned by specifying a combination of sortBy 590 and sortOrder URL parameters. 592 sortBy: The sortBy parameter specifies the attribute whose value 593 SHALL be used to order the returned responses. If the sortBy 594 attribute corresponds to a Singular Attribute, Resources are 595 sorted according to that attribute's value; if it's a Multi-valued 596 Attribute, Resources are sorted by the value of the primary 597 attribute, if any, or else the first value in the list, if any. 598 If the attribute is complex the attribute name must be a path to a 599 Sub-Attribute in standard attribute notation (Section 3.8) ; e.g., 600 sortBy=name.givenName. For all attribute types, if there is no 601 data for the specified sortBy value they are sorted via the 602 'sortOrder' parameter; i.e., they are ordered last if ascending 603 and first if descending. 605 sortOrder: The order in which the sortBy parameter is applied. 606 Allowed values are "ascending" and "descending". If a value for 607 sortBy is provided and no sortOrder is specified, the sortOrder 608 SHALL default to ascending. String type attributes are case 609 insensitive by default unless the attribute type is defined as a 610 caseExact string. sortOrder MUST sort according to the attribute 611 type; i.e., for caseIgnore attributes, sort the result using case 612 insensitive, Unicode alphabetic sort order, with no specific 613 locale implied and for caseExact attribute types, sort the result 614 using case sensitive, Unicode alphabetic sort order. 616 3.2.2.4. Pagination 618 Pagination parameters can be used together to "page through" large 619 numbers of Resources so as not to overwhelm the Consumer or Service 620 Provider. Pagination is not session based hence Consumers SHOULD 621 never assume repeatable results. For example, a request for a list 622 of 10 Resources beginning with a startIndex of 1 may return different 623 results when repeated as a Resource in the original result could be 624 deleted or new ones could be added in-between requests. Pagination 625 parameters and general behavior are derived from the OpenSearch 626 Protocol [3]. 628 The following table describes the URL pagination parameters. 630 +------------+-------------------+----------------------------------+ 631 | Parameter | Description | Default | 632 +------------+-------------------+----------------------------------+ 633 | startIndex | The 1-based index | 1 | 634 | | of the first | | 635 | | search result. | | 636 | count | Non-negative | None. When specified the | 637 | | Integer. | Service Provider MUST not return | 638 | | Specifies the | more results than specified | 639 | | desired maximum | though MAY return fewer results. | 640 | | number of search | If unspecified, the maximum | 641 | | results per page; | number of results is set by the | 642 | | e.g., 10. | Service Provider. | 643 +------------+-------------------+----------------------------------+ 645 Table 5: Pagination Request parameters 647 The following table describes the query response pagination 648 attributes specified by the Service Provider. 650 +--------------+----------------------------------------------------+ 651 | Element | Description | 652 +--------------+----------------------------------------------------+ 653 | itemsPerPage | Non-negative Integer. Specifies the number of | 654 | | search results returned in a query response page; | 655 | | e.g., 10. | 656 | totalResults | Non-negative Integer. Specifies the total number | 657 | | of results matching the Consumer query; e.g., | 658 | | 1000. | 659 | startIndex | The 1-based index of the first result in the | 660 | | current set of search results; e.g., 1. | 661 +--------------+----------------------------------------------------+ 663 Table 6: Pagination Response Elements 665 For example, to retrieve the first 10 Users set the startIndex to 1 666 and the count to 10. 668 GET /Users?startIndex=1&count=10 669 Host: example.com 670 Accept: application/json 671 Authorization: Bearer h480djs93hd8 673 { 674 "totalResults":100, 675 "itemsPerPage":10, 676 "startIndex":1, 677 "schemas":["urn:scim:schemas:core:1.0"], 678 "Resources":[{ 679 ... 680 }] 681 } 683 Given the example above, to continue paging set the startIndex to 11 684 and re-fetch; i.e., /Users?startIndex=11&count=10 686 3.2.3. Querying Resources Using HTTP POST 688 Clients MAY execute queries without passing parameters on the URL by 689 using the HTTP POST verb combined with the '/.search' path extension. 690 The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL 691 be used to indicate the HTTP POST verb is intended to be a query 692 operation. 694 To create a new search result set, a SCIM client sends an HTTP POST 695 request to the desired SCIM resource endpoint (ending in '/.search'). 696 The body of the POST request MAY include any of the parameters as 697 defined in Section 3.2.2. 699 After receiving a HTTP POST request, a response is returned as 700 specified in Section 3.2.2. 702 [NOTE: See resourceType meta attribute in example below --> need to 703 update rest of document!] 704 The following example shows an HTTP POST Search request with search 705 parameters attributes, filter, and count included: 706 POST /.search 707 Host: example.com 708 Accept: application/json 709 Content-Type: application/json 710 Authorization: Bearer h480djs93hd8 711 Content-Length: ... 713 { 714 "schemas": ["urn:scim:schemas:core:1.0"], 715 "attributes":["displayName","username"], 716 "filter":"displayName sw \"smith\"", 717 "count":10 718 } 720 Figure 1: Example POST Search Request 722 A search response is shown with the first page of results. For 723 brevity reasons, only two matches are shown: one User and one Group. 724 HTTP/1.1 200 OK 725 Content-Type: application/json 726 Location: https://example.com/.search 727 { 728 "totalResults":100, 729 "itemsPerPage":10, 730 "startIndex":1, 731 "schemas":["urn:scim:schemas:core:1.0"], 732 "Resources":[ 733 { 734 "meta":{ 735 "location": 736 "https://example.com/Users/2819c223-7f76-413861904646", 737 "resourceType":"User", 738 "lastModified": ... 739 } 740 "username":"jsmith", 741 "displayName":"Smith, James" 742 }, 743 { 744 "meta":{ 745 "location": 746 "https://example.com/Groups/c8596b90-7539-4f20968d1908", 747 "resourceType":"Group", 748 "lastModified": ... 749 } 750 "displayName":"Smith Family" 751 }, 752 ... 753 ] 754 } 756 Figure 2: Example POST Search Response 758 3.3. Modifying Resources 760 Resources can be modified in whole or in part via PUT or PATCH, 761 respectively. Implementers MUST support PUT as specified in RFC2616 762 . Resources such as Groups may be very large hence implementers 763 SHOULD support PATCH [4] to enable partial resource modifications. 765 3.3.1. Modifying with PUT 767 PUT performs a full update. Consumers must retrieve the entire 768 Resource and PUT the desired modifications as the operation 769 overwrites all previously stored data with the exception of the 770 password attribute. If the password attribute of the User resource 771 is unspecified, it should be left in-tact. Since this performs a 772 full update, Consumers MAY send read-only attributes of the retrieved 773 resource and Service Provider MUST ignore any read-only attributes 774 that are present in the payload of a PUT request. Unless otherwise 775 specified a successful PUT operation returns a 200 OK response code 776 and the entire Resource within the response body, enabling the 777 Consumer to correlate the Consumer's and Provider's views of the 778 updated Resource. Example: 780 PUT /Users/2819c223-7f76-453a-919d-413861904646 781 Host: example.com 782 Accept: application/json 783 Content-Type: application/json 784 Authorization: Bearer h480djs93hd8 785 If-Match: W/"a330bc54f0671c9" 787 { 788 "schemas":["urn:scim:schemas:core:1.0"], 789 "id":"2819c223-7f76-453a-919d-413861904646", 790 "userName":"bjensen", 791 "externalId":"bjensen", 792 "name":{ 793 "formatted":"Ms. Barbara J Jensen III", 794 "familyName":"Jensen", 795 "givenName":"Barbara", 796 "middleName":"Jane" 797 }, 798 "emails":[ 799 { 800 "value":"bjensen@example.com" 801 }, 802 { 803 "value":"babs@jensen.org" 804 } 805 ] 806 } 808 The service responds with the entire, updated User 810 HTTP/1.1 200 OK 811 Content-Type: application/json 812 ETag: W/"b431af54f0671a2" 813 Location:"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646" 814 { 815 "schemas":["urn:scim:schemas:core:1.0"], 816 "id":"2819c223-7f76-453a-919d-413861904646", 817 "userName":"bjensen", 818 "externalId":"bjensen", 819 "name":{ 820 "formatted":"Ms. Barbara J Jensen III", 821 "familyName":"Jensen", 822 "givenName":"Barbara", 823 "middleName":"Jane" 824 }, 825 "emails":[ 826 { 827 "value":"bjensen@example.com" 828 }, 829 { 830 "value":"babs@jensen.org" 831 } 832 ], 833 "meta": { 834 "resourceType","User", 835 "created":"2011-08-08T04:56:22Z", 836 "lastModified":"2011-08-08T08:00:12Z", 837 "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", 838 "version":"W\/\"b431af54f0671a2\"" 839 } 840 } 842 3.3.2. Modifying with PATCH 844 PATCH is OPTIONAL. PATCH enables consumers to send only those 845 attributes requiring modification, reducing network and processing 846 overhead. Attributes may be deleted, replaced, merged, or added in a 847 single request. 849 The body of a PATCH request MUST contain a partial Resource with the 850 desired modifications. The server MUST return either a 200 OK 851 response code and the entire Resource (subject to the "attributes" 852 query parameter - see Additional Retrieval Query Parameters 853 (Section 3.7)) within the response body, or a 204 No Content response 854 code and the appropriate response headers for a successful PATCH 855 request. The server MUST return a 200 OK if the "attributes" 856 parameter is specified on the request. 858 The server MUST process a PATCH request by first removing any 859 attributes specified in the meta.attributes Sub-Attribute (if 860 present) and then merging the attributes in the PATCH request body 861 into the Resource. 863 The meta.attributes Sub-Attribute MAY contain a list of attributes to 864 be removed from the Resource. If the PATCH request body contains an 865 attribute that is present in the meta.attributes list, the attribute 866 on the Resource is replaced with the value from the PATCH body. If 867 the attribute is complex the attribute name must be a path to a Sub- 868 Attribute in standard attribute notation (Section 3.8); e.g., 869 name.givenName. 871 Attributes that exist in the PATCH request body but not in the 872 meta.attributes Sub-Attribute will be either be updated or added to 873 the Resource according to the following rules. 875 Singular attributes: Singular attributes in the PATCH request body 876 replace the attribute on the Resource. 878 Complex attributes: Complex Sub-Attribute values in the PATCH 879 request body are merged into the complex attribute on the 880 Resource. 882 Multi-valued attributes: An attribute value in the PATCH request 883 body is added to the value collection if the value does not exist 884 and merged if a matching value is present. Values are matched by 885 comparing the value Sub-Attribute from the PATCH request body to 886 the value Sub-Attribute of the Resource. Attributes that do not 887 have a value Sub-Attribute; e.g., addresses, or do not have unique 888 value Sub-Attributes cannot be matched and must instead be deleted 889 then added. Specific values can be removed from a Resource by 890 adding an "operation" Sub-Attribute with the value "delete" to the 891 attribute in the PATCH request body. As with adding/updating 892 attribute value collections, the value to delete is determined by 893 comparing the value Sub-Attribute from the PATCH request body to 894 the value Sub-Attribute of the Resource. Attributes that do not 895 have a value Sub-Attribute or that have a non-unique value Sub- 896 Attribute are matched by comparing all Sub-Attribute values from 897 the PATCH request body to the Sub-Attribute values of the 898 Resource. A delete operation is ignored if the attribute's name 899 is in the meta.attributes list. If the requested value to delete 900 does not match a unique value on the Resource the server MAY 901 return a HTTP 400 error. 903 The following example shows how to add a member to a group: 905 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 906 Host: example.com 907 Accept: application/json 908 Content-Type: application/json 909 Authorization: Bearer h480djs93hd8 910 If-Match: W/"a330bc54f0671c9" 912 { 913 "schemas": ["urn:scim:schemas:core:1.0"], 914 "members": [ 915 { 916 "display": "Babs Jensen", 917 "$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", 918 "value": "2819c223-7f76-453a-919d-413861904646" 919 } 920 ] 921 } 923 The "display" Sub-Attribute in this request is optional since the 924 value attribute uniquely identifies the user to be added. If the 925 user was already a member of this group, no changes should be made to 926 the Resource and a success response should be returned. The server 927 responds with either the entire updated Group or no response body: 929 HTTP/1.1 204 No Content 930 Authorization: Bearer h480djs93hd8 931 ETag: W/"b431af54f0671a2" 932 Location: "https://example.com/v1/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" 934 The following example shows how to remove a member from a group. As 935 with the previous example, the "display" Sub-Attribute is optional. 936 If the user was not a member of this group, no changes should be made 937 to the Resource and a success response should be returned. 939 Note that server responses have been omitted for the rest of the 940 PATCH examples. 942 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 943 Host: example.com 944 Accept: application/json 945 Content-Type: application/json 946 Authorization: Bearer h480djs93hd8 947 If-Match: W/"a330bc54f0671c9" 949 { 950 "schemas": ["urn:scim:schemas:core:1.0"], 951 "members": [ 952 { 953 "display": "Babs Jensen", 954 "$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", 955 "value": "2819c223-7f76-453a-919d-413861904646" 956 "operation": "delete" 957 } 958 ] 959 } 961 The following example shows how to remove all members from a group: 963 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 964 Host: example.com 965 Accept: application/json 966 Content-Type: application/json 967 Authorization: Bearer h480djs93hd8 968 If-Match: W/"a330bc54f0671c9" 970 { 971 "schemas": ["urn:scim:schemas:core:1.0"], 972 "meta": { 973 "attributes": [ 974 "members" 975 ] 976 } 977 } 979 The following example shows how to replace all of the members of a 980 group with a different members list: 982 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 983 Host: example.com 984 Accept: application/json 985 Content-Type: application/json 986 Authorization: Bearer h480djs93hd8 987 If-Match: W/"a330bc54f0671c9" 989 { 990 "schemas": ["urn:scim:schemas:core:1.0"], 991 "meta": { 992 "attributes": [ 993 "members" 994 ] 995 }, 996 "members": [ 997 { 998 "display": "Babs Jensen", 999 "$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", 1000 "value": "2819c223-7f76-453a-919d-413861904646" 1001 }, 1002 { 1003 "display": "James Smith", 1004 "$ref": "https://example.com/v1/Users/08e1d05d-121c-4561-8b96-473d93df9210", 1005 "value": "08e1d05d-121c-4561-8b96-473d93df9210" 1006 } 1007 ] 1008 } 1010 The following example shows how to add a member to and remove a 1011 member from a Group in a single request: 1013 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1014 Host: example.com 1015 Accept: application/json 1016 Content-Type: application/json 1017 Authorization: Bearer h480djs93hd8 1018 If-Match: W/"a330bc54f0671c9" 1020 { 1021 "schemas": ["urn:scim:schemas:core:1.0"], 1022 "members": [ 1023 { 1024 "display": "Babs Jensen", 1025 "$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", 1026 "value": "2819c223-7f76-453a-919d-413861904646" 1027 "operation": "delete" 1028 }, 1029 { 1030 "display": "James Smith", 1031 "$ref": "https://example.com/v1/Users/08e1d05d-121c-4561-8b96-473d93df9210", 1032 "value": "08e1d05d-121c-4561-8b96-473d93df9210" 1033 } 1034 ] 1035 } 1037 The following example shows how to change a User's primary email. If 1038 the User already has the email address, it is made the primary 1039 address and the current primary address (if present) is made non- 1040 primary. If the User does not already have the email address, it is 1041 added and made the primary address. 1043 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1044 Host: example.com 1045 Accept: application/json 1046 Content-Type: application/json 1047 Authorization: Bearer h480djs93hd8 1048 If-Match: W/"a330bc54f0671c9" 1050 { 1051 "schemas": ["urn:scim:schemas:core:1.0"], 1052 "emails": [ 1053 { 1054 "value": "bjensen@example.com", 1055 "primary": true 1056 } 1057 ] 1058 } 1060 The following example shows how to change a User's address. Since 1061 address does not have a value Sub-Attribute, the existing address 1062 must be removed and the modified address added. 1064 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1065 Host: example.com 1066 Accept: application/json 1067 Content-Type: application/json 1068 Authorization: Bearer h480djs93hd8 1069 If-Match: W/"a330bc54f0671c9" 1071 { 1072 "schemas": ["urn:scim:schemas:core:1.0"], 1073 "addresses": [ 1074 { 1075 "type": "work", 1076 "streetAddress": "100 Universal City Plaza", 1077 "locality": "Hollywood", 1078 "region": "CA", 1079 "postalCode": "91608", 1080 "country": "US", 1081 "formatted": "100 Universal City Plaza\nHollywood, CA 91608 US", 1082 "primary": true 1083 "operation": "delete" 1084 }, 1085 { 1086 "type": "work", 1087 "streetAddress": "911 Universal City Plaza", 1088 "locality": "Hollywood", 1089 "region": "CA", 1090 "postalCode": "91608", 1091 "country": "US", 1092 "formatted": "911 Universal City Plaza\nHollywood, CA 91608 US", 1093 "primary": true 1094 } 1095 ] 1096 } 1098 The following example shows how to change a User's nickname: 1100 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1101 Host: example.com 1102 Accept: application/json 1103 Content-Type: application/json 1104 Authorization: Bearer h480djs93hd8 1105 If-Match: W/"a330bc54f0671c9" 1107 { 1108 "schemas": ["urn:scim:schemas:core:1.0"], 1109 "nickName": "Barbie" 1110 } 1112 The following example shows how to remove a User's nickname: 1114 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1115 Host: example.com 1116 Accept: application/json 1117 Content-Type: application/json 1118 Authorization: Bearer h480djs93hd8 1119 If-Match: W/"a330bc54f0671c9" 1121 { 1122 "schemas": ["urn:scim:schemas:core:1.0"], 1123 "meta": { 1124 "attributes": [ 1125 "nickName" 1126 ] 1127 } 1128 } 1130 The following example shows how to change a User's familyName. This 1131 only updates the familyName and formatted on the "name" complex 1132 attribute. Any other name Sub-Attributes on the Resource remain 1133 unchanged. 1135 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1136 Host: example.com 1137 Accept: application/json 1138 Content-Type: application/json 1139 Authorization: Bearer h480djs93hd8 1140 If-Match: W/"a330bc54f0671c9" 1142 { 1143 "schemas": ["urn:scim:schemas:core:1.0"], 1144 "name": { 1145 "formatted": "Ms. Barbara J Jensen III", 1146 "familyName": "Jensen" 1147 } 1149 } 1151 The following example shows how to remove a complex Sub-Attribute and 1152 an extended schema attribute from a User. 1154 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1155 Host: example.com 1156 Accept: application/json 1157 Content-Type: application/json 1158 Authorization: Bearer h480djs93hd8 1159 If-Match: W/"a330bc54f0671c9" 1161 { 1162 "schemas": ["urn:scim:schemas:core:1.0"], 1163 "meta": { 1164 "attributes": [ 1165 "name.formatted", 1166 "urn:hr:schemas:user:age" 1167 ] 1168 } 1169 } 1171 3.4. Deleting Resources 1173 Consumers request Resource removal via DELETE. Service Providers MAY 1174 choose not to permanently delete the Resource, but MUST return a 404 1175 error code for all operations associated with the previously deleted 1176 Id. Service Providers MUST also omit the Resource from future query 1177 results. In addition the Service Provider MUST not consider the 1178 deleted resource in conflict calculation. For example if a User 1179 resource is deleted, a CREATE request for a User resource with the 1180 same userName as the previously deleted resource should not fail with 1181 a 409 error due to userName conflict. 1183 DELETE /Users/2819c223-7f76-453a-919d-413861904646 1184 Host: example.com 1185 Authorization: Bearer h480djs93hd8 1186 If-Match: W/"c310cd84f0281b7" 1188 Server Response: 1190 HTTP/1.1 200 OK 1192 Example: Consumer attempt to retrieve the previously deleted User 1193 GET /Users/2819c223-7f76-453a-919d-413861904646 1194 Host: example.com 1195 Authorization: Bearer h480djs93hd8 1197 Server Response: 1199 HTTP/1.1 404 NOT FOUND 1201 { 1202 "Errors":[ 1203 { 1204 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 1205 "code":"404" 1206 } 1207 ] 1208 } 1210 3.5. Bulk 1212 Bulk is OPTIONAL. The bulk operation enables Consumers to send a 1213 potentially large collection of Resource operations in a single 1214 request. The body of a a bulk operation contains a set of HTTP 1215 Resource operations using one of the API supported HTTP methods; 1216 i.e., POST, PUT, PATCH or DELETE. 1218 The following Singular Attribute is defined in addition to the common 1219 attributes defined in SCIM core schema. 1221 failOnErrors An Integer specifying the number of errors that the 1222 Service Provider will accept before the operation is terminated 1223 and an error response is returned. OPTIONAL. 1225 The following Complex Multi-valued Attribute is defined in addition 1226 to the common attributes defined in core schema. 1228 Operations Defines operations within a bulk job. Each operation 1229 corresponds to a single HTTP request against a Resource endpoint. 1230 REQUIRED. 1232 method The HTTP method of the current operation. Possible values 1233 are POST, PUT, PATCH or DELETE. REQUIRED. 1235 bulkId The transient identifier of a newly created Resource, 1236 unique within a bulk request and created by the Consumer. The 1237 bulkId serves as a surrogate Resource id enabling Consumers to 1238 uniquely identify newly created Resources in the Response and 1239 cross reference new Resources in and across operations within a 1240 bulk request. REQUIRED when method is POST. 1242 version The current Resource version. Version is REQUIRED if the 1243 Service Provider supports ETags and the method is PUT, DELETE, 1244 or PATCH. 1246 path The Resource's relative path. If the method is POST the 1247 value must specify a Resource type endpoint; e.g., /Users or 1248 /Groups whereas all other method values must specify the path 1249 to a specific Resource; e.g., /Users/ 1250 2819c223-7f76-453a-919d-413861904646. REQUIRED in a request. 1252 data The Resource data as it would appear for a single POST, PUT 1253 or PATCH Resource operation. REQUIRED in a request when method 1254 is POST, PUT and PATCH. 1256 location The Resource endpoint URL. REQUIRED in a response, 1257 except in the event of a POST failure. 1259 status A complex type that contains information about the success 1260 or failure of one operation within the bulk job. REQUIRED in a 1261 response. 1263 code The HTTP response code that would have been returned if a 1264 a single HTTP request would have been used. REQUIRED. 1266 description A human readable error message. REQUIRED when an 1267 error occurred. 1269 If a bulk job is processed successfully the HTTP response code 200 OK 1270 MUST be returned, otherwise an appropriate HTTP error code MUST be 1271 returned. 1273 The Service Provider MUST continue performing as many changes as 1274 possible and disregard partial failures. The Consumer MAY override 1275 this behavior by specifying a value for failOnErrors attribute. The 1276 failOnErrors attribute defines the number of errors that the Service 1277 Provider should accept before failing the remaining operations 1278 returning the response. 1280 To be able to reference a newly created Resource the attribute bulkId 1281 MUST be specified when creating new Resources. The bulkId is defined 1282 by the Consumer as a surrogate identifier in a POST operation. The 1283 Service Provider MUST return the same bulkId together with the newly 1284 created Resource. The bulkId can then be used by the Consumer to map 1285 the Service Provider id with the bulkId of the created Resource. 1287 There can be more then one operation per Resource in each bulk job. 1288 The Service Consumer MUST take notice of the unordered structure of 1289 JSON and the Service Provider can process operations in any order. 1290 For example, if the Service Consumer sends two PUT operations in one 1291 request, the outcome is non-deterministic. 1293 The Service Provider response MUST include the result of all 1294 processed operations. A location attribute that includes the 1295 Resource's end point MUST be returned for all operations excluding 1296 failed POSTs. The status attribute includes information about the 1297 success or failure of one operation within the bulk job. The 1298 attribute status MUST include the code attribute that holds the HTTP 1299 response code that would have been returned if a single HTTP request 1300 would have been used. If an error occurred the status MUST also 1301 include the description attribute containing a human readable 1302 explanation of the error. 1304 "status": { 1305 "code": "201" 1306 } 1308 The following is an example of a status in a failed operation. 1310 "status": { 1311 "code": "400", 1312 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1313 } 1315 The following example shows how to add, update, and remove a user. 1316 The failOnErrors attribute is set to '1' indicating the Service 1317 Provider should return on the first error. The POST operation's 1318 bulkId value is set to 'qwerty' enabling the Consumer to match the 1319 new User with the returned Resource id '92b725cd-9465-4e7d-8c16- 1320 01f8e146b87a'. 1322 POST /v1/Bulk 1323 Host: example.com 1324 Accept: application/json 1325 Content-Type: application/json 1326 Authorization: Bearer h480djs93hd8 1327 Content-Length: ... 1329 { 1330 "schemas":[ 1331 "urn:scim:schemas:core:1.0" 1333 ], 1334 "failOnErrors":1, 1335 "Operations":[ 1336 { 1337 "method":"POST", 1338 "path":"/Users", 1339 "bulkId":"qwerty", 1340 "data":{ 1341 "schemas":[ 1342 "urn:scim:schemas:core:1.0" 1343 ], 1344 "userName":"Alice" 1345 } 1346 }, 1347 { 1348 "method":"PUT", 1349 "path":"/Users/b7c14771-226c-4d05-8860-134711653041", 1350 "version":"W\/\"3694e05e9dff591\"", 1351 "data":{ 1352 "schemas":[ 1353 "urn:scim:schemas:core:1.0" 1354 ], 1355 "id":"b7c14771-226c-4d05-8860-134711653041", 1356 "userName":"Bob" 1357 } 1358 }, 1359 { 1360 "method":"PATCH", 1361 "path":"/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1362 "version":"W\/\"edac3253e2c0ef2\"", 1363 "data":{ 1364 "schemas":[ 1365 "urn:scim:schemas:core:1.0" 1366 ], 1367 "id":"5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1368 "userName":"Dave", 1369 "meta":{ 1370 "attributes":[ 1371 "nickName" 1372 ] 1373 } 1374 } 1375 }, 1376 { 1377 "method":"DELETE", 1378 "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1379 "version":"W\/\"0ee8add0a938e1a\"" 1380 } 1382 ] 1383 } 1385 The Service Provider returns the following response. 1387 HTTP/1.1 200 OK 1388 Content-Type: application/json 1390 { 1391 "schemas": [ 1392 "urn:scim:schemas:core:1.0" 1393 ], 1394 "Operations": [ 1395 { 1396 "location": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1397 "method": "POST", 1398 "bulkId": "qwerty", 1399 "version": "W\/\"oY4m4wn58tkVjJxK\"", 1400 "status": { 1401 "code": "201" 1402 } 1403 }, 1404 { 1405 "location": "https://example.com/v1/Users/b7c14771-226c-4d05-8860-134711653041", 1406 "method": "PUT", 1407 "version": "W\/\"huJj29dMNgu3WXPD\"", 1408 "status": { 1409 "code": "200" 1410 } 1411 }, 1412 { 1413 "location": "https://example.com/v1/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1414 "method": "PATCH", 1415 "version": "W\/\"huJj29dMNgu3WXPD\"", 1416 "status": { 1417 "code": "200" 1418 } 1419 }, 1420 { 1421 "location": "https://example.com/v1/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1422 "method": "DELETE", 1423 "status": { 1424 "code": "200" 1425 } 1426 } 1427 ] 1428 } 1429 The following response is returned if an error occurred when 1430 attempting to create the User 'Alice'. The Service Provider stops 1431 processing the bulk operation and immediately returns a response to 1432 the Consumer. The response contains the error and any successful 1433 results prior to the error. 1435 HTTP/1.1 200 OK 1436 Content-Type: application/json 1438 { 1439 "schemas": [ 1440 "urn:scim:schemas:core:1.0" 1441 ], 1442 "Operations": [ 1443 { 1444 "method": "POST", 1445 "bulkId": "qwerty", 1446 "status": { 1447 "code": "400", 1448 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1449 } 1450 } 1451 ] 1452 } 1454 If the failOnErrors attribute is not specified or the Service 1455 Provider has not reached the error limit defined by the Consumer the 1456 Service Provider will continue to process all operations. The 1457 following is an example in which all operations failed. 1459 HTTP/1.1 200 OK 1460 Content-Type: application/json 1462 { 1463 "schemas": [ 1464 "urn:scim:schemas:core:1.0" 1465 ], 1466 "Operations": [ 1467 { 1468 "method": "POST", 1469 "bulkId": "qwerty", 1470 "status": { 1471 "code": "400", 1472 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1473 } 1474 }, 1475 { 1476 "location": "https://example.com/v1/Users/b7c14771-226c-4d05-8860-134711653041", 1477 "method": "PUT", 1478 "status": { 1479 "code": "412", 1480 "description": "Failed to update as user changed on the server since you last retrieved it." 1481 } 1482 }, 1483 { 1484 "location": "https://example.com/v1/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1485 "method": "PATCH", 1486 "status": { 1487 "code": "412", 1488 "description": "Failed to update as user changed on the server since you last retrieved it." 1489 } 1490 }, 1491 { 1492 "location": "https://example.com/v1/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1493 "method": "DELETE", 1494 "status": { 1495 "code": "404", 1496 "description": "Specified resource; e.g., User, does not exist." 1497 } 1498 } 1499 ] 1500 } 1502 The Consumer can, within one bulk operation, create a new User, a new 1503 Group and add the newly created User to the newly created Group. In 1504 order to add the new User to the Group the Consumer must use the 1505 surrogate id attribute, bulkId, to reference the User. The bulkId 1506 attribute value must be pre-pended with the literal "bulkId:"; e.g., 1507 if the bulkId is 'qwerty' the value is "bulkId:qwerty". The Service 1508 Provider MUST replace the string "bulkId:qwerty" with the permanent 1509 Resource id once created. 1511 The following example creates a User with the userName 'Alice' and a 1512 Group with the displayName 'Tour Guides' with Alice as a member. 1514 POST /v1/Bulk 1515 Host: example.com 1516 Accept: application/json 1517 Content-Type: application/json 1518 Authorization: Bearer h480djs93hd8 1519 Content-Length: ... 1521 { 1522 "schemas": [ 1523 "urn:scim:schemas:core:1.0" 1524 ], 1525 "Operations": [ 1526 { 1527 "method": "POST", 1528 "path": "/Users", 1529 "bulkId": "qwerty", 1530 "data": { 1531 "schemas": [ 1532 "urn:scim:schemas:core:1.0" 1533 ], 1534 "userName": "Alice" 1535 } 1536 }, 1537 { 1538 "method": "POST", 1539 "path": "/Groups", 1540 "bulkId": "ytrewq", 1541 "data": { 1542 "schemas": [ 1543 "urn:scim:schemas:core:1.0" 1544 ], 1545 "displayName": "Tour Guides", 1546 "members": [ 1547 { 1548 "type": "user", 1549 "value": "bulkId:qwerty" 1550 } 1551 ] 1552 } 1553 } 1555 ] 1556 } 1558 The Service Provider returns the following response. 1560 HTTP/1.1 200 OK 1561 Content-Type: application/json 1563 { 1564 "schemas": [ 1565 "urn:scim:schemas:core:1.0" 1566 ], 1567 "Operations": [ 1568 { 1569 "location": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1570 "method": "POST", 1571 "bulkId": "qwerty", 1572 "version": "W\/\"4weymrEsh5O6cAEK\"", 1573 "status": { 1574 "code": "201" 1575 } 1576 }, 1577 { 1578 "location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1579 "method": "POST", 1580 "bulkId": "ytrewq", 1581 "version": "W\/\"lha5bbazU3fNvfe5\"", 1582 "status": { 1583 "code": "201" 1584 } 1585 } 1586 ] 1587 } 1589 A subsequent request for the 'Tour Guides' Group ('e9e30dba-f08f- 1590 4109-8486-d5c6a331660a') returns the following: 1592 GET /v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1593 Host: example.com 1594 Accept: application/json 1595 Authorization: Bearer h480djs93hd8 1597 HTTP/1.1 200 OK 1598 Content-Type: application/json 1599 Location: https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1600 ETag: W/"lha5bbazU3fNvfe5" 1602 { 1603 "schemas":["urn:scim:schemas:core:1.0"], 1604 "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", 1605 "displayName": "Tour Guides", 1606 "meta": { 1607 "created":"2011-08-01T18:29:49.793Z", 1608 "lastModified":"2011-08-01T20:31:02.315Z", 1609 "location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1610 "version": "W\/\"lha5bbazU3fNvfe5\"" 1611 }, 1612 "members": [ 1613 { 1614 "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", 1615 "$ref": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1616 "type": "User" 1617 } 1618 ] 1619 } 1621 Extensions that include references to other Resources MUST be handled 1622 in the same way by the Service Provider. The following example uses 1623 the bulkId attribute within the enterprise extension managerId 1624 attribute. 1626 POST /v1/Bulk 1627 Host: example.com 1628 Accept: application/json 1629 Content-Type: application/json 1630 Authorization: Bearer h480djs93hd8 1631 Content-Length: ... 1633 { 1634 "schemas": [ 1635 "urn:scim:schemas:core:1.0" 1636 ], 1637 "Operations": [ 1638 { 1639 "method": "POST", 1640 "path": "/Users", 1641 "bulkId": "qwerty", 1642 "data": { 1643 "schemas": [ 1644 "urn:scim:schemas:core:1.0" 1645 ], 1646 "userName": "Alice" 1647 } 1648 }, 1649 { 1650 "method": "POST", 1651 "path": "/Users", 1652 "bulkId": "ytrewq", 1653 "data": { 1654 "schemas": [ 1655 "urn:scim:schemas:core:1.0", 1656 "urn:scim:schemas:extension:enterprise:1.0" 1657 ], 1658 "userName": "Bob", 1659 "urn:scim:schemas:extension:enterprise:1.0": { 1660 "employeeNumber": "11250", 1661 "manager": { 1662 "managerId": "batchId:qwerty", 1663 "displayName": "Alice" 1664 } 1665 } 1666 } 1667 } 1668 ] 1669 } 1671 The Service Provider MUST try to resolve circular cross references 1672 between Resources in a single bulk job but MAY stop after a failed 1673 attempt and instead return the status code 409 Conflict. The 1674 following example exhibits the potential conflict. 1676 POST /v1/Bulk 1677 Host: example.com 1678 Accept: application/json 1679 Content-Type: application/json 1680 Authorization: Bearer h480djs93hd8 1681 Content-Length: ... 1683 { 1684 "schemas": [ 1685 "urn:scim:schemas:core:1.0" 1686 ], 1687 "Operations": [ 1688 { 1689 "method": "POST", 1690 "path": "/Groups", 1691 "bulkId": "qwerty", 1692 "data": { 1693 "schemas": [ 1694 "urn:scim:schemas:core:1.0" 1695 ], 1696 "displayName": "Group A", 1697 "members": [ 1698 { 1699 "type": "group", 1700 "value": "bulkId:ytrewq" 1701 } 1702 ] 1703 } 1704 }, 1705 { 1706 "method": "POST", 1707 "path": "/Groups", 1708 "bulkId": "ytrewq", 1709 "data": { 1710 "schemas": [ 1711 "urn:scim:schemas:core:1.0" 1712 ], 1713 "displayName": "Group B", 1714 "members": [ 1715 { 1716 "type": "group", 1717 "value": "bulkId:qwerty" 1718 } 1719 ] 1720 } 1721 } 1722 ] 1723 } 1724 If the Service Provider resolved the above circular references the 1725 following is returned from a subsequent GET request. 1727 GET /v1/Groups?filter=displayName sw 'Group' 1728 Host: example.com 1729 Accept: application/json 1730 Authorization: Bearer h480djs93hd8 1732 HTTP/1.1 200 OK 1733 Content-Type: application/json 1735 { 1736 "totalResults": 2, 1737 "schemas": [ 1738 "urn:scim:schemas:core:1.0" 1739 ], 1740 "Resources": [ 1741 { 1742 "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1743 "schemas": [ 1744 "urn:scim:schemas:core:1.0" 1745 ], 1746 "displayName": "Group A", 1747 "meta": { 1748 "created":"2011-08-01T18:29:49.793Z", 1749 "lastModified":"2011-08-01T18:29:51.135Z", 1750 "location":"https://example.com/v1/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1751 "version":"W\/\"mvwNGaxB5SDq074p\"" 1752 }, 1753 "members": [ 1754 { 1755 "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1756 "$ref": "https://example.com/v1/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1757 "type": "Group" 1758 } 1759 ] 1760 }, 1761 { 1762 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1763 "schemas": [ 1764 "urn:scim:schemas:core:1.0" 1765 ], 1766 "displayName": "Group B", 1767 "meta": { 1768 "created":"2011-08-01T18:29:50.873Z", 1769 "lastModified":"2011-08-01T18:29:50.873Z", 1770 "location":"https://example.com/v1/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1771 "version":"W\/\"wGB85s2QJMjiNnuI\"" 1772 }, 1773 "members": [ 1774 { 1775 "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1776 "$ref": "https://example.com/v1/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1777 "type": "Group" 1778 } 1779 ] 1780 } 1781 ] 1782 } 1784 The Service Provider MUST define the maximum number of operations and 1785 maximum payload size a Consumer may send in a single request. If 1786 either limits are exceeded the Service Provider MUST return the HTTP 1787 response code 413 Request Entity Too Large. The returned response 1788 MUST specify the limit exceeded in the body of the error response. 1790 The following example the Consumer sent a request exceeding the 1791 Service Provider's max payload size of 1 megabyte. 1793 POST /v1/Bulk 1794 Host: example.com 1795 Accept: application/json 1796 Content-Type: application/json 1797 Authorization: Bearer h480djs93hd8 1798 Content-Length: 4294967296 1800 ... 1802 HTTP/1.1 413 Request Entity Too Large 1803 Content-Type: application/json 1804 Location: https://example.com/v1/Bulk/yfCrVJhFIJagAHj8 1806 { 1807 "Errors":[ 1808 { 1809 "description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).", 1810 "code":"413" 1811 } 1812 ] 1813 } 1814 3.6. Data Input/Output Formats 1816 Consumers MUST specify the format in which the data is submitted via 1817 the HTTP header content-type and MAY specify the desired response 1818 data format via an HTTP Accept Header; e.g.,"Accept: application/ 1819 json" or via URI suffix; e.g., 1821 GET /Users/2819c223-7f76-453a-919d-413861904646.json 1822 Host: example.com 1824 Service Providers MUST support the Accept Headers "Accept: 1825 application/json" for JSON [5]. The format defaults to JSON if no 1826 format is specified. 1828 Singular attributes are encoded as string name-value-pairs in JSON; 1829 e.g., 1831 "attribute": "value" 1833 Multi-valued attributes in JSON are encoded as arrays; e.g., 1835 "attributes": [ "value1", "value2" ] 1837 Elements with nested elements are represented as objects in JSON; 1838 e.g, 1840 "attribute": { "subattribute1": "value1", "subattribute2": "value2" } 1842 3.7. Additional retrieval query parameters 1844 Consumers MAY request a partial Resource representation on any 1845 operation that returns a Resource within the response by specifying 1846 the URL query parameter 'attributes'. When specified, each Resource 1847 returned MUST contain the minimal set of Resource attributes and, 1848 MUST contain no other attributes or Sub-Attributes than those 1849 explicitly requested. The query parameter attributes value is a 1850 comma separated list of Resource attribute names in standard, 1851 attribute notation (Section 3.8) form (e.g. userName, name, emails). 1853 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName 1854 Host: example.com 1855 Accept: application/json 1856 Authorization: Bearer h480djs93hd8 1858 Giving the response 1860 HTTP/1.1 200 OK 1861 Content-Type: application/json 1862 Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646 1863 ETag: W/"a330bc54f0671c9" 1865 { 1866 "schemas":["urn:scim:schemas:core:1.0"], 1867 "id":"2819c223-7f76-453a-919d-413861904646", 1868 "userName":"bjensen", 1869 "meta":{ 1870 "created":"2011-08-01T18:29:49.793Z", 1871 "lastModified":"2011-08-01T18:29:49.793Z", 1872 "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", 1873 "version":"W\/\"a330bc54f0671c9\"" 1874 } 1875 } 1877 3.8. Attribute Notation 1879 All operations share a common scheme for referencing simple and 1880 complex attributes. In general, attributes are identified by 1881 prefixing the attribute name with its schema URN separated by a ':' 1882 character; e.g., the core User Resource attribute 'userName' is 1883 identified as 'urn:scim:schemas:core:1.0:userName'. Consumers MAY 1884 omit core schema attribute URN prefixes though MUST fully qualify 1885 extended attributes with the associated Resource URN; e.g., the 1886 attribute 'age' defined in 'urn:hr:schemas:user' is fully encoded as 1887 'urn:hr:schemas:user:age'. A Complex attributes' Sub-Attributes are 1888 referenced via nested, dot ('.') notation; i.e., {urn}:{Attribute 1889 name}.{Sub-Attribute name}. For example, the fully qualified path 1890 for a User's givenName is urn:scim:schemas:core:1.0:name.givenName 1891 All facets (URN, attribute and Sub-Attribute name) of the fully 1892 encoded Attribute name are case insensitive. 1894 3.9. HTTP Response Codes 1896 The SCIM Protocol uses the response status codes defined in HTTP [6] 1897 to indicate operation success or failure. In addition to returning a 1898 HTTP response code implementers MUST return the errors in the body of 1899 the response in the client requested format containing the error 1900 response and, per the HTTP specification, human-readable 1901 explanations. Implementers SHOULD handle the identified errors as 1902 described below. 1904 +--------------+---------------------------+------------------------+ 1905 | Code | Applicability | Suggested Explanation | 1906 +--------------+---------------------------+------------------------+ 1907 | 400 BAD | GET,POST,PUT,PATCH,DELETE | Request is | 1908 | REQUEST | | unparseable, | 1909 | | | syntactically | 1910 | | | incorrect, or violates | 1911 | | | schema | 1912 | 401 | GET,POST,PUT,PATCH,DELETE | Authorization failure | 1913 | UNAUTHORIZED | | | 1914 | 403 | GET,POST,PUT,PATCH,DELETE | Server does not | 1915 | FORBIDDEN | | support requested | 1916 | | | operation | 1917 | 404 NOT | GET,PUT,PATCH,DELETE | Specified resource; | 1918 | FOUND | | e.g., User, does not | 1919 | | | exist | 1920 | 409 CONFLICT | POST, PUT,PATCH,DELETE | The specified version | 1921 | | | number does not match | 1922 | | | the resource's latest | 1923 | | | version number or a | 1924 | | | Service Provider | 1925 | | | refused to create a | 1926 | | | new, duplicate | 1927 | | | resource | 1928 | 412 | PUT,PATCH,DELETE | Failed to update as | 1929 | PRECONDITION | | Resource {id} changed | 1930 | FAILED | | on the server last | 1931 | | | retrieved | 1932 | 413 REQUEST | POST | {"maxOperations": | 1933 | ENTITY TOO | | 1000,"maxPayload": | 1934 | LARGE | | 1048576} | 1935 | 500 INTERNAL | GET,POST,PUT,PATCH,DELETE | An internal error. | 1936 | SERVER ERROR | | Implementers SHOULD | 1937 | | | provide descriptive | 1938 | | | debugging advice | 1939 | 501 NOT | GET,POST,PUT,PATCH,DELETE | Service Provider does | 1940 | IMPLEMENTED | | not support the | 1941 | | | request operation; | 1942 | | | e.g., PATCH | 1943 +--------------+---------------------------+------------------------+ 1945 Table 7: Defined error cases 1947 Error example in response to a non-existent GET request. 1949 HTTP/1.1 404 NOT FOUND 1951 { 1952 "Errors":[ 1953 { 1954 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 1955 "code":"404" 1956 } 1957 ] 1958 } 1960 3.10. API Versioning 1962 The Base URL MAY be appended with a version identifier as a separate 1963 segment in the URL path. At this time the only valid identifier is 1964 'v1'. If specified, the version identifier MUST appear in the URL 1965 path immediately preceding the Resource endpoint and conform to the 1966 following scheme: the character 'v' followed by the desired SCIM 1967 version number; e.g., a version 'v1' User request is specified as 1968 /v1/Users. When specified Service Providers MUST perform the 1969 operation using the desired version or reject the request. When 1970 omitted Service Providers SHOULD perform the operation using the most 1971 recent API supported by the Service Provider. 1973 3.11. Versioning Resources 1975 The API supports resource versioning via standard,HTTP ETags. 1976 Service providers MAY support weak ETags as the preferred mechanism 1977 for performing conditional retrievals and ensuring Consumers do not 1978 inadvertently overwrite each others changes, respectively. When 1979 supported SCIM ETags MUST be specified as an HTTP header and SHOULD 1980 be specified within the 'version' attribute contained in the 1981 Resource's 'meta' attribute. 1983 Example: 1985 POST /Users HTTP/1.1 1986 Host: example.com 1987 Content-Type: application/json 1988 Authorization: Bearer h480djs93hd8 1989 Content-Length: ... 1991 { 1992 "schemas":["urn:scim:schemas:core:1.0"], 1993 "userName":"bjensen", 1994 "externalId":"bjensen", 1995 "name":{ 1996 "formatted":"Ms. Barbara J Jensen III", 1997 "familyName":"Jensen", 1998 "givenName":"Barbara" 1999 } 2000 } 2002 The server responds with an ETag in the response header and meta 2003 structure. 2005 HTTP/1.1 201 Created 2006 Content-Type: application/json 2007 Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646 2008 ETag: W/"e180ee84f0671b1" 2010 { 2011 "schemas":["urn:scim:schemas:core:1.0"], 2012 "id":"2819c223-7f76-453a-919d-413861904646", 2013 "meta":{ 2014 "created":"2011-08-01T21:32:44.882Z", 2015 "lastModified":"2011-08-01T21:32:44.882Z", 2016 "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646", 2017 "version":"W\/\"e180ee84f0671b1\"" 2018 }, 2019 "name":{ 2020 "formatted":"Ms. Barbara J Jensen III", 2021 "familyName":"Jensen", 2022 "givenName":"Barbara" 2023 }, 2024 "userName":"bjensen" 2025 } 2027 With the returned ETag, Consumers MAY choose to retrieve the Resource 2028 only if the Resource has been modified. 2030 Conditional retrieval example using If-None-Match header: 2032 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName 2033 Host: example.com 2034 Accept: application/json 2035 Authorization: Bearer h480djs93hd8 2036 If-None-Match: W/"e180ee84f0671b1" 2038 If the Resource has not changed the Service Provider simply returns 2039 an empty body with a 304 "Not Modified" response code. 2041 If the Service Providers supports versioning of resources the 2042 Consumer MUST supply an If-Match header for PUT and PATCH operations 2043 to ensure that the requested operation succeeds only if the supplied 2044 ETag matches the latest Service Provider Resource; e.g., If-Match: 2045 W/"e180ee84f0671b1" 2047 3.12. HTTP Method Overloading 2049 In recognition that some clients, servers and firewalls prevent PUT, 2050 PATCH and DELETE operations a client MAY override the POST operation 2051 by specifying the custom header "X-HTTP-Method-Override" with the 2052 desired PUT, PATCH, DELETE operation. For example: 2054 POST /Users/2819c223-7f76-453a-919d-413861904646 2055 X-HTTP-Method-Override: DELETE 2057 4. Multi-Tenancy 2059 A single Service Provider may expose the SCIM protocol to multiple 2060 Consumers. Depending on the nature of the service, the Consumers may 2061 have authority to access and alter Resources initially created by 2062 other Consumers. Alternatively, Consumers may expect to access 2063 disjoint sets of Resources, and may expect that their resources are 2064 inaccessible by other Consumers. These scenarios are called "multi- 2065 tenancy", where each Consumer is understood to be or represent a 2066 "tenant" of the Service Provider. Consumers may also be multi- 2067 tenanted. 2069 The following common cases may occur: 2071 1. All Consumers share all Resources (no tenancy) 2073 2. Each single Consumer creates and accesses a private subset of 2074 Resources (1 Consumer:1 Tenant) 2076 3. Sets of Consumers share sets of Resources (M Consumers:1 Tenant) 2078 4. One Consumer to Multiple Tenants (1 Consumer:M Tenants) 2080 Service Providers may implement any subset of the above cases. 2082 Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a 2083 scheme for multi-tenancy. 2085 The SCIM protocol does not prescribe the mechanisms whereby Consumers 2086 and Service Providers interact for: 2088 o Registering or provisioning Tenants 2090 o Associating a subset of Consumers with a subset of the Tenants 2092 o Indicating which tenant is associated with the data in a request 2093 or response, or indicating which Tenant is the subject of a query 2095 o Implementers are encouraged to use mechanisms which comply with 2096 RESTful conventions. 2098 4.1. Associating Consumers to Tenants 2100 The Service Provider MAY use the authentication mechanism (Section 2) 2101 to determine the identity of the Consumer, and thus infer the 2102 associated Tenant. 2104 For implementations where a Consumer is associated with more than one 2105 Tenant, the Service Provider MAY use one of the following methods for 2106 explicit specification of the Tenant. 2108 If any of these methods of allowing the Consumer to explicitly 2109 specify the Tenant are employed, the Service Provider should ensure 2110 that access controls are in place to prevent or allow cross-tenant 2111 use cases. 2113 The Service Provider should consider precedence in cases where a 2114 Consumer may explicitly specify a Tenant while being implicitly 2115 associated with a different Tenant. 2117 4.1.1. URL Prefix Example 2119 https://www.example.com/Tenants/{tenant_id}/v1/Users 2121 4.1.2. Subdomain Example 2123 https://{tenant_id}.example.com/v1/Groups 2125 4.1.3. HTTP Header 2127 The Service Provider may recognize a {tenant_id} provided by the 2128 Consumer in the HTTP Header "SCIM_TENANT_ID" as the indicator of the 2129 desired target Tenant. 2131 In all of these methods, the {tenant_id} is a unique identifier for 2132 the Tenant as defined by the Service Provider. 2134 4.2. SCIM Identifiers with Multiple Tenants 2136 Considerations for a Multi-Tenant Implementation: 2138 The Service Provider may choose to implement SCIM ids which are 2139 unique across all Resources for all Tenants, but this is not 2140 required. 2142 The externalId, defined by the Consumer, is required to be unique 2143 ONLY within the Resources associated with the associated Tenant. 2145 5. Security Considerations 2147 The SCIM Protocol is based on HTTP and thus subject to the security 2148 considerations found in Section 15 of [RFC2616]. SCIM Resources 2149 (e.g., Users and Groups) can contain sensitive information. 2150 Therefore, SCIM Consumers and Service Providers MUST implement TLS. 2151 Which version(s) ought to be implemented will vary over time, and 2152 depend on the widespread deployment and known security 2153 vulnerabilities at the time of implementation. At the time of this 2154 writing, TLS version 1.2 [RFC5246 [7]] is the most recent version, 2155 but has very limited actual deployment, and might not be readily 2156 available in implementation toolkits. TLS version 1.0 [RFC2246 [7]] 2157 is the most widely deployed version, and will give the broadest 2158 interoperability. 2160 6. Contributors 2162 Samuel Erdtman (samuel@erdtman.se) 2164 Patrick Harding (pharding@pingidentity.com) 2166 7. Acknowledgments 2168 The editor would like to thank the participants in the the SCIM 2169 working group for their support of this specification. 2171 Authors' Addresses 2173 Trey Drake (editor) 2174 UnboundID 2176 Email: trey.drake@unboundid.com 2178 Chuck Mortimore 2179 SalesForce 2181 Email: cmortimore@salesforce.com 2183 Morteza Ansari 2184 Cisco 2186 Email: morteza.ansari@cisco.com 2188 Kelly Grizzle 2189 SailPoint 2191 Email: kelly.grizzle@sailpoint.com 2193 Erik Wahlstroem 2194 Technology Nexus 2196 Email: erik.wahlstrom@nexussafe.com