idnits 2.17.1 draft-ietf-scim-api-03.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 : ---------------------------------------------------------------------------- ** 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 service | | | Integer. | provider MUST not return more | | | Specifies the | results than specified though | | | desired maximum | MAY return fewer results. If | | | number of search | unspecified, the maximum number | | | results per page; | of results is set by the service | | | e.g., 10. | provider. | +------------+-------------------+----------------------------------+ == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Clients request resource removal via DELETE. Service providers MAY choose not to permanently delete the resource, but MUST return a 404 error code for all operations associated with the previously deleted Id. Service providers MUST also omit the resource from future query results. In addition the service provider MUST not consider the deleted resource in conflict calculation. For example if a User resource is deleted, a CREATE request for a User resource with the same userName as the previously deleted resource should not fail with a 409 error due to userName conflict. -- The document date (February 12, 2014) is 3719 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: 'RFC2246' is defined on line 2289, but no explicit reference was found in the text == Unused Reference: 'RFC5246' is defined on line 2302, but no explicit reference was found in the text == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-25 ** Downref: Normative reference to an Experimental draft: draft-reschke-http-status-308 (ref. 'I-D.reschke-http-status-308') ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 7 errors (**), 0 flaws (~~), 6 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group K. Grizzle 3 Internet-Draft SailPoint 4 Intended status: Standards Track P. Hunt, Ed. 5 Expires: August 16, 2014 Oracle 6 M. Ansari 7 Cisco 8 E. Wahlstroem 9 Technology Nexus 10 C. Mortimore 11 Salesforce 12 February 12, 2014 14 System for Cross-Domain Identity Management:Protocol 15 draft-ietf-scim-api-03 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 August 16, 2014. 48 Copyright Notice 50 Copyright (c) 2014 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 66 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3 67 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3 68 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 69 2. Authentication and Authorization . . . . . . . . . . . . . . 3 70 3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 71 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 6 72 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 7 73 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 7 74 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 7 75 3.2.2. List/Query Resources . . . . . . . . . . . . . . . . 9 76 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 17 77 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 19 78 3.3.1. Modifying with PUT . . . . . . . . . . . . . . . . . 20 79 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 22 80 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 30 81 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 31 82 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 46 83 3.7. Additional retrieval query parameters . . . . . . . . . . 47 84 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 48 85 3.9. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 48 86 3.10. API Versioning . . . . . . . . . . . . . . . . . . . . . 50 87 3.11. Versioning Resources . . . . . . . . . . . . . . . . . . 50 88 3.12. HTTP Method Overloading . . . . . . . . . . . . . . . . . 52 89 4. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 52 90 4.1. Associating Clients to Tenants . . . . . . . . . . . . . 53 91 4.1.1. URL Prefix Example . . . . . . . . . . . . . . . . . 54 92 4.1.2. Subdomain Example . . . . . . . . . . . . . . . . . . 54 93 4.1.3. HTTP Header . . . . . . . . . . . . . . . . . . . . . 54 94 4.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 54 95 5. Security Considerations . . . . . . . . . . . . . . . . . . . 54 96 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 97 6.1. Normative References . . . . . . . . . . . . . . . . . . 55 98 6.2. Informative References . . . . . . . . . . . . . . . . . 55 99 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 56 100 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 56 101 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 56 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 57 104 1. Introduction and Overview 106 The SCIM Protocol is an application-level, REST protocol for 107 provisioning and managing identity data on the web. The protocol 108 supports creation, modification, retrieval, and discovery of core 109 identity resources; i.e., Users and Groups, as well as custom 110 resource extensions. 112 1.1. Intended Audience 114 This document is intended as a guide to SCIM API usage for both 115 identity service providers and clients. 117 1.2. Notational Conventions 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 121 document are to be interpreted as described in [RFC2119]. These 122 keywords are capitalized when used to unambiguously specify 123 requirements of the protocol or application features and behavior 124 that affect the interoperability and security of implementations. 125 When these words are not capitalized, they are meant in their 126 natural-language sense. 128 For purposes of readability examples are not URL encoded. 129 Implementers MUST percent encode URLs as described in Section 2.1 130 [RFC3896]. 132 1.3. Definitions 134 Base URL: The SCIM REST API is always relative to a Base URL. The 135 Base URL MUST NOT contain a query string as clients may append 136 additional path information and query parameters as part of 137 forming the request. Example: https://example.com/scim/v2/ 139 2. Authentication and Authorization 141 The SCIM protocol does not define a scheme for authentication and 142 authorization therefore implementers are free to choose mechanisms 143 appropriate to their use cases. The choice of authentication 144 mechanism will impact interoperability. It is RECOMMENDED that 145 clients be implemented in such a way that new authentication schemes 146 can be deployed. Implementers SHOULD support existing authentication 147 /authorization schemes. In particular, OAuth2[RFC6750] is 148 RECOMMENDED. Appropriate security considerations of the selected 149 authentication and authorization schemes SHOULD be taken. Because 150 this protocol uses HTTP response status codes as the primary means of 151 reporting the result of a request, servers are advised to respond to 152 unauthorized or unauthenticated requests using the 401 response code 153 in accordance with section 10.4.2 of Section 10.4.2 [RFC2616]. 155 All examples assume OAuth2 bearer token [RFC6750]; e.g., 157 GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 158 Host: example.com 159 Authorization: Bearer h480djs93hd8 161 The context of the request (i.e. the user for whom data is being 162 requested) MUST be inferred by service providers. 164 3. API 166 The SCIM protocol specifies well known endpoints and HTTP methods for 167 managing resources defined in the core schema; i.e., "User" and 168 "Group" resources correspond to "/Users" and "/Groups" respectively. 169 Service providers that support extended resources SHOULD define 170 resource endpoints using the established convention; pluralize the 171 resource name defined in the extended schema by appending an 's'. 172 Given there are cases where resource pluralization is ambiguous; 173 e.g., a resource named "Person" is legitimately "Persons" and 174 "People" clients SHOULD discover resource endpoints via the "/ 175 ResourceTypes" endpoint . 177 GET Retrieves a complete or partial resource. 179 POST Create new resource, perform an extended Search, or bulk modify 180 resources. 182 PUT Modifies a resource with a complete, client specified resource 183 (replace). 185 PATCH Modifies a resource with a set of client specified changes 186 (partial update). 188 DELETE Deletes a resource. 190 +------------+--------------------+---------------+-----------------+ 191 | Resource | Endpoint | Operations | Description | 192 +------------+--------------------+---------------+-----------------+ 193 | User | /Users | GET (Section | Retrieve/Add/Mo | 194 | | | 3.2.1), POST | dify Users | 195 | | | (Section | | 196 | | | 3.1), PUT | | 197 | | | (Section | | 198 | | | 3.3.1), PATCH | | 199 | | | (Section | | 200 | | | 3.3.2), | | 201 | | | DELETE | | 202 | | | (Section 3.4) | | 203 | Group | /Groups | GET (Section | Retrieve/Add/Mo | 204 | | | 3.2.1), POST | dify Groups | 205 | | | (Section | | 206 | | | 3.1), PUT | | 207 | | | (Section | | 208 | | | 3.3.1), PATCH | | 209 | | | (Section | | 210 | | | 3.3.2), | | 211 | | | DELETE | | 212 | | | (Section 3.4) | | 213 | Service | /ServiceProviderCo | GET (Section | Retrieve the | 214 | Provider C | nfigs | 3.2.1) | service | 215 | onfigurati | | | provider's | 216 | on | | | configuration | 217 | Resource | /ResourceTypes | GET (Section | Retrieve the | 218 | Type | | 3.2.1) | supported | 219 | | | | resource types | 220 | Schema | /Schemas | GET (Section | Retrieve a | 221 | | | 3.2.1) | resource's | 222 | | | | schema | 223 | Bulk | /Bulk | POST (Section | Bulk modify | 224 | | | 3.5) | resources | 225 | Search | [prefix]/.search | POST (Section | Perform a | 226 | | | 3.2.3) | search at | 227 | | | | system root or | 228 | | | | within a | 229 | | | | resource | 230 | | | | endpoint for | 231 | | | | one or more | 232 | | | | resource types | 233 | | | | using POST. | 234 +------------+--------------------+---------------+-----------------+ 236 Table 1: Defined endpoints 238 All requests to the service provider are made via Section 9 [RFC2616] 239 on a URL derived from the Base URL. Responses are returned in the 240 body of the HTTP response, formatted as JSON. Response and error 241 codes SHOULD be transmitted via the HTTP status code of the response 242 (if possible), and SHOULD also be specified in the body of the 243 response. 245 3.1. Creating Resources 247 To create new resources, clients send POST requests to the resource 248 endpoint; i.e., "/Users" or "/Groups". 250 Successful resource creation is indicated with a 201 ("Created") 251 response code. Upon successful creation, the response body MUST 252 contain the newly created resource. Since the server is free to 253 alter and/or ignore POSTed content, returning the full representation 254 can be useful to the client, enabling it to correlate the client and 255 server views of the new resource. When a resource is created, its 256 URI must be returned in the response Location header. 258 If the service provider determines creation of the requested resource 259 conflicts with existing resources; e.g., a "User" resource with a 260 duplicate "userName", the service provider MUST return a 409 error 261 and SHOULD indicate the conflicting attribute(s) in the body of the 262 response. 264 Below, the client sends a POST request containing a user 266 POST /Users HTTP/1.1 267 Host: example.com 268 Accept: application/json 269 Content-Type: application/json 270 Authorization: Bearer h480djs93hd8 271 Content-Length: ... 273 { 274 "schemas":["urn:scim:schemas:core:2.0:User"], 275 "userName":"bjensen", 276 "externalId":"bjensen", 277 "name":{ 278 "formatted":"Ms. Barbara J Jensen III", 279 "familyName":"Jensen", 280 "givenName":"Barbara" 281 } 282 } 283 The server signals a successful creation with a status code of 201. 284 The response includes a Location header indicating the User URI, and 285 a representation of that user in the body of the response. 287 HTTP/1.1 201 Created 288 Content-Type: application/json 289 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 290 ETag: W/"e180ee84f0671b1" 292 { 293 "schemas":["urn:scim:schemas:core:2.0:User"], 294 "id":"2819c223-7f76-453a-919d-413861904646", 295 "externalId":"bjensen", 296 "meta":{ 297 "resourceType":"User", 298 "created":"2011-08-01T21:32:44.882Z", 299 "lastModified":"2011-08-01T21:32:44.882Z", 300 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 301 "version":"W\/\"e180ee84f0671b1\"" 302 }, 303 "name":{ 304 "formatted":"Ms. Barbara J Jensen III", 305 "familyName":"Jensen", 306 "givenName":"Barbara" 307 }, 308 "userName":"bjensen" 309 } 311 3.1.1. Resource Types 313 When adding a resource to a specific endpoint, the meta attribute 314 "resourceType" SHALL be set by the service provider to the 315 corresponding resource Type for the endpoint. For example, "/Users" 316 will set "resourceType" to "User", and "/Groups" will set 317 "resourceType" to "Group". 319 3.2. Retrieving Resources 321 "User" and "Group" resources are retrieved via opaque, unique URLs or 322 via Query. Service providers MAY choose to respond with a sub-set of 323 resource attributes, though MUST minimally return the resource id and 324 meta attributes. 326 3.2.1. Retrieving a known Resource 328 To retrieve a known resource, clients send GET requests to the 329 resource endpoint; e.g., "/Users/{id}" or "/Groups/{id}". 331 If the resource exists the server responds with a status code of 200 332 and includes the result in the body of the response. 334 The below example retrieves a single User via the "/Users" endpoint. 336 GET /Users/2819c223-7f76-453a-919d-413861904646 337 Host: example.com 338 Accept: application/json 339 Authorization: Bearer h480djs93hd8 341 The server responds with: 343 HTTP/1.1 200 OK 344 Content-Type: application/json 345 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 346 ETag: W/"f250dd84f0671c3" 348 { 349 "schemas":["urn:scim:schemas:core:2.0:User"], 350 "id":"2819c223-7f76-453a-919d-413861904646", 351 "externalId":"bjensen", 352 "meta":{ 353 "resourceType":"User", 354 "created":"2011-08-01T18:29:49.793Z", 355 "lastModified":"2011-08-01T18:29:49.793Z", 356 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 357 "version":"W\/\"f250dd84f0671c3\"" 358 }, 359 "name":{ 360 "formatted":"Ms. Barbara J Jensen III", 361 "familyName":"Jensen", 362 "givenName":"Barbara" 363 }, 364 "userName":"bjensen", 365 "phoneNumbers":[ 366 { 367 "value":"555-555-8377", 368 "type":"work" 369 } 370 ], 371 "emails":[ 372 { 373 "value":"bjensen@example.com", 374 "type":"work" 375 } 376 ] 377 } 378 3.2.2. List/Query Resources 380 SCIM defines a standard set of operations that can be used to filter, 381 sort, and paginate response results. The operations are specified by 382 adding query parameters to the resource's endpoint. Service 383 providers MAY support additional query parameters not specified here, 384 and Providers SHOULD ignore any query parameters they don't 385 recognize. 387 List and query responses MUST be identified using the following URI: 388 "urn:scim:schemas:core:2.0:ListResponse". The following attributes 389 are defined for list and query responses: 391 totalResults The total number of results returned by the list or 392 query operation. This may not be equal to the number of elements 393 in the resources attribute of the list response if pagination 394 (Section 3.2.2.4) is requested. REQUIRED. 396 Resources A multi-valued list of complex objects containing the 397 requested resources. This may be a subset of the full set of 398 resources if pagination (Section 3.2.2.4) is requested. REQUIRED. 400 startIndex The 1-based index of the first result in the current set 401 of list results. REQUIRED if pagination (Section 3.2.2.4) is 402 requested. 404 itemsPerPage The number of resources returned in a list response 405 page. REQUIRED if pagination (Section 3.2.2.4) is requested. 407 The below example returns the userName for all Users: 409 GET /Users?attributes=userName 410 Host: example.com 411 Accept: application/json 412 Authorization: Bearer h480djs93hd8 413 HTTP/1.1 200 OK 414 Content-Type: application/json 416 { 417 "schemas":["urn:scim:schemas:core:2.0:ListResponse"], 418 "totalResults":2, 419 "Resources":[ 420 { 421 "userName":"bjensen" 422 }, 423 { 424 "userName":"jsmith" 425 } 426 ] 427 } 429 3.2.2.1. Query Endpoints 431 Queries MAY be performed against a SCIM resource object or a resource 432 type endpoint. For example: 434 "/Users/{userid}" 436 "/Users" 438 "/Groups" 440 A server MAY support searches against the server root (e.g. "/"). A 441 search against a server root indicates that ALL resources within the 442 server SHALL be included subject to filtering. A filter expression 443 using "meta.resourceType" MAY be used to restrict results to one or 444 more specific resource types (e.g. "User"). 446 When processing search operations across endpoints that include more 447 than one SCIM resource type (e.g. a search from the server root 448 endpoint), filters MUST be processed in the same fashion as outlined 449 in Section 3.2.2.2. For filtered attributes that are not part of a 450 particular resource type, the service provider SHALL treat the 451 attribute as if there is no attribute value. For example, a presence 452 or equality filter for an undefined attribute evaluates as FALSE. 454 3.2.2.2. Filtering 456 Filtering is OPTIONAL. Clients may request a subset of resources by 457 specifying the 'filter' URL query parameter containing a filter 458 expression. When specified only those resources matching the filter 459 expression SHALL be returned. The expression language that is used 460 in the filter parameter supports references to attributes and 461 literals. The literal values can be strings enclosed in double 462 quotes, numbers, date times enclosed in double quotes, and Boolean 463 values; i.e., true or false. String literals MUST be valid 464 [RFC4627]. 466 The attribute name and attribute operator are case insensitive. For 467 example, the following two expressions will evaluate to the same 468 logical value: 470 filter=userName Eq "john" 472 filter=Username eq "john" 474 The filter parameter MUST contain at least one valid Boolean 475 expression. Each expression MUST contain an attribute name followed 476 by an attribute operator and optional value. Multiple expressions 477 MAY be combined using the two logical operators. Furthermore 478 expressions can be grouped together using "()". 480 The operators supported in the expression are listed in the following 481 table. 483 +----------+-------------+------------------------------------------+ 484 | Operator | Description | Behavior | 485 +----------+-------------+------------------------------------------+ 486 | eq | equal | The attribute and operator values must | 487 | | | be identical for a match. | 488 | ne | not equal | The attribute and operator values are | 489 | | | not identical. | 490 | co | contains | The entire operator value must be a | 491 | | | substring of the attribute value for a | 492 | | | match. | 493 | sw | starts with | The entire operator value must be a | 494 | | | substring of the attribute value, | 495 | | | starting at the beginning of the | 496 | | | attribute value. This criterion is | 497 | | | satisfied if the two strings are | 498 | | | identical. | 499 | ew | ends with | The entire operator value must be a | 500 | | | substring of the attribute value, | 501 | | | matching at the end of the attribute | 502 | | | value. This criterion is satisfied if | 503 | | | the two strings are identical. | 504 | pr | present | If the attribute has a non-empty value, | 505 | | (has value) | or if it contains a non-empty node for | 506 | | | complex attributes there is a match. | 507 | gt | greater | If the attribute value is greater than | 508 | | than | operator value, there is a match. The | 509 | | | actual comparison is dependent on the | 510 | | | attribute type. For string attribute | 511 | | | types, this is a lexicographical | 512 | | | comparison and for DateTime types, it is | 513 | | | a chronological comparison. | 514 | ge | greater | If the attribute value is greater than | 515 | | than or | or equal to the operator value, there is | 516 | | equal | a match. The actual comparison is | 517 | | | dependent on the attribute type. For | 518 | | | string attribute types, this is a | 519 | | | lexicographical comparison and for | 520 | | | DateTime types, it is a chronological | 521 | | | comparison. | 522 | lt | less than | If the attribute value is less than | 523 | | | operator value, there is a match. The | 524 | | | actual comparison is dependent on the | 525 | | | attribute type. For string attribute | 526 | | | types, this is a lexicographical | 527 | | | comparison and for DateTime types, it is | 528 | | | a chronological comparison. | 529 | le | less than | If the attribute value is less than or | 530 | | or equal | equal to the operator value, there is a | 531 | | | match. The actual comparison is | 532 | | | dependent on the attribute type. For | 533 | | | string attribute types, this is a | 534 | | | lexicographical comparison and for | 535 | | | DateTime types, it is a chronological | 536 | | | comparison. | 537 +----------+-------------+------------------------------------------+ 539 Table 2: Attribute Operators 541 +----------+-------------+------------------------------------------+ 542 | Operator | Description | Behavior | 543 +----------+-------------+------------------------------------------+ 544 | and | Logical And | The filter is only a match if both | 545 | | | expressions evaluate to true. | 546 | or | Logical or | The filter is a match if either | 547 | | | expression evaluates to true. | 548 | not | Not | The filter is a match if the expression | 549 | | function | evaluates to false. | 550 +----------+-------------+------------------------------------------+ 552 Table 3: Logical Operators 554 +----------+-------------+------------------------------------------+ 555 | Operator | Description | Behavior | 556 +----------+-------------+------------------------------------------+ 557 | () | Precedence | Boolean expressions may be grouped using | 558 | | grouping | parentheses to change the standard order | 559 | | | of operations; i.e., evaluate OR logical | 560 | | | operators before logical AND operators. | 561 | [] | Complex | Service providers MAY support complex | 562 | | attribute | filters where expressions MUST be | 563 | | filter | applied to the same value of a parent | 564 | | grouping | attribute specified immediately before | 565 | | | the left square bracket ("["). The | 566 | | | expression within square brackets ("[" | 567 | | | and "]") MUST be a valid filter | 568 | | | expression based upon sub-attributes of | 569 | | | the parent attribute. Nested expressions | 570 | | | MAY be used. See examples below. | 571 +----------+-------------+------------------------------------------+ 573 Table 4: Grouping Operators 575 Filters MUST be evaluated using standard order of operations 576 [Order-Operations]. Attribute operators have the highest precedence, 577 followed by the grouping operator (i.e, parentheses), followed by the 578 logical AND operator, followed by the logical OR operator. 580 If the specified attribute in a filter expression is a multi-valued 581 attribute, the resource MUST match if any of the instances of the 582 given attribute match the specified criterion; e.g. if a User has 583 multiple emails values, only one has to match for the entire User to 584 match. For complex attributes, a fully qualified Sub-Attribute MUST 585 be specified using standard attribute notation (Section 3.8). For 586 example, to filter by userName the parameter value is userName and to 587 filter by first name, the parameter value is name.givenName. 589 Providers MAY support additional filter operations if they choose. 590 Providers MUST decline to filter results if the specified filter 591 operation is not recognized and return a HTTP 400 error with an 592 appropriate human readable response. For example, if a client 593 specified an unsupported operator named 'regex' the service provider 594 should specify an error response description identifying the client 595 error; e.g., 'The operator 'regex' is not supported.' 597 String type attributes are case insensitive by default unless the 598 attribute type is defined as a caseExact string. Attribute operators 599 'eq', 'co', and 'sw' MUST perform caseIgnore matching for all string 600 attributes unless the attribute is defined as caseExact. By default 601 all string attributes are caseIgnore. 603 Clients MAY search by schema or schema extensions by using a filter 604 expression including the "schemas" attribute. 606 The following are examples of valid filters. Some attributes (e.g. 607 rooms and rooms.number) are hypothetical extensions and are not part 608 of SCIM core schema: 610 filter=userName eq "bjensen" 612 filter=name.familyName co "O'Malley" 614 filter=userName sw "J" 616 filter=title pr 618 filter=meta.lastModified gt "2011-05-13T04:42:34Z" 620 filter=meta.lastModified ge "2011-05-13T04:42:34Z" 622 filter=meta.lastModified lt "2011-05-13T04:42:34Z" 624 filter=meta.lastModified le "2011-05-13T04:42:34Z" 626 filter=title pr and userType eq "Employee" 628 filter=title pr or userType eq "Intern" 630 filter=schemas eq "urn:scim:schemas:extension:enterprise:2.0:User" 632 filter=userType eq "Employee" and (emails co "example.com" or emails 633 co "example.org") 635 filter=userType ne "Employee" and not (emails co "example.com" or 636 emails co "example.org") 638 filter=userType eq "Employee" and (emails.type eq "work") 640 filter=userType eq "Employee" and emails[type eq "work" and 641 value co "@example.com"] 643 filter=emails[type eq "work" and value co "@example.com"] or ims[type 644 eq "xmpp" and value co "@foo.com"] 646 filter=addresses[state eq "CA" and rooms[type eq "bedroom" and 647 number gt 2]] 649 3.2.2.3. Sorting 651 Sort is OPTIONAL. Sorting allows clients to specify the order in 652 which resources are returned by specifying a combination of sortBy 653 and sortOrder URL parameters. 655 sortBy: The sortBy parameter specifies the attribute whose value 656 SHALL be used to order the returned responses. If the sortBy 657 attribute corresponds to a singular attribute, resources are 658 sorted according to that attribute's value; if it's a multi-valued 659 attribute, resources are sorted by the value of the primary 660 attribute, if any, or else the first value in the list, if any. 661 If the attribute is complex the attribute name must be a path to a 662 sub-attribute in standard attribute notation (Section 3.8) ; e.g., 663 "sortBy=name.givenName". For all attribute types, if there is no 664 data for the specified "sortBy" value they are sorted via the 665 "sortOrder" parameter; i.e., they are ordered last if ascending 666 and first if descending. 668 sortOrder: The order in which the sortBy parameter is applied. 669 Allowed values are "ascending" and "descending". If a value for 670 sortBy is provided and no sortOrder is specified, the sortOrder 671 SHALL default to ascending. String type attributes are case 672 insensitive by default unless the attribute type is defined as a 673 case exact string. "sortOrder" MUST sort according to the 674 attribute type; i.e., for "caseIgnore" attributes, sort the result 675 using case insensitive, unicode alphabetic sort order, with no 676 specific locale implied and for caseExact attribute types, sort 677 the result using case sensitive, Unicode alphabetic sort order. 679 3.2.2.4. Pagination 681 Pagination parameters can be used together to "page through" large 682 numbers of resources so as not to overwhelm the client or service 683 provider. Pagination is not session based hence clients SHOULD never 684 assume repeatable results. For example, a request for a list of 10 685 resources beginning with a startIndex of 1 may return different 686 results when repeated as a resource in the original result could be 687 deleted or new ones could be added in-between requests. Pagination 688 parameters and general behavior are derived from the OpenSearch 689 Protocol [OpenSearch]. 691 The following table describes the URL pagination parameters. 693 +------------+-------------------+----------------------------------+ 694 | Parameter | Description | Default | 695 +------------+-------------------+----------------------------------+ 696 | startIndex | The 1-based index | 1 | 697 | | of the first | | 698 | | search result. | | 699 | count | Non-negative | None. When specified the service | 700 | | Integer. | provider MUST not return more | 701 | | Specifies the | results than specified though | 702 | | desired maximum | MAY return fewer results. If | 703 | | number of search | unspecified, the maximum number | 704 | | results per page; | of results is set by the service | 705 | | e.g., 10. | provider. | 706 +------------+-------------------+----------------------------------+ 708 Table 5: Pagination Request parameters 710 The following table describes the query response pagination 711 attributes specified by the service provider. 713 +--------------+----------------------------------------------------+ 714 | Element | Description | 715 +--------------+----------------------------------------------------+ 716 | itemsPerPage | Non-negative Integer. Specifies the number of | 717 | | search results returned in a query response page; | 718 | | e.g., 10. | 719 | totalResults | Non-negative Integer. Specifies the total number | 720 | | of results matching the client query; e.g., 1000. | 721 | startIndex | The 1-based index of the first result in the | 722 | | current set of search results; e.g., 1. | 723 +--------------+----------------------------------------------------+ 725 Table 6: Pagination Response Elements 727 For example, to retrieve the first 10 Users set the startIndex to 1 728 and the count to 10. 730 GET /Users?startIndex=1&count=10 731 Host: example.com 732 Accept: application/json 733 Authorization: Bearer h480djs93hd8 734 { 735 "totalResults":100, 736 "itemsPerPage":10, 737 "startIndex":1, 738 "schemas":["urn:scim:schemas:core:2.0"], 739 "Resources":[{ 740 ... 741 }] 742 } 744 Given the example above, to continue paging set the startIndex to 11 745 and re-fetch; i.e., /Users?startIndex=11&count=10 747 3.2.3. Querying Resources Using HTTP POST 749 Clients MAY execute queries without passing parameters on the URL by 750 using the HTTP POST verb combined with the '/.search' path extension. 751 The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL 752 be used to indicate the HTTP POST verb is intended to be a query 753 operation. 755 To create a new search result set, a SCIM client sends an HTTP POST 756 request to the desired SCIM resource endpoint (ending in '/.search'). 757 The body of the POST request MAY include any of the parameters as 758 defined in Section 3.2.2. 760 Search requests MUST be identified using the following URI: 761 'urn:scim:schemas:core:2.0:SearchRequest'. The following attributes 762 are defined for search requests: 764 attributes A multi-valued list of strings indicating the names of 765 resource attributes to return in the response. Attribute names 766 MUST be in standard attribute notation (Section 3.8) form. See 767 additional retrieval query parameters (Section 3.7). OPTIONAL. 769 filter The filter string used to request a subset of resources. The 770 filter string MUST be a valid filter (Section 3.2.2.2) expression. 771 OPTIONAL. 773 sortBy A string indicating the attribute whose value SHALL be used 774 to order the returned responses. The sortBy attribute MUST be in 775 standard attribute notation (Section 3.8) form. See sorting 776 (Section 3.2.2.3). OPTIONAL. 778 sortOrder A string indicating the order in which the sortBy 779 parameter is applied. Allowed values are "ascending" and 780 "descending". See sorting (Section 3.2.2.3). OPTIONAL. 782 startIndex An integer indicating the 1-based index of the first 783 search result. See pagination (Section 3.2.2.4). OPTIONAL. 785 count An integer indicating the desired maximum number of search 786 results per page. See pagination (Section 3.2.2.4). OPTIONAL. 788 After receiving a HTTP POST request, a response is returned as 789 specified in Section 3.2.2. 791 The following example shows an HTTP POST Search request with search 792 parameters attributes, filter, and count included: 794 POST /.search 795 Host: example.com 796 Accept: application/json 797 Content-Type: application/json 798 Authorization: Bearer h480djs93hd8 799 Content-Length: ... 801 { 802 "schemas": ["urn:scim:schemas:core:2.0:SearchRequest"], 803 "attributes": ["displayName", "userName"], 804 "filter": "displayName sw \"smith\"", 805 "startIndex": 1, 806 "count": 10 807 } 809 Figure 1: Example POST Search Request 811 A search response is shown with the first page of results. For 812 brevity reasons, only two matches are shown: one User and one Group. 814 HTTP/1.1 200 OK 815 Content-Type: application/json 816 Location: https://example.com/.search 817 { 818 "schemas": ["urn:scim:schemas:core:2.0:ListResponse"], 819 "totalResults":100, 820 "itemsPerPage":10, 821 "startIndex":1, 822 "Resources":[ 823 { 824 "meta":{ 825 "location": 826 "https://example.com/Users/2819c223-7f76-413861904646", 827 "resourceType":"User", 828 "lastModified": ... 829 }, 830 "userName":"jsmith", 831 "displayName":"Smith, James" 832 }, 833 { 834 "meta":{ 835 "location": 836 "https://example.com/Groups/c8596b90-7539-4f20968d1908", 837 "resourceType":"Group", 838 "lastModified": ... 839 }, 840 "displayName":"Smith Family" 841 }, 842 ... 843 ] 844 } 846 Figure 2: Example POST Search Response 848 3.3. Modifying Resources 850 Resources can be modified in whole or in part via PUT or PATCH, 851 respectively. Implementers MUST support PUT as specified in 852 Section 9.6 [RFC2616] . Resources such as Groups may be very large 853 hence implementers SHOULD support PATCH [RFC5789] to enable partial 854 resource modifications. 856 3.3.1. Modifying with PUT 858 PUT performs a full update. Clients MAY retrieve the entire resource 859 in advance, add the desired modifications and use HTTP PUT which will 860 overwrite all previously stored data. Since the PUT request performs 861 a full update, clients MAY send attributes of the retrieved resource 862 and the service provider MUST process according to attribute 863 mutability as follows: 865 readWrite, writeOnly Any values provided SHALL replace the existing 866 attribute values. Omitting the attribute or specific values means 867 the attribute or specific value SHALL be removed; 869 immutable If values are provided for elements already set in the 870 attribute they MUST match existing data or an error is returned. 871 If the service provider has no existing values, a new value(s) MAY 872 be specified; and, 874 readOnly Any values provided (e.g. meta.resourceType) SHALL be 875 ignored. 877 If an attribute is "required", the client MUST specify the attribute 878 in the PUT request. 880 If a value provided for an immutable attribute with an existing value 881 is NOT matched, the server SHALL respond with an HTTP response code 882 of 400 and an apprpriate human readable message indicating an attempt 883 to change an immutable attribute. 885 Unless otherwise specified a successful PUT operation returns a 200 886 OK response code and the entire resource within the response body, 887 enabling the client to correlate the client's and Provider's views of 888 the updated resource. Example: 890 PUT /Users/2819c223-7f76-453a-919d-413861904646 891 Host: example.com 892 Accept: application/json 893 Content-Type: application/json 894 Authorization: Bearer h480djs93hd8 895 If-Match: W/"a330bc54f0671c9" 897 { 898 "schemas":["urn:scim:schemas:core:2.0:User"], 899 "id":"2819c223-7f76-453a-919d-413861904646", 900 "userName":"bjensen", 901 "externalId":"bjensen", 902 "name":{ 903 "formatted":"Ms. Barbara J Jensen III", 904 "familyName":"Jensen", 905 "givenName":"Barbara", 906 "middleName":"Jane" 907 }, 908 "emails":[ 909 { 910 "value":"bjensen@example.com" 911 }, 912 { 913 "value":"babs@jensen.org" 914 } 915 ] 916 } 918 The service responds with the entire, updated User 920 HTTP/1.1 200 OK 921 Content-Type: application/json 922 ETag: W/"b431af54f0671a2" 923 Location:"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646" 924 { 925 "schemas":["urn:scim:schemas:core:2.0:User"], 926 "id":"2819c223-7f76-453a-919d-413861904646", 927 "userName":"bjensen", 928 "externalId":"bjensen", 929 "name":{ 930 "formatted":"Ms. Barbara J Jensen III", 931 "familyName":"Jensen", 932 "givenName":"Barbara", 933 "middleName":"Jane" 934 }, 935 "emails":[ 936 { 937 "value":"bjensen@example.com" 938 }, 939 { 940 "value":"babs@jensen.org" 941 } 942 ], 943 "meta": { 944 "resourceType":"User", 945 "created":"2011-08-08T04:56:22Z", 946 "lastModified":"2011-08-08T08:00:12Z", 947 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 948 "version":"W\/\"b431af54f0671a2\"" 949 } 950 } 952 3.3.2. Modifying with PATCH 954 PATCH is OPTIONAL. PATCH enables clients to send only those 955 attributes requiring modification, reducing network and processing 956 overhead. Attributes may be deleted, replaced, merged, or added in a 957 single request. 959 The body of a PATCH request MUST contain a partial resource with the 960 desired modifications. The server MUST return either a 200 OK 961 response code and the entire resource (subject to the "attributes" 962 query parameter - see Additional Retrieval Query Parameters 963 (Section 3.7)) within the response body, or a 204 No Content response 964 code and the appropriate response headers for a successful PATCH 965 request. The server MUST return a 200 OK if the "attributes" 966 parameter is specified on the request. 968 The server MUST process a PATCH request by first removing any 969 attributes specified in the meta.attributes Sub-Attribute (if 970 present) and then merging the attributes in the PATCH request body 971 into the resource. 973 The meta.attributes Sub-Attribute MAY contain a list of attributes to 974 be removed from the resource. If the PATCH request body contains an 975 attribute that is present in the meta.attributes list, the attribute 976 on the resource is replaced with the value from the PATCH body. If 977 the attribute is complex the attribute name must be a path to a Sub- 978 Attribute in standard attribute notation (Section 3.8); e.g., 979 name.givenName. 981 Attributes that exist in the PATCH request body but not in the 982 meta.attributes Sub-Attribute will be either be updated or added to 983 the resource according to the following rules. 985 Singular attributes: Singular attributes in the PATCH request body 986 replace the attribute on the resource. 988 Complex attributes: Complex Sub-Attribute values in the PATCH 989 request body are merged into the complex attribute on the 990 resource. 992 Multi-valued attributes: An attribute value in the PATCH request 993 body is added to the value collection if the value does not exist 994 and merged if a matching value is present. Values are matched by 995 comparing the value Sub-Attribute from the PATCH request body to 996 the value Sub-Attribute of the resource. Attributes that do not 997 have a value Sub-Attribute; e.g., addresses, or do not have unique 998 value Sub-Attributes cannot be matched and must instead be deleted 999 then added. Specific values can be removed from a resource by 1000 adding an "operation" Sub-Attribute with the value "delete" to the 1001 attribute in the PATCH request body. As with adding/updating 1002 attribute value collections, the value to delete is determined by 1003 comparing the value Sub-Attribute from the PATCH request body to 1004 the value Sub-Attribute of the resource. Attributes that do not 1005 have a value Sub-Attribute or that have a non-unique value Sub- 1006 Attribute are matched by comparing all Sub-Attribute values from 1007 the PATCH request body to the Sub-Attribute values of the 1008 resource. A delete operation is ignored if the attribute's name 1009 is in the meta.attributes list. If the requested value to delete 1010 does not match a unique value on the resource the server MAY 1011 return a HTTP 400 error. 1013 The following example shows how to add a member to a group: 1015 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1016 Host: example.com 1017 Accept: application/json 1018 Content-Type: application/json 1019 Authorization: Bearer h480djs93hd8 1020 If-Match: W/"a330bc54f0671c9" 1022 { 1023 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1024 "members": [ 1025 { 1026 "display": "Babs Jensen", 1027 "$ref": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 1028 "value": "2819c223-7f76-453a-919d-413861904646" 1029 } 1030 ] 1031 } 1033 The "display" Sub-Attribute in this request is optional since the 1034 value attribute uniquely identifies the user to be added. If the 1035 user was already a member of this group, no changes should be made to 1036 the resource and a success response should be returned. The server 1037 responds with either the entire updated Group or no response body: 1039 HTTP/1.1 204 No Content 1040 Authorization: Bearer h480djs93hd8 1041 ETag: W/"b431af54f0671a2" 1042 Location: "https://example.com/v2/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" 1044 The following example shows how to remove a member from a group. As 1045 with the previous example, the "display" Sub-Attribute is optional. 1046 If the user was not a member of this group, no changes should be made 1047 to the resource and a success response should be returned. 1049 Note that server responses have been omitted for the rest of the 1050 PATCH examples. 1052 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1053 Host: example.com 1054 Accept: application/json 1055 Content-Type: application/json 1056 Authorization: Bearer h480djs93hd8 1057 If-Match: W/"a330bc54f0671c9" 1059 { 1060 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1061 "members": [ 1062 { 1063 "display": "Babs Jensen", 1064 "$ref": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 1065 "value": "2819c223-7f76-453a-919d-413861904646", 1066 "operation": "delete" 1067 } 1068 ] 1069 } 1071 The following example shows how to remove all members from a group: 1073 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1074 Host: example.com 1075 Accept: application/json 1076 Content-Type: application/json 1077 Authorization: Bearer h480djs93hd8 1078 If-Match: W/"a330bc54f0671c9" 1080 { 1081 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1082 "meta": { 1083 "attributes": [ 1084 "members" 1085 ] 1086 } 1087 } 1089 The following example shows how to replace all of the members of a 1090 group with a different members list: 1092 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1093 Host: example.com 1094 Accept: application/json 1095 Content-Type: application/json 1096 Authorization: Bearer h480djs93hd8 1097 If-Match: W/"a330bc54f0671c9" 1099 { 1100 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1101 "meta": { 1102 "attributes": [ 1103 "members" 1104 ] 1105 }, 1106 "members": [ 1107 { 1108 "display": "Babs Jensen", 1109 "$ref": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 1110 "value": "2819c223-7f76-453a-919d-413861904646" 1111 }, 1112 { 1113 "display": "James Smith", 1114 "$ref": "https://example.com/v2/Users/08e1d05d-121c-4561-8b96-473d93df9210", 1115 "value": "08e1d05d-121c-4561-8b96-473d93df9210" 1116 } 1117 ] 1118 } 1120 The following example shows how to add a member to and remove a 1121 member from a Group in a single request: 1123 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1124 Host: example.com 1125 Accept: application/json 1126 Content-Type: application/json 1127 Authorization: Bearer h480djs93hd8 1128 If-Match: W/"a330bc54f0671c9" 1130 { 1131 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1132 "members": [ 1133 { 1134 "display": "Babs Jensen", 1135 "$ref": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 1136 "value": "2819c223-7f76-453a-919d-413861904646", 1137 "operation": "delete" 1138 }, 1139 { 1140 "display": "James Smith", 1141 "$ref": "https://example.com/v2/Users/08e1d05d-121c-4561-8b96-473d93df9210", 1142 "value": "08e1d05d-121c-4561-8b96-473d93df9210" 1143 } 1144 ] 1145 } 1147 The following example shows how to change a User's primary email. If 1148 the User already has the email address, it is made the primary 1149 address and the current primary address (if present) is made non- 1150 primary. If the User does not already have the email address, it is 1151 added and made the primary address. 1153 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1154 Host: example.com 1155 Accept: application/json 1156 Content-Type: application/json 1157 Authorization: Bearer h480djs93hd8 1158 If-Match: W/"a330bc54f0671c9" 1160 { 1161 "schemas": ["urn:scim:schemas:core:2.0:User"], 1162 "emails": [ 1163 { 1164 "value": "bjensen@example.com", 1165 "primary": true 1166 } 1167 ] 1168 } 1169 The following example shows how to change a User's address. Since 1170 address does not have a value Sub-Attribute, the existing address 1171 must be removed and the modified address added. 1173 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1174 Host: example.com 1175 Accept: application/json 1176 Content-Type: application/json 1177 Authorization: Bearer h480djs93hd8 1178 If-Match: W/"a330bc54f0671c9" 1180 { 1181 "schemas": ["urn:scim:schemas:core:2.0:User"], 1182 "addresses": [ 1183 { 1184 "type": "work", 1185 "streetAddress": "100 Universal City Plaza", 1186 "locality": "Hollywood", 1187 "region": "CA", 1188 "postalCode": "91608", 1189 "country": "US", 1190 "formatted": "100 Universal City Plaza\nHollywood, CA 91608 US", 1191 "primary": true, 1192 "operation": "delete" 1193 }, 1194 { 1195 "type": "work", 1196 "streetAddress": "911 Universal City Plaza", 1197 "locality": "Hollywood", 1198 "region": "CA", 1199 "postalCode": "91608", 1200 "country": "US", 1201 "formatted": "911 Universal City Plaza\nHollywood, CA 91608 US", 1202 "primary": true 1203 } 1204 ] 1205 } 1207 The following example shows how to change a User's nickname: 1209 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1210 Host: example.com 1211 Accept: application/json 1212 Content-Type: application/json 1213 Authorization: Bearer h480djs93hd8 1214 If-Match: W/"a330bc54f0671c9" 1216 { 1217 "schemas": ["urn:scim:schemas:core:2.0:User"], 1218 "nickName": "Barbie" 1219 } 1221 The following example shows how to remove a User's nickname: 1223 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1224 Host: example.com 1225 Accept: application/json 1226 Content-Type: application/json 1227 Authorization: Bearer h480djs93hd8 1228 If-Match: W/"a330bc54f0671c9" 1230 { 1231 "schemas": ["urn:scim:schemas:core:2.0:User"], 1232 "meta": { 1233 "attributes": [ 1234 "nickName" 1235 ] 1236 } 1237 } 1239 The following example shows how to change a User's familyName. This 1240 only updates the familyName and formatted on the "name" complex 1241 attribute. Any other name Sub-Attributes on the resource remain 1242 unchanged. 1244 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1245 Host: example.com 1246 Accept: application/json 1247 Content-Type: application/json 1248 Authorization: Bearer h480djs93hd8 1249 If-Match: W/"a330bc54f0671c9" 1251 { 1252 "schemas": ["urn:scim:schemas:core:2.0:User"], 1253 "name": { 1254 "formatted": "Ms. Barbara J Jensen III", 1255 "familyName": "Jensen" 1256 } 1257 } 1259 The following example shows how to remove a complex Sub-Attribute and 1260 an extended schema attribute from a User. 1262 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1263 Host: example.com 1264 Accept: application/json 1265 Content-Type: application/json 1266 Authorization: Bearer h480djs93hd8 1267 If-Match: W/"a330bc54f0671c9" 1269 { 1270 "schemas": ["urn:scim:schemas:core:2.0:User"], 1271 "meta": { 1272 "attributes": [ 1273 "name.formatted", 1274 "urn:hr:schemas:user:age" 1275 ] 1276 } 1277 } 1279 3.4. Deleting Resources 1281 Clients request resource removal via DELETE. Service providers MAY 1282 choose not to permanently delete the resource, but MUST return a 404 1283 error code for all operations associated with the previously deleted 1284 Id. Service providers MUST also omit the resource from future query 1285 results. In addition the service provider MUST not consider the 1286 deleted resource in conflict calculation. For example if a User 1287 resource is deleted, a CREATE request for a User resource with the 1288 same userName as the previously deleted resource should not fail with 1289 a 409 error due to userName conflict. 1291 DELETE /Users/2819c223-7f76-453a-919d-413861904646 1292 Host: example.com 1293 Authorization: Bearer h480djs93hd8 1294 If-Match: W/"c310cd84f0281b7" 1296 In response to a successful delete, the server SHALL respond with 1297 successful HTTP status 204 (No Content). A non-normative example 1298 response: 1300 HTTP/1.1 204 No Content 1302 Example: client attempt to retrieve the previously deleted User 1304 GET /Users/2819c223-7f76-453a-919d-413861904646 1305 Host: example.com 1306 Authorization: Bearer h480djs93hd8 1308 Server Response: 1310 HTTP/1.1 404 NOT FOUND 1312 { 1313 "schemas": ["urn:scim:schemas:core:2.0:Error"], 1314 "Errors":[ 1315 { 1316 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 1317 "code":"404" 1318 } 1319 ] 1320 } 1322 3.5. Bulk 1324 Bulk is OPTIONAL. The bulk operation enables clients to send a 1325 potentially large collection of resource operations in a single 1326 request. The body of a a bulk operation contains a set of HTTP 1327 resource operations using one of the API supported HTTP methods; 1328 i.e., POST, PUT, PATCH or DELETE. 1330 Bulk requests are identified using the following URI: 1331 'urn:scim:schemas:core:2.0:BulkRequest'. Bulk responses are 1332 identified using the following URI: 1334 'urn:scim:schemas:core:2.0:BulkResponse'. Bulk requests and bulk 1335 responses share many attributes. Unless otherwise specified, each 1336 attribute below is present in both bulk requests and bulk responses. 1338 The following Singular Attribute is defined in addition to the common 1339 attributes defined in SCIM core schema. 1341 failOnErrors An Integer specifying the number of errors that the 1342 service provider will accept before the operation is terminated 1343 and an error response is returned. OPTIONAL in a request. Not 1344 valid in a response. 1346 The following Complex Multi-valued Attribute is defined in addition 1347 to the common attributes defined in core schema. 1349 Operations Defines operations within a bulk job. Each operation 1350 corresponds to a single HTTP request against a resource endpoint. 1351 REQUIRED. 1353 method The HTTP method of the current operation. Possible values 1354 are POST, PUT, PATCH or DELETE. REQUIRED. 1356 bulkId The transient identifier of a newly created resource, 1357 unique within a bulk request and created by the client. The 1358 bulkId serves as a surrogate resource id enabling clients to 1359 uniquely identify newly created resources in the Response and 1360 cross reference new resources in and across operations within a 1361 bulk request. REQUIRED when method is POST. 1363 version The current resource version. Version is REQUIRED if the 1364 service provider supports ETags and the method is PUT, DELETE, 1365 or PATCH. 1367 path The resource's relative path. If the method is POST the 1368 value must specify a resource type endpoint; e.g., /Users or / 1369 Groups whereas all other method values must specify the path to 1370 a specific resource; e.g., /Users/2819c223-7f76-453a- 1371 919d-413861904646. REQUIRED in a request. 1373 data The resource data as it would appear for a single POST, PUT 1374 or PATCH resource operation. REQUIRED in a request when method 1375 is POST, PUT and PATCH. 1377 location The resource endpoint URL. REQUIRED in a response, 1378 except in the event of a POST failure. 1380 status A complex type that contains information about the success 1381 or failure of one operation within the bulk job. REQUIRED in a 1382 response. 1384 code The HTTP response code that would have been returned if a 1385 a single HTTP request would have been used. REQUIRED. 1387 description A human readable error message. REQUIRED when an 1388 error occurred. 1390 If a bulk job is processed successfully the HTTP response code 200 OK 1391 MUST be returned, otherwise an appropriate HTTP error code MUST be 1392 returned. 1394 The service provider MUST continue performing as many changes as 1395 possible and disregard partial failures. The client MAY override 1396 this behavior by specifying a value for failOnErrors attribute. The 1397 failOnErrors attribute defines the number of errors that the service 1398 provider should accept before failing the remaining operations 1399 returning the response. 1401 To be able to reference a newly created resource the attribute bulkId 1402 MUST be specified when creating new resources. The bulkId is defined 1403 by the client as a surrogate identifier in a POST operation. The 1404 service provider MUST return the same bulkId together with the newly 1405 created resource. The bulkId can then be used by the client to map 1406 the service provider id with the bulkId of the created resource. 1408 There can be more then one operation per resource in each bulk job. 1409 The Service client MUST take notice of the unordered structure of 1410 JSON and the service provider can process operations in any order. 1411 For example, if the Service client sends two PUT operations in one 1412 request, the outcome is non-deterministic. 1414 The service provider response MUST include the result of all 1415 processed operations. A location attribute that includes the 1416 resource's end point MUST be returned for all operations excluding 1417 failed POSTs. The status attribute includes information about the 1418 success or failure of one operation within the bulk job. The 1419 attribute status MUST include the code attribute that holds the HTTP 1420 response code that would have been returned if a single HTTP request 1421 would have been used. If an error occurred the status MUST also 1422 include the description attribute containing a human readable 1423 explanation of the error. 1425 "status": { 1426 "code": "201" 1427 } 1429 The following is an example of a status in a failed operation. 1431 "status": { 1432 "code": "400", 1433 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1434 } 1436 The following example shows how to add, update, and remove a user. 1437 The failOnErrors attribute is set to '1' indicating the service 1438 provider should return on the first error. The POST operation's 1439 bulkId value is set to 'qwerty' enabling the client to match the new 1440 User with the returned resource id '92b725cd-9465-4e7d- 1441 8c16-01f8e146b87a'. 1443 POST /v2/Bulk 1444 Host: example.com 1445 Accept: application/json 1446 Content-Type: application/json 1447 Authorization: Bearer h480djs93hd8 1448 Content-Length: ... 1450 { 1451 "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], 1452 "failOnErrors":1, 1453 "Operations":[ 1454 { 1455 "method":"POST", 1456 "path":"/Users", 1457 "bulkId":"qwerty", 1458 "data":{ 1459 "schemas": ["urn:scim:schemas:core:2.0:User"], 1460 "userName":"Alice" 1461 } 1462 }, 1463 { 1464 "method":"PUT", 1465 "path":"/Users/b7c14771-226c-4d05-8860-134711653041", 1466 "version":"W\/\"3694e05e9dff591\"", 1467 "data":{ 1468 "schemas": ["urn:scim:schemas:core:2.0:User"], 1469 "id":"b7c14771-226c-4d05-8860-134711653041", 1470 "userName":"Bob" 1472 } 1473 }, 1474 { 1475 "method":"PATCH", 1476 "path":"/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1477 "version":"W\/\"edac3253e2c0ef2\"", 1478 "data":{ 1479 "schemas":["urn:scim:schemas:core:2.0:User"], 1480 "id":"5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1481 "userName":"Dave", 1482 "meta":{ 1483 "attributes":[ 1484 "nickName" 1485 ] 1486 } 1487 } 1488 }, 1489 { 1490 "method":"DELETE", 1491 "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1492 "version":"W\/\"0ee8add0a938e1a\"" 1493 } 1494 ] 1495 } 1497 The service provider returns the following response. 1499 HTTP/1.1 200 OK 1500 Content-Type: application/json 1502 { 1503 "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], 1504 "Operations": [ 1505 { 1506 "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1507 "method": "POST", 1508 "bulkId": "qwerty", 1509 "version": "W\/\"oY4m4wn58tkVjJxK\"", 1510 "status": { 1511 "code": "201" 1512 } 1513 }, 1514 { 1515 "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 1516 "method": "PUT", 1517 "version": "W\/\"huJj29dMNgu3WXPD\"", 1518 "status": { 1519 "code": "200" 1520 } 1521 }, 1522 { 1523 "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1524 "method": "PATCH", 1525 "version": "W\/\"huJj29dMNgu3WXPD\"", 1526 "status": { 1527 "code": "200" 1528 } 1529 }, 1530 { 1531 "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1532 "method": "DELETE", 1533 "status": { 1534 "code": "204" 1535 } 1536 } 1537 ] 1538 } 1540 The following response is returned if an error occurred when 1541 attempting to create the User 'Alice'. The service provider stops 1542 processing the bulk operation and immediately returns a response to 1543 the client. The response contains the error and any successful 1544 results prior to the error. 1546 HTTP/1.1 200 OK 1547 Content-Type: application/json 1549 { 1550 "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], 1551 "Operations": [ 1552 { 1553 "method": "POST", 1554 "bulkId": "qwerty", 1555 "status": { 1556 "code": "400", 1557 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1558 } 1559 } 1560 ] 1561 } 1563 If the failOnErrors attribute is not specified or the service 1564 provider has not reached the error limit defined by the client the 1565 service provider will continue to process all operations. The 1566 following is an example in which all operations failed. 1568 HTTP/1.1 200 OK 1569 Content-Type: application/json 1571 { 1572 "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], 1573 "Operations": [ 1574 { 1575 "method": "POST", 1576 "bulkId": "qwerty", 1577 "status": { 1578 "code": "400", 1579 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1580 } 1581 }, 1582 { 1583 "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 1584 "method": "PUT", 1585 "status": { 1586 "code": "412", 1587 "description": "Failed to update as user changed on the server since you last retrieved it." 1588 } 1589 }, 1590 { 1591 "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1592 "method": "PATCH", 1593 "status": { 1594 "code": "412", 1595 "description": "Failed to update as user changed on the server since you last retrieved it." 1596 } 1597 }, 1598 { 1599 "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1600 "method": "DELETE", 1601 "status": { 1602 "code": "404", 1603 "description": "Specified resource; e.g., User, does not exist." 1604 } 1605 } 1606 ] 1607 } 1609 The client can, within one bulk operation, create a new User, a new 1610 Group and add the newly created User to the newly created Group. In 1611 order to add the new User to the Group the client must use the 1612 surrogate id attribute, bulkId, to reference the User. The bulkId 1613 attribute value must be pre-pended with the literal "bulkId:"; e.g., 1614 if the bulkId is 'qwerty' the value is "bulkId:qwerty". The service 1615 provider MUST replace the string "bulkId:qwerty" with the permanent 1616 resource id once created. 1618 The following example creates a User with the userName 'Alice' and a 1619 Group with the displayName 'Tour Guides' with Alice as a member. 1621 POST /v2/Bulk 1622 Host: example.com 1623 Accept: application/json 1624 Content-Type: application/json 1625 Authorization: Bearer h480djs93hd8 1626 Content-Length: ... 1628 { 1629 "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], 1630 "Operations": [ 1631 { 1632 "method": "POST", 1633 "path": "/Users", 1634 "bulkId": "qwerty", 1635 "data": { 1636 "schemas": ["urn:scim:schemas:core:2.0:User"], 1637 "userName": "Alice" 1638 } 1639 }, 1640 { 1641 "method": "POST", 1642 "path": "/Groups", 1643 "bulkId": "ytrewq", 1644 "data": { 1645 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1646 "displayName": "Tour Guides", 1647 "members": [ 1648 { 1649 "type": "user", 1650 "value": "bulkId:qwerty" 1651 } 1652 ] 1653 } 1654 } 1655 ] 1656 } 1658 The service provider returns the following response. 1660 HTTP/1.1 200 OK 1661 Content-Type: application/json 1663 { 1664 "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], 1665 "Operations": [ 1666 { 1667 "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1668 "method": "POST", 1669 "bulkId": "qwerty", 1670 "version": "W\/\"4weymrEsh5O6cAEK\"", 1671 "status": { 1672 "code": "201" 1673 } 1674 }, 1675 { 1676 "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1677 "method": "POST", 1678 "bulkId": "ytrewq", 1679 "version": "W\/\"lha5bbazU3fNvfe5\"", 1680 "status": { 1681 "code": "201" 1682 } 1683 } 1684 ] 1685 } 1687 A subsequent request for the 'Tour Guides' Group ('e9e30dba- 1688 f08f-4109-8486-d5c6a331660a') returns the following: 1690 GET /v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1691 Host: example.com 1692 Accept: application/json 1693 Authorization: Bearer h480djs93hd8 1695 HTTP/1.1 200 OK 1696 Content-Type: application/json 1697 Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1698 ETag: W/"lha5bbazU3fNvfe5" 1700 { 1701 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1702 "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", 1703 "displayName": "Tour Guides", 1704 "meta": { 1705 "resourceType": "Group", 1706 "created": "2011-08-01T18:29:49.793Z", 1707 "lastModified": "2011-08-01T20:31:02.315Z", 1708 "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1709 "version": "W\/\"lha5bbazU3fNvfe5\"" 1710 }, 1711 "members": [ 1712 { 1713 "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", 1714 "$ref": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1715 "type": "User" 1716 } 1717 ] 1718 } 1720 Extensions that include references to other resources MUST be handled 1721 in the same way by the service provider. The following example uses 1722 the bulkId attribute within the enterprise extension managerId 1723 attribute. 1725 POST /v2/Bulk 1726 Host: example.com 1727 Accept: application/json 1728 Content-Type: application/json 1729 Authorization: Bearer h480djs93hd8 1730 Content-Length: ... 1732 { 1733 "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], 1734 "Operations": [ 1735 { 1736 "method": "POST", 1737 "path": "/Users", 1738 "bulkId": "qwerty", 1739 "data": { 1740 "schemas": ["urn:scim:schemas:core:2.0:User"], 1741 "userName": "Alice" 1742 } 1743 }, 1744 { 1745 "method": "POST", 1746 "path": "/Users", 1747 "bulkId": "ytrewq", 1748 "data": { 1749 "schemas": [ 1750 "urn:scim:schemas:core:2.0:User", 1751 "urn:scim:schemas:extension:enterprise:2.0:User" 1752 ], 1753 "userName": "Bob", 1754 "urn:scim:schemas:extension:enterprise:2.0:User": { 1755 "employeeNumber": "11250", 1756 "manager": { 1757 "managerId": "batchId:qwerty", 1758 "displayName": "Alice" 1759 } 1760 } 1761 } 1762 } 1763 ] 1764 } 1766 The service provider MUST try to resolve circular cross references 1767 between resources in a single bulk job but MAY stop after a failed 1768 attempt and instead return the status code 409 Conflict. The 1769 following example exhibits the potential conflict. 1771 POST /v2/Bulk 1772 Host: example.com 1773 Accept: application/json 1774 Content-Type: application/json 1775 Authorization: Bearer h480djs93hd8 1776 Content-Length: ... 1778 { 1779 "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], 1780 "Operations": [ 1781 { 1782 "method": "POST", 1783 "path": "/Groups", 1784 "bulkId": "qwerty", 1785 "data": { 1786 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1787 "displayName": "Group A", 1788 "members": [ 1789 { 1790 "type": "group", 1791 "value": "bulkId:ytrewq" 1792 } 1793 ] 1794 } 1795 }, 1796 { 1797 "method": "POST", 1798 "path": "/Groups", 1799 "bulkId": "ytrewq", 1800 "data": { 1801 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1802 "displayName": "Group B", 1803 "members": [ 1804 { 1805 "type": "group", 1806 "value": "bulkId:qwerty" 1807 } 1808 ] 1809 } 1810 } 1811 ] 1812 } 1814 If the service provider resolved the above circular references the 1815 following is returned from a subsequent GET request. 1817 GET /v2/Groups?filter=displayName sw 'Group' 1818 Host: example.com 1819 Accept: application/json 1820 Authorization: Bearer h480djs93hd8 1822 HTTP/1.1 200 OK 1823 Content-Type: application/json 1825 { 1826 "schemas": ["urn:scim:schemas:core:2.0:ListResponse"], 1827 "totalResults": 2, 1828 "Resources": [ 1829 { 1830 "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1831 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1832 "displayName": "Group A", 1833 "meta": { 1834 "resourceType": "Group", 1835 "created": "2011-08-01T18:29:49.793Z", 1836 "lastModified": "2011-08-01T18:29:51.135Z", 1837 "location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1838 "version": "W\/\"mvwNGaxB5SDq074p\"" 1839 }, 1840 "members": [ 1841 { 1842 "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1843 "$ref": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1844 "type": "Group" 1845 } 1846 ] 1847 }, 1848 { 1849 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1850 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1851 "displayName": "Group B", 1852 "meta": { 1853 "resourceType": "Group", 1854 "created": "2011-08-01T18:29:50.873Z", 1855 "lastModified": "2011-08-01T18:29:50.873Z", 1856 "location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1857 "version": "W\/\"wGB85s2QJMjiNnuI\"" 1858 }, 1859 "members": [ 1860 { 1861 "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1862 "$ref": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1863 "type": "Group" 1864 } 1865 ] 1866 } 1867 ] 1868 } 1869 The service provider MUST define the maximum number of operations and 1870 maximum payload size a client may send in a single request. If 1871 either limits are exceeded the service provider MUST return the HTTP 1872 response code 413 Request Entity Too Large. The returned response 1873 MUST specify the limit exceeded in the body of the error response. 1875 The following example the client sent a request exceeding the service 1876 provider's max payload size of 1 megabyte. 1878 POST /v2/Bulk 1879 Host: example.com 1880 Accept: application/json 1881 Content-Type: application/json 1882 Authorization: Bearer h480djs93hd8 1883 Content-Length: 4294967296 1885 ... 1887 HTTP/1.1 413 Request Entity Too Large 1888 Content-Type: application/json 1889 Location: https://example.com/v2/Bulk/yfCrVJhFIJagAHj8 1891 { 1892 "schemas":["urn:scim:schemas:core:2.0:Error"], 1893 "Errors":[ 1894 { 1895 "description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).", 1896 "code":"413" 1897 } 1898 ] 1899 } 1901 3.6. Data Input/Output Formats 1903 Clients MUST specify the format in which the data is submitted via 1904 the Section 14.17 HTTP header content-type [RFC2616] and MAY specify 1905 the desired response data format via an HTTP Accept Header; 1906 e.g.,"Accept: application/json" or via URI suffix; e.g., 1908 GET /Users/2819c223-7f76-453a-919d-413861904646.json 1909 Host: example.com 1911 Service providers MUST support the Accept Headers "Accept: 1912 application/json" for [RFC4627]. The format defaults to JSON if no 1913 format is specified. 1915 Singular attributes are encoded as string name-value-pairs in JSON; 1916 e.g., 1918 "attribute": "value" 1920 Multi-valued attributes in JSON are encoded as arrays; e.g., 1922 "attributes": [ "value1", "value2" ] 1924 Elements with nested elements are represented as objects in JSON; 1925 e.g, 1927 "attribute": { "subattribute1": "value1", "subattribute2": "value2" } 1929 3.7. Additional retrieval query parameters 1931 Clients MAY request a partial resource representation on any 1932 operation that returns a resource within the response by specifying 1933 the URL query parameter 'attributes'. When specified, each resource 1934 returned MUST contain the minimal set of resource attributes and MUST 1935 contain no other attributes or Sub-Attributes than those explicitly 1936 requested. The query parameter attributes value is a comma separated 1937 list of resource attribute names in standard attribute notation 1938 (Section 3.8) form (e.g. userName, name, emails). 1940 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName 1941 Host: example.com 1942 Accept: application/json 1943 Authorization: Bearer h480djs93hd8 1945 Giving the response 1947 HTTP/1.1 200 OK 1948 Content-Type: application/json 1949 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 1950 ETag: W/"a330bc54f0671c9" 1952 { 1953 "schemas":["urn:scim:schemas:core:2.0:User"], 1954 "id":"2819c223-7f76-453a-919d-413861904646", 1955 "userName":"bjensen", 1956 "meta":{ 1957 "resourceType": "User", 1958 "created":"2011-08-01T18:29:49.793Z", 1959 "lastModified":"2011-08-01T18:29:49.793Z", 1960 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 1961 "version":"W\/\"a330bc54f0671c9\"" 1962 } 1963 } 1965 3.8. Attribute Notation 1967 All operations share a common scheme for referencing simple and 1968 complex attributes. In general, attributes are identified by 1969 prefixing the attribute name with its schema URN separated by a ':' 1970 character; e.g., the core User resource attribute 'userName' is 1971 identified as 'urn:scim:schemas:core:2.0:User:userName'. Clients MAY 1972 omit core schema attribute URN prefixes though MUST fully qualify 1973 extended attributes with the associated resource URN; e.g., the 1974 attribute 'age' defined in 'urn:hr:schemas:user' is fully encoded as 1975 'urn:hr:schemas:user:age'. A Complex attributes' Sub-Attributes are 1976 referenced via nested, dot ('.') notation; i.e., {urn}:{Attribute 1977 name}.{Sub-Attribute name}. For example, the fully qualified path for 1978 a User's givenName is urn:scim:schemas:core:2.0:User:name.givenName 1979 All facets (URN, attribute and Sub-Attribute name) of the fully 1980 encoded Attribute name are case insensitive. 1982 3.9. HTTP Response Codes 1984 The SCIM Protocol uses the response status codes defined in HTTP 1985 Section 10 [RFC2616] to indicate operation success or failure. In 1986 addition to returning a HTTP response code implementers MUST return 1987 the errors in the body of the response in the client requested format 1988 containing the error response and, per the HTTP specification, human- 1989 readable explanations. Error responses are identified using the 1990 following URI: 'urn:scim:schemas:core:2.0:Error'. The following 1991 multi-valued attribute is defined in addition to those attributes 1992 defined in SCIM Core Schema: 1994 Errors The list of errors encountered by the service provider. The 1995 value attribute is a complex type with the following sub- 1996 attributes. 1998 description A human-readable explanation of the error. REQUIRED. 2000 code A string indicating the HTTP response code. REQUIRED. 2002 Implementers SHOULD handle the identified errors as described below. 2004 +--------------+---------------+------------------------------------+ 2005 | Code | Applicability | Suggested Explanation | 2006 +--------------+---------------+------------------------------------+ 2007 | 307 | GET, POST, | The client is directed to repeat | 2008 | TEMPORARY | PUT, PATCH, | the same HTTP request at the | 2009 | REDIRECT | DELETE | location identified. The client | 2010 | | | SHOULD NOT use the location | 2011 | | | provided in the response as a | 2012 | | | permanent reference to the | 2013 | | | resource and SHOULD continue to | 2014 | | | use the original request URI | 2015 | | | [I-D.ietf-httpbis-p2-semantics]. | 2016 | 308 | GET, POST, | The client is directed to repeat | 2017 | PERMANENT | PUT, PATCH, | the same HTTP request at the | 2018 | REDIRECT | DELETE | location identified. The client | 2019 | | | SHOULD use the location provided | 2020 | | | in the response as the permanent | 2021 | | | reference to the resource | 2022 | | | [I-D.reschke-http-status-308]. | 2023 | 400 BAD | GET, POST, | Request is unparseable, | 2024 | REQUEST | PUT, PATCH, | syntactically incorrect, or | 2025 | | DELETE | violates schema | 2026 | 401 | GET, POST, | Authorization failure | 2027 | UNAUTHORIZED | PUT, PATCH, | | 2028 | | DELETE | | 2029 | 403 | GET, POST, | Server does not support requested | 2030 | FORBIDDEN | PUT, PATCH, | operation | 2031 | | DELETE | | 2032 | 404 NOT | GET, PUT, | Specified resource; e.g., User, | 2033 | FOUND | PATCH, DELETE | does not exist | 2034 | 409 CONFLICT | POST, PUT, | The specified version number does | 2035 | | PATCH, DELETE | not match the resource's latest | 2036 | | | version number or a service | 2037 | | | provider refused to create a new, | 2038 | | | duplicate resource | 2039 | 412 | PUT, PATCH,D | Failed to update as resource {id} | 2040 | PRECONDITION | ELETE | changed on the server last | 2041 | FAILED | | retrieved | 2042 | 413 REQUEST | POST | {"maxOperations": | 2043 | ENTITY TOO | | 1000,"maxPayload": 1048576} | 2044 | LARGE | | | 2045 | 500 INTERNAL | GET, POST, | An internal error. Implementers | 2046 | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive | 2047 | | DELETE | debugging advice | 2048 | 501 NOT | GET, POST, | Service Provider does not support | 2049 | IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH | 2050 | | DELETE | | 2051 +--------------+---------------+------------------------------------+ 2053 Table 7: Defined error cases 2055 Error example in response to a non-existent GET request. 2057 HTTP/1.1 404 NOT FOUND 2059 { 2060 "schemas": ["urn:scim:schemas:core:2.0:Error"], 2061 "Errors":[ 2062 { 2063 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 2064 "code":"404" 2065 } 2066 ] 2067 } 2069 3.10. API Versioning 2071 The Base URL MAY be appended with a version identifier as a separate 2072 segment in the URL path. At this time the only valid identifier is 2073 'v1'. If specified, the version identifier MUST appear in the URL 2074 path immediately preceding the resource endpoint and conform to the 2075 following scheme: the character 'v' followed by the desired SCIM 2076 version number; e.g., a version 'v1' User request is specified as /v2 2077 /Users. When specified service providers MUST perform the operation 2078 using the desired version or reject the request. When omitted 2079 service providers SHOULD perform the operation using the most recent 2080 API supported by the service provider. 2082 3.11. Versioning Resources 2084 The API supports resource versioning via standard HTTP 2085 ETagsSection 14.19 [RFC2616]. Service providers MAY support weak 2086 ETags as the preferred mechanism for performing conditional 2087 retrievals and ensuring clients do not inadvertently overwrite each 2088 others changes, respectively. When supported SCIM ETags MUST be 2089 specified as an HTTP header and SHOULD be specified within the 2090 'version' attribute contained in the resource's 'meta' attribute. 2092 Example: 2094 POST /Users HTTP/1.1 2095 Host: example.com 2096 Content-Type: application/json 2097 Authorization: Bearer h480djs93hd8 2098 Content-Length: ... 2100 { 2101 "schemas":["urn:scim:schemas:core:2.0:User"], 2102 "userName":"bjensen", 2103 "externalId":"bjensen", 2104 "name":{ 2105 "formatted":"Ms. Barbara J Jensen III", 2106 "familyName":"Jensen", 2107 "givenName":"Barbara" 2108 } 2109 } 2111 The server responds with an ETag in the response header and meta 2112 structure. 2114 HTTP/1.1 201 Created 2115 Content-Type: application/json 2116 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2117 ETag: W/"e180ee84f0671b1" 2119 { 2120 "schemas":["urn:scim:schemas:core:2.0:User"], 2121 "id":"2819c223-7f76-453a-919d-413861904646", 2122 "meta":{ 2123 "resourceType":"User", 2124 "created":"2011-08-01T21:32:44.882Z", 2125 "lastModified":"2011-08-01T21:32:44.882Z", 2126 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2127 "version":"W\/\"e180ee84f0671b1\"" 2128 }, 2129 "name":{ 2130 "formatted":"Ms. Barbara J Jensen III", 2131 "familyName":"Jensen", 2132 "givenName":"Barbara" 2133 }, 2134 "userName":"bjensen" 2135 } 2136 With the returned ETag, clients MAY choose to retrieve the resource 2137 only if the resource has been modified. 2139 Conditional retrieval example using If-None-Match Section 14.26 2140 [RFC2616] header: 2142 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName 2143 Host: example.com 2144 Accept: application/json 2145 Authorization: Bearer h480djs93hd8 2146 If-None-Match: W/"e180ee84f0671b1" 2148 If the resource has not changed the service provider simply returns 2149 an empty body with a 304 "Not Modified" response code. 2151 If the service providers supports versioning of resources the client 2152 MUST supply an If-Match Section 14.24 [RFC2616] header for PUT and 2153 PATCH operations to ensure that the requested operation succeeds only 2154 if the supplied ETag matches the latest service provider resource; 2155 e.g., If-Match: W/"e180ee84f0671b1" 2157 3.12. HTTP Method Overloading 2159 In recognition that some clients, servers and firewalls prevent PUT, 2160 PATCH and DELETE operations a client MAY override the POST operation 2161 by specifying the custom header "X-HTTP-Method-Override" with the 2162 desired PUT, PATCH, DELETE operation. For example: 2164 POST /Users/2819c223-7f76-453a-919d-413861904646 2165 X-HTTP-Method-Override: DELETE 2167 4. Multi-Tenancy 2169 A single service provider may expose the SCIM protocol to multiple 2170 clients. Depending on the nature of the service, the clients may 2171 have authority to access and alter resources initially created by 2172 other clients. Alternatively, clients may expect to access disjoint 2173 sets of resources, and may expect that their resources are 2174 inaccessible by other clients. These scenarios are called "multi- 2175 tenancy", where each client is understood to be or represent a 2176 "tenant" of the service provider. Clients may also be multi- 2177 tenanted. 2179 The following common cases may occur: 2181 1. All clients share all resources (no tenancy) 2182 2. Each single client creates and accesses a private subset of 2183 resources (1 client:1 Tenant) 2185 3. Sets of clients share sets of resources (M clients:1 Tenant) 2187 4. One client to Multiple Tenants (1 client:M Tenants) 2189 Service providers may implement any subset of the above cases. 2191 Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a 2192 scheme for multi-tenancy. 2194 The SCIM protocol does not prescribe the mechanisms whereby clients 2195 and service providers interact for: 2197 o Registering or provisioning Tenants 2199 o Associating a subset of clients with a subset of the Tenants 2201 o Indicating which tenant is associated with the data in a request 2202 or response, or indicating which Tenant is the subject of a query 2204 o Implementers are encouraged to use mechanisms which comply with 2205 RESTful conventions. 2207 4.1. Associating Clients to Tenants 2209 The service provider MAY use the authentication mechanism (Section 2) 2210 to determine the identity of the client, and thus infer the 2211 associated Tenant. 2213 For implementations where a client is associated with more than one 2214 Tenant, the service provider MAY use one of the following methods for 2215 explicit specification of the Tenant. 2217 If any of these methods of allowing the client to explicitly specify 2218 the Tenant are employed, the service provider should ensure that 2219 access controls are in place to prevent or allow cross-tenant use 2220 cases. 2222 The service provider should consider precedence in cases where a 2223 client may explicitly specify a Tenant while being implicitly 2224 associated with a different Tenant. 2226 4.1.1. URL Prefix Example 2228 https://www.example.com/Tenants/{tenant_id}/v2/Users 2230 4.1.2. Subdomain Example 2232 https://{tenant_id}.example.com/v2/Groups 2234 4.1.3. HTTP Header 2236 The service provider may recognize a {tenant_id} provided by the 2237 client in the HTTP Header "SCIM_TENANT_ID" as the indicator of the 2238 desired target Tenant. 2240 In all of these methods, the {tenant_id} is a unique identifier for 2241 the Tenant as defined by the service provider. 2243 4.2. SCIM Identifiers with Multiple Tenants 2245 Considerations for a Multi-Tenant Implementation: 2247 The service provider may choose to implement SCIM ids which are 2248 unique across all resources for all Tenants, but this is not 2249 required. 2251 The externalId, defined by the client, is required to be unique ONLY 2252 within the resources associated with the associated Tenant. 2254 5. Security Considerations 2256 The SCIM Protocol is based on HTTP and thus subject to the security 2257 considerations found in Section 15 of [RFC2616]. SCIM resources 2258 (e.g., Users and Groups) can contain sensitive information. 2259 Therefore, SCIM clients and service providers MUST implement TLS. 2260 Which version(s) ought to be implemented will vary over time, and 2261 depend on the widespread deployment and known security 2262 vulnerabilities at the time of implementation. At the time of this 2263 writing, TLS version 1.2 [RFC5246]] is the most recent version, but 2264 has very limited actual deployment, and might not be readily 2265 available in implementation toolkits. TLS version 1.0 [[RFC2246]] is 2266 the most widely deployed version, and will give the broadest 2267 interoperability. 2269 6. References 2270 6.1. Normative References 2272 [I-D.ietf-httpbis-p2-semantics] 2273 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2274 (HTTP/1.1): Semantics and Content", draft-ietf- 2275 httpbis-p2-semantics-25 (work in progress), November 2013. 2277 [I-D.reschke-http-status-308] 2278 Reschke, J., "The Hypertext Transfer Protocol (HTTP) 2279 Status Code 308 (Permanent Redirect)", draft-reschke-http- 2280 status-308-07 (work in progress), March 2012. 2282 [IANA.Language] 2283 Internet Assigned Numbers Authority (IANA), "Language 2284 Subtag Registry", 2005. 2286 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2287 Requirement Levels", BCP 14, RFC 2119, March 1997. 2289 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2290 RFC 2246, January 1999. 2292 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2293 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2294 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2296 [RFC3896] Nicklass, O., "Definitions of Managed Objects for the DS3/ 2297 E3 Interface Type", RFC 3896, September 2004. 2299 [RFC4627] Crockford, D., "The application/json Media Type for 2300 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2302 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2303 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2305 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 2306 5789, March 2010. 2308 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 2309 Framework: Bearer Token Usage", RFC 6750, October 2012. 2311 6.2. Informative References 2313 [OpenSearch] 2314 Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . 2316 [Order-Operations] 2317 Wikipedia, "Order of Operations: Programming Languages", . 2319 Appendix A. Contributors 2321 Samuel Erdtman (samuel@erdtman.se) 2323 Patrick Harding (pharding@pingidentity.com) 2325 Appendix B. Acknowledgments 2327 The editors would like to acknowledge the contribution and work of 2328 the past draft editors: 2330 Trey Drake, UnboundID 2332 Chuck Mortimore, Salesforce 2334 The editor would like to thank the participants in the the SCIM 2335 working group for their support of this specification. 2337 Appendix C. Change Log 2339 [[This section to be removed prior to publication as an RFC]] 2341 Draft 02 - KG - Addition of schema extensibility 2343 Draft 03 - PH - Revisions based on following tickets: 2345 24 - Add filter negation 2347 39 - Clarification on response for DELETE 2349 42 - Make root searches optional 2351 49 - Add "ew" filter 2353 50 - Filters for multi-valued complex attributes 2355 51 - Search by Schema 2357 53 - Standard use of term client (some was consumer) 2359 55 - Redirect support (3xx) 2361 56 - Make manager attribute consistent with other $ref attrs 2363 57 - Update all "/v1" examples to '/v2" 2365 59 - Fix capitalization per IETF editor practices 2366 60 - Changed tags to normal and tags 2368 Authors' Addresses 2370 Kelly Grizzle 2371 SailPoint 2373 Email: kelly.grizzle@sailpoint.com 2375 Phil Hunt (editor) 2376 Oracle Corporation 2378 Email: phil.hunt@yahoo.com 2380 Morteza Ansari 2381 Cisco 2383 Email: morteza.ansari@cisco.com 2385 Erik Wahlstroem 2386 Technology Nexus 2388 Email: erik.wahlstrom@nexussafe.com 2390 Chuck Mortimore 2391 Salesforce.com 2393 Email: cmortimore@salesforce.com