idnits 2.17.1 draft-ietf-scim-api-04.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 35 instances of too long lines in the document, the longest one being 28 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: +------------+-------------------+----------------------------------+ | Parameter | Description | Default | +------------+-------------------+----------------------------------+ | startIndex | The 1-based index | 1 | | | of the first | | | | search result. | | | count | Non-negative | None. When specified the service | | | Integer. | provider MUST not return more | | | Specifies the | results than specified though | | | desired maximum | MAY return fewer results. If | | | number of search | unspecified, the maximum number | | | results per page; | of results is set by the service | | | e.g., 10. | provider. | +------------+-------------------+----------------------------------+ == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: Each operation against an attribute MUST be compatible with the attribute's mutability and schema as defined in the Attribute Types Section of [I-D.ietf-scim-core-schema]. For example, a client MAY NOT modify an attribute that has mutability "readOnly"or "immutable". However, a client MAY "add" a value to an"immutable" attribute if the attribute had no previous value. An operation that is not compatibile with an attribute's mutability or schema SHALL return an error as indicated below. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Clients request resource removal via DELETE. Service providers MAY choose not to permanently delete the resource, but MUST return a 404 error code for all operations associated with the previously deleted Id. Service providers MUST also omit the resource from future query results. In addition the service provider MUST not consider the deleted resource in conflict calculation. For example if a User resource is deleted, a CREATE request for a User resource with the same userName as the previously deleted resource should not fail with a 409 error due to userName conflict. -- The document date (April 23, 2014) is 3655 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 2398, but no explicit reference was found in the text == Unused Reference: 'RFC5246' is defined on line 2412, but no explicit reference was found in the text == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-25 == Outdated reference: A later version (-22) exists of draft-ietf-scim-core-schema-03 ** Downref: Normative reference to an Experimental draft: draft-reschke-http-status-308 (ref. 'I-D.reschke-http-status-308') ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 7 errors (**), 0 flaws (~~), 8 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: October 25, 2014 Oracle 6 M. Ansari 7 Cisco 8 E. Wahlstroem 9 Technology Nexus 10 C. Mortimore 11 Salesforce 12 April 23, 2014 14 System for Cross-Domain Identity Management:Protocol 15 draft-ietf-scim-api-04 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 25, 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 . . . . . . . . . 19 77 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 21 78 3.3.1. Modifying with PUT . . . . . . . . . . . . . . . . . 22 79 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 24 80 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 33 81 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 34 82 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 49 83 3.7. Additional retrieval query parameters . . . . . . . . . . 50 84 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 51 85 3.9. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 51 86 3.10. API Versioning . . . . . . . . . . . . . . . . . . . . . 53 87 3.11. Versioning Resources . . . . . . . . . . . . . . . . . . 53 88 3.12. HTTP Method Overloading . . . . . . . . . . . . . . . . . 55 89 4. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 55 90 4.1. Associating Clients to Tenants . . . . . . . . . . . . . 56 91 4.1.1. URL Prefix Example . . . . . . . . . . . . . . . . . 57 92 4.1.2. Subdomain Example . . . . . . . . . . . . . . . . . . 57 93 4.1.3. HTTP Header . . . . . . . . . . . . . . . . . . . . . 57 94 4.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 57 95 5. Security Considerations . . . . . . . . . . . . . . . . . . . 57 96 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 57 97 6.1. Normative References . . . . . . . . . . . . . . . . . . 58 98 6.2. Informative References . . . . . . . . . . . . . . . . . 59 99 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 59 100 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 59 101 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 59 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 60 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 [RFC3986]. 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 query example below requests the userName for all Users: 409 GET /Users?attributes=userName 410 Host: example.com 411 Accept: application/json 412 Authorization: Bearer h480djs93hd8 413 The following is an example response to the query above: 415 HTTP/1.1 200 OK 416 Content-Type: application/json 418 { 419 "schemas":["urn:scim:schemas:core:2.0:ListResponse"], 420 "totalResults":2, 421 "Resources":[ 422 { 423 "userName":"bjensen" 424 }, 425 { 426 "userName":"jsmith" 427 } 428 ] 429 } 431 3.2.2.1. Query Endpoints 433 Queries MAY be performed against a SCIM resource object or a resource 434 type endpoint. For example: 436 "/Users/{userid}" 438 "/Users" 440 "/Groups" 442 A server MAY support searches against the server root (e.g. "/"). A 443 search against a server root indicates that ALL resources within the 444 server SHALL be included subject to filtering. A filter expression 445 using "meta.resourceType" MAY be used to restrict results to one or 446 more specific resource types (e.g. "User"). 448 When processing search operations across endpoints that include more 449 than one SCIM resource type (e.g. a search from the server root 450 endpoint), filters MUST be processed in the same fashion as outlined 451 in Section 3.2.2.2. For filtered attributes that are not part of a 452 particular resource type, the service provider SHALL treat the 453 attribute as if there is no attribute value. For example, a presence 454 or equality filter for an undefined attribute evaluates as FALSE. 456 3.2.2.2. Filtering 458 Filtering is OPTIONAL. Clients may request a subset of resources by 459 specifying the 'filter' URL query parameter containing a filter 460 expression. When specified only those resources matching the filter 461 expression SHALL be returned. The expression language that is used 462 in the filter parameter supports references to attributes and 463 literals. 465 The attribute name and attribute operator are case insensitive. For 466 example, the following two expressions will evaluate to the same 467 logical value: 469 filter=userName Eq "john" 471 filter=Username eq "john" 473 The filter parameter MUST contain at least one valid Boolean 474 expression. Each expression MUST contain an attribute name followed 475 by an attribute operator and optional value. Multiple expressions 476 MAY be combined using the two logical operators. Furthermore 477 expressions can be grouped together using "()". 479 The operators supported in the expression are listed in the following 480 table. 482 +----------+-------------+------------------------------------------+ 483 | Operator | Description | Behavior | 484 +----------+-------------+------------------------------------------+ 485 | eq | equal | The attribute and operator values must | 486 | | | be identical for a match. | 487 | ne | not equal | The attribute and operator values are | 488 | | | not identical. | 489 | co | contains | The entire operator value must be a | 490 | | | substring of the attribute value for a | 491 | | | match. | 492 | sw | starts with | The entire operator value must be a | 493 | | | substring of the attribute value, | 494 | | | starting at the beginning of the | 495 | | | attribute value. This criterion is | 496 | | | satisfied if the two strings are | 497 | | | identical. | 498 | ew | ends with | The entire operator value must be a | 499 | | | substring of the attribute value, | 500 | | | matching at the end of the attribute | 501 | | | value. This criterion is satisfied if | 502 | | | the two strings are identical. | 503 | pr | present | If the attribute has a non-empty value, | 504 | | (has value) | or if it contains a non-empty node for | 505 | | | complex attributes there is a match. | 506 | gt | greater | If the attribute value is greater than | 507 | | than | operator value, there is a match. The | 508 | | | actual comparison is dependent on the | 509 | | | attribute type. For string attribute | 510 | | | types, this is a lexicographical | 511 | | | comparison and for DateTime types, it is | 512 | | | a chronological comparison. | 513 | ge | greater | If the attribute value is greater than | 514 | | than or | or equal to the operator value, there is | 515 | | equal | a match. The actual comparison is | 516 | | | dependent on the attribute type. For | 517 | | | string attribute types, this is a | 518 | | | lexicographical comparison and for | 519 | | | DateTime types, it is a chronological | 520 | | | comparison. | 521 | lt | less than | If the attribute value is less than | 522 | | | operator value, there is a match. The | 523 | | | actual comparison is dependent on the | 524 | | | attribute type. For string attribute | 525 | | | types, this is a lexicographical | 526 | | | comparison and for DateTime types, it is | 527 | | | a chronological comparison. | 528 | le | less than | If the attribute value is less than or | 529 | | or equal | equal to the operator value, there is a | 530 | | | match. The actual comparison is | 531 | | | dependent on the attribute type. For | 532 | | | string attribute types, this is a | 533 | | | lexicographical comparison and for | 534 | | | DateTime types, it is a chronological | 535 | | | comparison. | 536 +----------+-------------+------------------------------------------+ 538 Table 2: Attribute Operators 540 +----------+-------------+------------------------------------------+ 541 | Operator | Description | Behavior | 542 +----------+-------------+------------------------------------------+ 543 | and | Logical And | The filter is only a match if both | 544 | | | expressions evaluate to true. | 545 | or | Logical or | The filter is a match if either | 546 | | | expression evaluates to true. | 547 | not | Not | The filter is a match if the expression | 548 | | function | evaluates to false. | 549 +----------+-------------+------------------------------------------+ 551 Table 3: Logical Operators 553 +----------+-------------+------------------------------------------+ 554 | Operator | Description | Behavior | 555 +----------+-------------+------------------------------------------+ 556 | ( ) | Precedence | Boolean expressions may be grouped using | 557 | | grouping | parentheses to change the standard order | 558 | | | of operations; i.e., evaluate OR logical | 559 | | | operators before logical AND operators. | 560 | [ ] | Complex | Service providers MAY support complex | 561 | | attribute | filters where expressions MUST be | 562 | | filter | applied to the same value of a parent | 563 | | grouping | attribute specified immediately before | 564 | | | the left square bracket ("["). The | 565 | | | expression within square brackets ("[" | 566 | | | and "]") MUST be a valid filter | 567 | | | expression based upon sub-attributes of | 568 | | | the parent attribute. Nested expressions | 569 | | | MAY be used. See examples below. | 570 +----------+-------------+------------------------------------------+ 572 Table 4: Grouping Operators 574 SCIM filters MUST conform to the following ABNF rules as per 575 [RFC5234] below: 577 FILTER = attrExp / logExp / valuePath / *1"not" "(" FILTER ")" 579 valuePath = attrPath "[" FILTER "]" 580 ; FILTER uses sub-attribs of a parent attrPath 582 ATTRNAME = ALPHA *(nameChar) 584 nameChar = "-" / "_" / DIGIT / ALPHA 586 attrPath = [URI ":"] ATTRNAME *1subAttr 587 ; SCIM attribute name 588 ; URI is SCIM "schema" URI 590 subAttr = "." ATTRNAME 591 ; a sub-attribute of a complex attribute 593 attrExpr = (attrPath SP "pr") / 594 (attrPath SP compareOp SP compValue) 596 compValue = false / null / true / number / string 597 ; rules from JSON (RFC7159) 599 compareOp = "eq" / "ne" / "co" / 600 "sw" / "ew" / 601 "gt" / "lt" / 602 "ge" / "le" 604 logExp = FILTER ("and" / "or") FILTER 606 Figure 1: ABNF Specification of SCIM Filters 608 In the above ABNF, the "compValue" (comparison value) rule is built 609 on JSON Data Interchange format ABNF rules as specified in [RFC7159], 610 "DIGIT" and "ALPHA" are defined per Appendix B.1 of [RFC5234] and, 611 "URI" is defined per Appendix A of [RFC3986]. 613 Filters MUST be evaluated using standard order of operations 614 [Order-Operations]. Attribute operators have the highest precedence, 615 followed by the grouping operator (i.e, parentheses), followed by the 616 logical AND operator, followed by the logical OR operator. 618 If the specified attribute in a filter expression is a multi-valued 619 attribute, the resource MUST match if any of the instances of the 620 given attribute match the specified criterion; e.g. if a User has 621 multiple emails values, only one has to match for the entire User to 622 match. For complex attributes, a fully qualified Sub-Attribute MUST 623 be specified using standard attribute notation (Section 3.8). For 624 example, to filter by userName the parameter value is userName and to 625 filter by first name, the parameter value is name.givenName. 627 Providers MAY support additional filter operations if they choose. 628 Providers MUST decline to filter results if the specified filter 629 operation is not recognized and return a HTTP 400 error with an 630 appropriate human readable response. For example, if a client 631 specified an unsupported operator named 'regex' the service provider 632 should specify an error response description identifying the client 633 error; e.g., 'The operator 'regex' is not supported.' 635 String type attributes are case insensitive by default unless the 636 attribute type is defined as a caseExact string. Attribute operators 637 'eq', 'co', and 'sw' MUST perform caseIgnore matching for all string 638 attributes unless the attribute is defined as caseExact. By default 639 all string attributes are caseIgnore. 641 Clients MAY search by schema or schema extensions by using a filter 642 expression including the "schemas" attribute. 644 The following are examples of valid filters. Some attributes (e.g. 645 rooms and rooms.number) are hypothetical extensions and are not part 646 of SCIM core schema: 648 filter=userName eq "bjensen" 650 filter=name.familyName co "O'Malley" 652 filter=userName sw "J" 654 filter=title pr 656 filter=meta.lastModified gt "2011-05-13T04:42:34Z" 658 filter=meta.lastModified ge "2011-05-13T04:42:34Z" 660 filter=meta.lastModified lt "2011-05-13T04:42:34Z" 662 filter=meta.lastModified le "2011-05-13T04:42:34Z" 664 filter=title pr and userType eq "Employee" 666 filter=title pr or userType eq "Intern" 668 filter=schemas eq "urn:scim:schemas:extension:enterprise:2.0:User" 670 filter=userType eq "Employee" and (emails co "example.com" or emails 671 co "example.org") 673 filter=userType ne "Employee" and not (emails co "example.com" or 674 emails co "example.org") 676 filter=userType eq "Employee" and (emails.type eq "work") 678 filter=userType eq "Employee" and emails[type eq "work" and 679 value co "@example.com"] 681 filter=emails[type eq "work" and value co "@example.com"] or 682 ims[type eq "xmpp" and value co "@foo.com"] 684 filter=addresses[state eq "CA" and rooms[type eq "bedroom" and 685 number gt 2]] 687 Example Filters 689 3.2.2.3. Sorting 691 Sort is OPTIONAL. Sorting allows clients to specify the order in 692 which resources are returned by specifying a combination of sortBy 693 and sortOrder URL parameters. 695 sortBy: The sortBy parameter specifies the attribute whose value 696 SHALL be used to order the returned responses. If the sortBy 697 attribute corresponds to a singular attribute, resources are 698 sorted according to that attribute's value; if it's a multi-valued 699 attribute, resources are sorted by the value of the primary 700 attribute, if any, or else the first value in the list, if any. 701 If the attribute is complex the attribute name must be a path to a 702 sub-attribute in standard attribute notation (Section 3.8) ; e.g., 703 "sortBy=name.givenName". For all attribute types, if there is no 704 data for the specified "sortBy" value they are sorted via the 705 "sortOrder" parameter; i.e., they are ordered last if ascending 706 and first if descending. 708 sortOrder: The order in which the sortBy parameter is applied. 709 Allowed values are "ascending" and "descending". If a value for 710 sortBy is provided and no sortOrder is specified, the sortOrder 711 SHALL default to ascending. String type attributes are case 712 insensitive by default unless the attribute type is defined as a 713 case exact string. "sortOrder" MUST sort according to the 714 attribute type; i.e., for "caseIgnore" attributes, sort the result 715 using case insensitive, unicode alphabetic sort order, with no 716 specific locale implied and for caseExact attribute types, sort 717 the result using case sensitive, Unicode alphabetic sort order. 719 3.2.2.4. Pagination 721 Pagination parameters can be used together to "page through" large 722 numbers of resources so as not to overwhelm the client or service 723 provider. Pagination is not session based hence clients SHOULD never 724 assume repeatable results. For example, a request for a list of 10 725 resources beginning with a startIndex of 1 may return different 726 results when repeated as a resource in the original result could be 727 deleted or new ones could be added in-between requests. Pagination 728 parameters and general behavior are derived from the OpenSearch 729 Protocol [OpenSearch]. 731 The following table describes the URL pagination parameters. 733 +------------+-------------------+----------------------------------+ 734 | Parameter | Description | Default | 735 +------------+-------------------+----------------------------------+ 736 | startIndex | The 1-based index | 1 | 737 | | of the first | | 738 | | search result. | | 739 | count | Non-negative | None. When specified the service | 740 | | Integer. | provider MUST not return more | 741 | | Specifies the | results than specified though | 742 | | desired maximum | MAY return fewer results. If | 743 | | number of search | unspecified, the maximum number | 744 | | results per page; | of results is set by the service | 745 | | e.g., 10. | provider. | 746 +------------+-------------------+----------------------------------+ 748 Table 5: Pagination Request parameters 750 The following table describes the query response pagination 751 attributes specified by the service provider. 753 +--------------+----------------------------------------------------+ 754 | Element | Description | 755 +--------------+----------------------------------------------------+ 756 | itemsPerPage | Non-negative Integer. Specifies the number of | 757 | | search results returned in a query response page; | 758 | | e.g., 10. | 759 | totalResults | Non-negative Integer. Specifies the total number | 760 | | of results matching the client query; e.g., 1000. | 761 | startIndex | The 1-based index of the first result in the | 762 | | current set of search results; e.g., 1. | 763 +--------------+----------------------------------------------------+ 765 Table 6: Pagination Response Elements 767 For example, to retrieve the first 10 Users set the startIndex to 1 768 and the count to 10: 770 GET /Users?startIndex=1&count=10 771 Host: example.com 772 Accept: application/json 773 Authorization: Bearer h480djs93hd8 774 The response to the query above returns metadata regarding paging 775 similar to the following example (actual resources removed for 776 brevity): 778 { 779 "totalResults":100, 780 "itemsPerPage":10, 781 "startIndex":1, 782 "schemas":["urn:scim:schemas:core:2.0"], 783 "Resources":[{ 784 ... 785 }] 786 } 788 Given the example above, to continue paging set the startIndex to 11 789 and re-fetch; i.e., /Users?startIndex=11&count=10 791 3.2.3. Querying Resources Using HTTP POST 793 Clients MAY execute queries without passing parameters on the URL by 794 using the HTTP POST verb combined with the '/.search' path extension. 795 The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL 796 be used to indicate the HTTP POST verb is intended to be a query 797 operation. 799 To create a new search result set, a SCIM client sends an HTTP POST 800 request to the desired SCIM resource endpoint (ending in '/.search'). 801 The body of the POST request MAY include any of the parameters as 802 defined in Section 3.2.2. 804 Search requests MUST be identified using the following URI: 805 'urn:scim:schemas:core:2.0:SearchRequest'. The following attributes 806 are defined for search requests: 808 attributes A multi-valued list of strings indicating the names of 809 resource attributes to return in the response. Attribute names 810 MUST be in standard attribute notation (Section 3.8) form. See 811 additional retrieval query parameters (Section 3.7). OPTIONAL. 813 filter The filter string used to request a subset of resources. The 814 filter string MUST be a valid filter (Section 3.2.2.2) expression. 815 OPTIONAL. 817 sortBy A string indicating the attribute whose value SHALL be used 818 to order the returned responses. The sortBy attribute MUST be in 819 standard attribute notation (Section 3.8) form. See sorting 820 (Section 3.2.2.3). OPTIONAL. 822 sortOrder A string indicating the order in which the sortBy 823 parameter is applied. Allowed values are "ascending" and 824 "descending". See sorting (Section 3.2.2.3). OPTIONAL. 826 startIndex An integer indicating the 1-based index of the first 827 search result. See pagination (Section 3.2.2.4). OPTIONAL. 829 count An integer indicating the desired maximum number of search 830 results per page. See pagination (Section 3.2.2.4). OPTIONAL. 832 After receiving a HTTP POST request, a response is returned as 833 specified in Section 3.2.2. 835 The following example shows an HTTP POST Search request with search 836 parameters attributes, filter, and count included: 838 POST /.search 839 Host: example.com 840 Accept: application/json 841 Content-Type: application/json 842 Authorization: Bearer h480djs93hd8 843 Content-Length: ... 845 { 846 "schemas": ["urn:scim:schemas:core:2.0:SearchRequest"], 847 "attributes": ["displayName", "userName"], 848 "filter": "displayName sw \"smith\"", 849 "startIndex": 1, 850 "count": 10 851 } 853 Figure 2: Example POST Search Request 855 A search response is shown with the first page of results. For 856 brevity reasons, only two matches are shown: one User and one Group. 858 HTTP/1.1 200 OK 859 Content-Type: application/json 860 Location: https://example.com/.search 861 { 862 "schemas": ["urn:scim:schemas:core:2.0:ListResponse"], 863 "totalResults":100, 864 "itemsPerPage":10, 865 "startIndex":1, 866 "Resources":[ 867 { 868 "meta":{ 869 "location": 870 "https://example.com/Users/2819c223-7f76-413861904646", 871 "resourceType":"User", 872 "lastModified": ... 873 }, 874 "userName":"jsmith", 875 "displayName":"Smith, James" 876 }, 877 { 878 "meta":{ 879 "location": 880 "https://example.com/Groups/c8596b90-7539-4f20968d1908", 881 "resourceType":"Group", 882 "lastModified": ... 883 }, 884 "displayName":"Smith Family" 885 }, 886 ... 887 ] 888 } 890 Figure 3: Example POST Search Response 892 3.3. Modifying Resources 894 Resources can be modified in whole or in part via PUT or PATCH, 895 respectively. Implementers MUST support PUT as specified in 896 Section 9.6 [RFC2616] . Resources such as Groups may be very large 897 hence implementers SHOULD support PATCH [RFC5789] to enable partial 898 resource modifications. 900 3.3.1. Modifying with PUT 902 PUT performs a full update. Clients MAY retrieve the entire resource 903 in advance, add the desired modifications and use HTTP PUT which will 904 overwrite all previously stored data. Since the PUT request performs 905 a full update, clients MAY send attributes of the retrieved resource 906 and the service provider MUST process according to attribute 907 mutability as follows: 909 readWrite, writeOnly Any values provided SHALL replace the existing 910 attribute values. Omitting the attribute or specific values means 911 the attribute or specific value SHALL be removed; 913 immutable If values are provided for elements already set in the 914 attribute they MUST match existing data or an error is returned. 915 If the service provider has no existing values, a new value(s) MAY 916 be specified; and, 918 readOnly Any values provided (e.g. meta.resourceType) SHALL be 919 ignored. 921 If an attribute is "required", the client MUST specify the attribute 922 in the PUT request. 924 If a value provided for an immutable attribute with an existing value 925 is NOT matched, the server SHALL respond with an HTTP response code 926 of 400 and an appropriate human readable message indicating an 927 attempt to change an immutable attribute. 929 Unless otherwise specified a successful PUT operation returns a 200 930 OK response code and the entire resource within the response body, 931 enabling the client to correlate the client's and Provider's views of 932 the updated resource. Example: 934 PUT /Users/2819c223-7f76-453a-919d-413861904646 935 Host: example.com 936 Accept: application/json 937 Content-Type: application/json 938 Authorization: Bearer h480djs93hd8 939 If-Match: W/"a330bc54f0671c9" 941 { 942 "schemas":["urn:scim:schemas:core:2.0:User"], 943 "id":"2819c223-7f76-453a-919d-413861904646", 944 "userName":"bjensen", 945 "externalId":"bjensen", 946 "name":{ 947 "formatted":"Ms. Barbara J Jensen III", 948 "familyName":"Jensen", 949 "givenName":"Barbara", 950 "middleName":"Jane" 951 }, 952 "emails":[ 953 { 954 "value":"bjensen@example.com" 955 }, 956 { 957 "value":"babs@jensen.org" 958 } 959 ] 960 } 961 The service responds with the entire, updated User: 963 HTTP/1.1 200 OK 964 Content-Type: application/json 965 ETag: W/"b431af54f0671a2" 966 Location:"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646" 967 { 968 "schemas":["urn:scim:schemas:core:2.0:User"], 969 "id":"2819c223-7f76-453a-919d-413861904646", 970 "userName":"bjensen", 971 "externalId":"bjensen", 972 "name":{ 973 "formatted":"Ms. Barbara J Jensen III", 974 "familyName":"Jensen", 975 "givenName":"Barbara", 976 "middleName":"Jane" 977 }, 978 "emails":[ 979 { 980 "value":"bjensen@example.com" 981 }, 982 { 983 "value":"babs@jensen.org" 984 } 985 ], 986 "meta": { 987 "resourceType":"User", 988 "created":"2011-08-08T04:56:22Z", 989 "lastModified":"2011-08-08T08:00:12Z", 990 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 991 "version":"W\/\"b431af54f0671a2\"" 992 } 993 } 995 3.3.2. Modifying with PATCH 997 HTTP PATCH is an OPTIONAL server function that enables clients to 998 update one or more attributes of a SCIM resource using a sequence of 999 operations to "add", "remove", or "replace" values. The general form 1000 of the SCIM patch request is based on JavaScript Object Notation 1001 (JSON) Patch [RFC6902]. One difference between SCIM patch and JSON 1002 patch is that SCIM servers do not support array indexing and may not 1003 support all [RFC6902] operation types. 1005 The body of an HTTP PATCH request MUST contain one or more patch 1006 operation objects. A patch operation object MUST have exactly one 1007 "op" member, whose value indicates the operation to perform and MAY 1008 be one of "add", "remove", or "replace" . The semantics of each 1009 operation are defined below. 1011 Operation objects MUST have exactly one "path" member which is a 1012 "String" containing an attribute path as specified by the following 1013 ABNF syntax rule: 1015 PATH = attrPath / valuePath [subAttr] 1017 Figure 4: SCIM Patch PATH Rule 1019 The rules, "attrPath", "valuePath", and "subAttr" are defined in 1020 Section 3.2.2.2. The "valuePath" rule allows specific values of a 1021 complex, multi-valued attribute to be selected. 1023 Valid examples of "path" values are as follows: 1025 "path":"members" 1027 "path":"name.familyName" 1029 "path":"addresses[type eq \"work\"]" 1031 "path":"members[value eq 1032 \"2819c223-7f76-453a-919d-413861904646\"]" 1034 "path":"members[value eq 1035 \"2819c223-7f76-453a-919d-413861904646\"].displayName" 1037 Each operation against an attribute MUST be compatible with the 1038 attribute's mutability and schema as defined in the Attribute Types 1039 Section of [I-D.ietf-scim-core-schema]. For example, a client MAY 1040 NOT modify an attribute that has mutability "readOnly"or "immutable". 1041 However, a client MAY "add" a value to an"immutable" attribute if the 1042 attribute had no previous value. An operation that is not 1043 compatibile with an attribute's mutability or schema SHALL return an 1044 error as indicated below. 1046 Each patch operation represents a single action to be applied to the 1047 same SCIM resource specified by the request URI. Operations are 1048 applied sequentially in the order they appear in the array. Each 1049 operation in the sequence is applied to the target resource; the 1050 resulting resource becomes the target of the next operation. 1051 Evaluation continues until all operations are successfully applied or 1052 until an error condition is encountered. 1054 A patch request, regardless of the number of operations, SHALL be 1055 treated as atomic. If a single operation encounters an error 1056 condition, the original SCIM resource MUST be restored, and a failure 1057 status SHALL be returned. 1059 If a request fails. the server SHALL return an HTTP response status 1060 code of 400 and a JSON detail error response containing an "error" 1061 object that SHOULD be one of the following string values: 1063 malformed_operation 1064 The JSON operation elements could not successfully be parsed. 1065 This may be due to an invalid or missing operation attribute, or 1066 it could be due to a missing attribute required by a specific 1067 operation. 1069 mutability 1070 The operation requested is not compatible with the mutability of 1071 the selected attribute. 1073 invalid_path 1074 The path attribute was invalid or malformed. 1076 no_target 1077 The "path" specified did not return a target against which the 1078 operation could be performed. 1080 invalid_value 1081 The operation "value" was missing or was not compatable with the 1082 targeted attribute's type 1084 The following is a non-normative example of an error response to a 1085 patch request. 1087 HTTP/1.1 400 Bad Request 1088 Content-Type: application/json;charset=UTF-8 1089 Cache-Control: no-store 1090 Pragma: no-cache 1092 { 1093 "error":"mutability", 1094 "error_description":"Attribute 'id' is readOnly." 1095 } 1097 On successful completion, the server MUST return either a 200 OK 1098 response code and the entire resource (subject to the "attributes" 1099 query parameter - see Additional Retrieval Query Parameters 1100 (Section 3.7)) within the response body, or a 204 No Content response 1101 code and the appropriate response headers for a successful patch 1102 request. The server MUST return a 200 OK if the "attributes" 1103 parameter is specified on the request. 1105 3.3.2.1. Add Operation 1107 The "add" operation performs one of the following functions, 1108 depending upon what the target location indicated by "path" 1109 references: 1111 o If the target location does not exist, the attribute and value is 1112 added. 1114 o If the target location specifies a multi-valued attribute, a new 1115 value is added to the attribute. 1117 o if the target location specifies a single-valued attribute, the 1118 existing value is replaced. 1120 o If the target location specifies an attribute that does not exist 1121 (has no value), the attribute is added with the new value. 1123 o If the target location exists, the value is replaced. 1125 o If the target location already contains the value specified, no 1126 changes SHOULD be made to the resource and a success response 1127 SHOULD be returned. Unless other operations change the resource, 1128 this operation SHALL NOT change the modify timestamp of the 1129 resource. 1131 The operation MUST contain a "value" member whose content specifies 1132 the value to be added. The value MAY be a quoted value OR it may be 1133 a JSON object containing the sub-attributes of the complex attribute 1134 specified in the operation's "path". 1136 The following example shows how to add a member to a group. Some 1137 text removed for readability ("..."): 1139 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1140 Host: example.com 1141 Accept: application/json 1142 Content-Type: application/json 1143 Authorization: Bearer h480djs93hd8 1144 If-Match: W/"a330bc54f0671c9" 1146 { 1147 "op":"add", 1148 "path":"members", 1149 "value":[ 1150 { 1151 "display": "Babs Jensen", 1152 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1153 "value": "2819c223-7f76-453a-919d-413861904646" 1154 } 1155 ] 1156 } 1158 The "display" Sub-Attribute in this request is optional since the 1159 value attribute uniquely identifies the user to be added. If the 1160 user was already a member of this group, no changes should be made to 1161 the resource and a success response should be returned. The server 1162 responds with either the entire updated Group or no response body: 1164 HTTP/1.1 204 No Content 1165 Authorization: Bearer h480djs93hd8 1166 ETag: W/"b431af54f0671a2" 1167 Location: "https://example.com/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" 1169 3.3.2.2. Remove Operation 1171 The "remove" operation removes the value at the target location 1172 specified by the "path". The operation performs the following 1173 functions depending on the target location specified by "path": 1175 o If the target location is a single-value attribute, the attribute 1176 and its associated value is removed. 1178 o If the target location is a multi-valued attribute and no filter 1179 is specified, the attribute and all values are removed. 1181 o If the target location is a multi-valued attribute and a complex 1182 filter is specified comparing a "value", the values matched by the 1183 filter are removed. 1185 o If the target location is a complex-multi-valued attribute and a 1186 complex filter is specified based on the attribute's sub- 1187 attributes, the matching records are removed. 1189 The following example shows how to remove a member from a group. As 1190 with the previous example, the "display" Sub-Attribute is optional. 1191 If the user was not a member of this group, no changes should be made 1192 to the resource and a success response should be returned. 1194 Note that server responses have been omitted for the rest of the 1195 PATCH examples. 1197 Remove a single member from a group. Some text removed for 1198 readability ("..."): 1200 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1201 Host: example.com 1202 Accept: application/json 1203 Content-Type: application/json 1204 Authorization: Bearer h480djs93hd8 1205 If-Match: W/"a330bc54f0671c9" 1207 { 1208 "op":"remove", 1209 "path":"members[value eq \"2819c223-7f76-...413861904646\"]" 1210 } 1212 Remove all members of a group: 1214 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1215 Host: example.com 1216 Accept: application/json 1217 Content-Type: application/json 1218 Authorization: Bearer h480djs93hd8 1219 If-Match: W/"a330bc54f0671c9" 1221 { "op":"remove","path":"members"} 1223 Removal of a value from a complex-multi-valued attribute (request 1224 headers removed for brevity): 1226 { 1227 "op":"remove", 1228 "path":"emails[type eq \"work\" and value ew \"example.com\"]" 1229 } 1230 Example request to remove and add a member. Some text removed for 1231 readability ("..."): 1233 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1234 Host: example.com 1235 Accept: application/json 1236 Content-Type: application/json 1237 Authorization: Bearer h480djs93hd8 1238 If-Match: W/"a330bc54f0671c9" 1240 [ 1241 { 1242 "op":"remove", 1243 "path":"members[value eq\"2819c223...919d-413861904646\"]" 1244 }, 1245 { 1246 "op":"add", 1247 "path":"members", 1248 "value": [ 1249 { 1250 "display": "James Smith", 1251 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1252 "value": "08e1d05d...473d93df9210" 1253 } 1254 ] 1255 } 1256 ] 1257 The following example shows how to replace all the members of a group 1258 with a different members list. Some text removed for readabilty 1259 ("..."): 1261 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1262 Host: example.com 1263 Accept: application/json 1264 Content-Type: application/json 1265 Authorization: Bearer h480djs93hd8 1266 If-Match: W/"a330bc54f0671c9" 1268 [ 1269 { "op":"remove","path":"members"}, 1270 { 1271 "op":"add", 1272 "path":"members", 1273 "value":[ 1274 { 1275 "display": "Babs Jensen", 1276 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1277 "value": "2819c223-7f76-453a-919d-413861904646" 1278 }, 1279 { 1280 "display": "James Smith", 1281 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1282 "value": "08e1d05d-121c-4561-8b96-473d93df9210" 1283 }] 1284 } 1285 ] 1287 3.3.2.3. Replace Operation 1289 The "replace" operation replaces the value at the target location 1290 specified by the "path". The operation performs the following 1291 functions depending on the target location specified by "path": 1293 o If the target location is a single-value attribute, the attributes 1294 value is replaced. 1296 o If the target location is a multi-valued attribute and no filter 1297 is specified, the attribute and all values are replaced. 1299 o If the target location is a multi-valued attribute and a complex 1300 filter is specified comparing a "value", the values matched by the 1301 filter are replaced. 1303 o If the target location is a complex-multi-valued attribute and a 1304 complex filter is specified based on the attribute's sub- 1305 attributes, the matching records are replaced. 1307 o If the target location is a complex-multi-valued attribute with a 1308 complex filter and a specific sub-attribute (e.g. "addresses[type 1309 eq "work"].streetAddress"), the matching sub-attribute of the 1310 matching record is replaced. 1312 The following example shows how to replace all the members of a group 1313 with a different members list in a single replace operation. Some 1314 text removed for readability ("..."): 1316 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1317 Host: example.com 1318 Accept: application/json 1319 Content-Type: application/json 1320 Authorization: Bearer h480djs93hd8 1321 If-Match: W/"a330bc54f0671c9" 1323 { 1324 "op":"replace", 1325 "path":"members", 1326 "value":[ 1327 { 1328 "display": "Babs Jensen", 1329 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1330 "value": "2819c223...413861904646" 1331 }, 1332 { 1333 "display": "James Smith", 1334 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1335 "value": "08e1d05d...473d93df9210" 1336 } 1337 ] 1338 } 1339 The following example shows how to change a User's entire "work" 1340 address. 1342 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1343 Host: example.com 1344 Accept: application/json 1345 Content-Type: application/json 1346 Authorization: Bearer h480djs93hd8 1347 If-Match: W/"a330bc54f0671c9" 1349 { 1350 "op":"replace", 1351 "path":"addresses[type eq \"work\"]", 1352 "value": 1353 { 1354 "type": "work", 1355 "streetAddress": "911 Universal City Plaza", 1356 "locality": "Hollywood", 1357 "region": "CA", 1358 "postalCode": "91608", 1359 "country": "US", 1360 "formatted": "911 Universal City Plaza\nHollywood, CA 91608 US", 1361 "primary": true 1362 } 1363 } 1365 The following example shows how to change a User's address. Since 1366 address does not have a value Sub-Attribute, the existing address 1367 must be removed and the modified address added. 1369 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1370 Host: example.com 1371 Accept: application/json 1372 Content-Type: application/json 1373 Authorization: Bearer h480djs93hd8 1374 If-Match: W/"a330bc54f0671c9" 1376 { 1377 "op":"replace", 1378 "path":"addresses[type eq \"work\"].streetAddress", 1379 "value":"911 Universal City Plaza" 1380 } 1382 3.4. Deleting Resources 1384 Clients request resource removal via DELETE. Service providers MAY 1385 choose not to permanently delete the resource, but MUST return a 404 1386 error code for all operations associated with the previously deleted 1387 Id. Service providers MUST also omit the resource from future query 1388 results. In addition the service provider MUST not consider the 1389 deleted resource in conflict calculation. For example if a User 1390 resource is deleted, a CREATE request for a User resource with the 1391 same userName as the previously deleted resource should not fail with 1392 a 409 error due to userName conflict. 1394 DELETE /Users/2819c223-7f76-453a-919d-413861904646 1395 Host: example.com 1396 Authorization: Bearer h480djs93hd8 1397 If-Match: W/"c310cd84f0281b7" 1399 In response to a successful delete, the server SHALL respond with 1400 successful HTTP status 204 (No Content). A non-normative example 1401 response: 1403 HTTP/1.1 204 No Content 1405 Example: client attempt to retrieve the previously deleted User 1407 GET /Users/2819c223-7f76-453a-919d-413861904646 1408 Host: example.com 1409 Authorization: Bearer h480djs93hd8 1411 Server Response: 1413 HTTP/1.1 404 NOT FOUND 1415 { 1416 "schemas": ["urn:scim:schemas:core:2.0:Error"], 1417 "Errors":[ 1418 { 1419 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 1420 "code":"404" 1421 } 1422 ] 1423 } 1425 3.5. Bulk 1427 Bulk is OPTIONAL. The bulk operation enables clients to send a 1428 potentially large collection of resource operations in a single 1429 request. The body of a a bulk operation contains a set of HTTP 1430 resource operations using one of the API supported HTTP methods; 1431 i.e., POST, PUT, PATCH or DELETE. 1433 Bulk requests are identified using the following URI: 1434 'urn:scim:schemas:core:2.0:BulkRequest'. Bulk responses are 1435 identified using the following URI: 1436 'urn:scim:schemas:core:2.0:BulkResponse'. Bulk requests and bulk 1437 responses share many attributes. Unless otherwise specified, each 1438 attribute below is present in both bulk requests and bulk responses. 1440 The following Singular Attribute is defined in addition to the common 1441 attributes defined in SCIM core schema. 1443 failOnErrors An Integer specifying the number of errors that the 1444 service provider will accept before the operation is terminated 1445 and an error response is returned. OPTIONAL in a request. Not 1446 valid in a response. 1448 The following Complex Multi-valued Attribute is defined in addition 1449 to the common attributes defined in core schema. 1451 Operations Defines operations within a bulk job. Each operation 1452 corresponds to a single HTTP request against a resource endpoint. 1453 REQUIRED. 1455 method The HTTP method of the current operation. Possible values 1456 are POST, PUT, PATCH or DELETE. REQUIRED. 1458 bulkId The transient identifier of a newly created resource, 1459 unique within a bulk request and created by the client. The 1460 bulkId serves as a surrogate resource id enabling clients to 1461 uniquely identify newly created resources in the Response and 1462 cross reference new resources in and across operations within a 1463 bulk request. REQUIRED when method is POST. 1465 version The current resource version. Version is REQUIRED if the 1466 service provider supports ETags and the method is PUT, DELETE, 1467 or PATCH. 1469 path The resource's relative path. If the method is POST the 1470 value must specify a resource type endpoint; e.g., /Users or / 1471 Groups whereas all other method values must specify the path to 1472 a specific resource; e.g., /Users/2819c223-7f76-453a- 1473 919d-413861904646. REQUIRED in a request. 1475 data The resource data as it would appear for a single POST, PUT 1476 or PATCH resource operation. REQUIRED in a request when method 1477 is POST, PUT and PATCH. 1479 location The resource endpoint URL. REQUIRED in a response, 1480 except in the event of a POST failure. 1482 status A complex type that contains information about the success 1483 or failure of one operation within the bulk job. REQUIRED in a 1484 response. 1486 code The HTTP response code that would have been returned if a 1487 a single HTTP request would have been used. REQUIRED. 1489 description A human readable error message. REQUIRED when an 1490 error occurred. 1492 If a bulk job is processed successfully the HTTP response code 200 OK 1493 MUST be returned, otherwise an appropriate HTTP error code MUST be 1494 returned. 1496 The service provider MUST continue performing as many changes as 1497 possible and disregard partial failures. The client MAY override 1498 this behavior by specifying a value for failOnErrors attribute. The 1499 failOnErrors attribute defines the number of errors that the service 1500 provider should accept before failing the remaining operations 1501 returning the response. 1503 To be able to reference a newly created resource the attribute bulkId 1504 MUST be specified when creating new resources. The bulkId is defined 1505 by the client as a surrogate identifier in a POST operation. The 1506 service provider MUST return the same bulkId together with the newly 1507 created resource. The bulkId can then be used by the client to map 1508 the service provider id with the bulkId of the created resource. 1510 There can be more then one operation per resource in each bulk job. 1511 The Service client MUST take notice of the unordered structure of 1512 JSON and the service provider can process operations in any order. 1513 For example, if the Service client sends two PUT operations in one 1514 request, the outcome is non-deterministic. 1516 The service provider response MUST include the result of all 1517 processed operations. A location attribute that includes the 1518 resource's end point MUST be returned for all operations excluding 1519 failed POSTs. The status attribute includes information about the 1520 success or failure of one operation within the bulk job. The 1521 attribute status MUST include the code attribute that holds the HTTP 1522 response code that would have been returned if a single HTTP request 1523 would have been used. If an error occurred the status MUST also 1524 include the description attribute containing a human readable 1525 explanation of the error. 1527 "status": { 1528 "code": "201" 1529 } 1531 The following is an example of a status in a failed operation. 1533 "status": { 1534 "code": "400", 1535 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1536 } 1538 The following example shows how to add, update, and remove a user. 1539 The failOnErrors attribute is set to '1' indicating the service 1540 provider should return on the first error. The POST operation's 1541 bulkId value is set to 'qwerty' enabling the client to match the new 1542 User with the returned resource id '92b725cd-9465-4e7d- 1543 8c16-01f8e146b87a'. 1545 POST /v2/Bulk 1546 Host: example.com 1547 Accept: application/json 1548 Content-Type: application/json 1549 Authorization: Bearer h480djs93hd8 1550 Content-Length: ... 1552 { 1553 "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], 1554 "failOnErrors":1, 1555 "Operations":[ 1556 { 1557 "method":"POST", 1558 "path":"/Users", 1559 "bulkId":"qwerty", 1560 "data":{ 1561 "schemas": ["urn:scim:schemas:core:2.0:User"], 1562 "userName":"Alice" 1563 } 1564 }, 1565 { 1566 "method":"PUT", 1567 "path":"/Users/b7c14771-226c-4d05-8860-134711653041", 1568 "version":"W\/\"3694e05e9dff591\"", 1569 "data":{ 1570 "schemas": ["urn:scim:schemas:core:2.0:User"], 1571 "id":"b7c14771-226c-4d05-8860-134711653041", 1572 "userName":"Bob" 1574 } 1575 }, 1576 { 1577 "method": "PATCH", 1578 "path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1579 "version": "W/\"edac3253e2c0ef2\"", 1580 "data": {[ 1581 { 1582 "op": "remove", 1583 "path": "nickName" 1584 }, 1585 { 1586 "op": "add", 1587 "path": "userName", 1588 "value": "Dave" 1589 } 1590 ]} 1591 }, 1592 { 1593 "method":"DELETE", 1594 "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1595 "version":"W\/\"0ee8add0a938e1a\"" 1596 } 1597 ] 1598 } 1600 The service provider returns the following response. 1602 HTTP/1.1 200 OK 1603 Content-Type: application/json 1605 { 1606 "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], 1607 "Operations": [ 1608 { 1609 "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1610 "method": "POST", 1611 "bulkId": "qwerty", 1612 "version": "W\/\"oY4m4wn58tkVjJxK\"", 1613 "status": { 1614 "code": "201" 1615 } 1616 }, 1617 { 1618 "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 1619 "method": "PUT", 1620 "version": "W\/\"huJj29dMNgu3WXPD\"", 1621 "status": { 1622 "code": "200" 1623 } 1624 }, 1625 { 1626 "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1627 "method": "PATCH", 1628 "version": "W\/\"huJj29dMNgu3WXPD\"", 1629 "status": { 1630 "code": "200" 1631 } 1632 }, 1633 { 1634 "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1635 "method": "DELETE", 1636 "status": { 1637 "code": "204" 1638 } 1639 } 1640 ] 1641 } 1643 The following response is returned if an error occurred when 1644 attempting to create the User 'Alice'. The service provider stops 1645 processing the bulk operation and immediately returns a response to 1646 the client. The response contains the error and any successful 1647 results prior to the error. 1649 HTTP/1.1 200 OK 1650 Content-Type: application/json 1652 { 1653 "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], 1654 "Operations": [ 1655 { 1656 "method": "POST", 1657 "bulkId": "qwerty", 1658 "status": { 1659 "code": "400", 1660 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1661 } 1662 } 1663 ] 1664 } 1666 If the failOnErrors attribute is not specified or the service 1667 provider has not reached the error limit defined by the client the 1668 service provider will continue to process all operations. The 1669 following is an example in which all operations failed. 1671 HTTP/1.1 200 OK 1672 Content-Type: application/json 1674 { 1675 "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], 1676 "Operations": [ 1677 { 1678 "method": "POST", 1679 "bulkId": "qwerty", 1680 "status": { 1681 "code": "400", 1682 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1683 } 1684 }, 1685 { 1686 "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 1687 "method": "PUT", 1688 "status": { 1689 "code": "412", 1690 "description": "Failed to update as user changed on the server since you last retrieved it." 1691 } 1692 }, 1693 { 1694 "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1695 "method": "PATCH", 1696 "status": { 1697 "code": "412", 1698 "description": "Failed to update as user changed on the server since you last retrieved it." 1699 } 1700 }, 1701 { 1702 "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1703 "method": "DELETE", 1704 "status": { 1705 "code": "404", 1706 "description": "Specified resource; e.g., User, does not exist." 1707 } 1708 } 1709 ] 1710 } 1712 The client can, within one bulk operation, create a new User, a new 1713 Group and add the newly created User to the newly created Group. In 1714 order to add the new User to the Group the client must use the 1715 surrogate id attribute, bulkId, to reference the User. The bulkId 1716 attribute value must be pre-pended with the literal "bulkId:"; e.g., 1717 if the bulkId is 'qwerty' the value is "bulkId:qwerty". The service 1718 provider MUST replace the string "bulkId:qwerty" with the permanent 1719 resource id once created. 1721 The following example creates a User with the userName 'Alice' and a 1722 Group with the displayName 'Tour Guides' with Alice as a member. 1724 POST /v2/Bulk 1725 Host: example.com 1726 Accept: application/json 1727 Content-Type: application/json 1728 Authorization: Bearer h480djs93hd8 1729 Content-Length: ... 1731 { 1732 "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], 1733 "Operations": [ 1734 { 1735 "method": "POST", 1736 "path": "/Users", 1737 "bulkId": "qwerty", 1738 "data": { 1739 "schemas": ["urn:scim:schemas:core:2.0:User"], 1740 "userName": "Alice" 1741 } 1742 }, 1743 { 1744 "method": "POST", 1745 "path": "/Groups", 1746 "bulkId": "ytrewq", 1747 "data": { 1748 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1749 "displayName": "Tour Guides", 1750 "members": [ 1751 { 1752 "type": "user", 1753 "value": "bulkId:qwerty" 1754 } 1755 ] 1756 } 1757 } 1758 ] 1759 } 1761 The service provider returns the following response. 1763 HTTP/1.1 200 OK 1764 Content-Type: application/json 1766 { 1767 "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], 1768 "Operations": [ 1769 { 1770 "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1771 "method": "POST", 1772 "bulkId": "qwerty", 1773 "version": "W\/\"4weymrEsh5O6cAEK\"", 1774 "status": { 1775 "code": "201" 1776 } 1777 }, 1778 { 1779 "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1780 "method": "POST", 1781 "bulkId": "ytrewq", 1782 "version": "W\/\"lha5bbazU3fNvfe5\"", 1783 "status": { 1784 "code": "201" 1785 } 1786 } 1787 ] 1788 } 1790 A subsequent request for the 'Tour Guides' Group ('e9e30dba- 1791 f08f-4109-8486-d5c6a331660a') returns the following: 1793 GET /v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1794 Host: example.com 1795 Accept: application/json 1796 Authorization: Bearer h480djs93hd8 1798 HTTP/1.1 200 OK 1799 Content-Type: application/json 1800 Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1801 ETag: W/"lha5bbazU3fNvfe5" 1803 { 1804 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1805 "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", 1806 "displayName": "Tour Guides", 1807 "meta": { 1808 "resourceType": "Group", 1809 "created": "2011-08-01T18:29:49.793Z", 1810 "lastModified": "2011-08-01T20:31:02.315Z", 1811 "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1812 "version": "W\/\"lha5bbazU3fNvfe5\"" 1813 }, 1814 "members": [ 1815 { 1816 "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", 1817 "$ref": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1818 "type": "User" 1819 } 1820 ] 1821 } 1823 Extensions that include references to other resources MUST be handled 1824 in the same way by the service provider. The following example uses 1825 the bulkId attribute within the enterprise extension managerId 1826 attribute. 1828 POST /v2/Bulk 1829 Host: example.com 1830 Accept: application/json 1831 Content-Type: application/json 1832 Authorization: Bearer h480djs93hd8 1833 Content-Length: ... 1835 { 1836 "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], 1837 "Operations": [ 1838 { 1839 "method": "POST", 1840 "path": "/Users", 1841 "bulkId": "qwerty", 1842 "data": { 1843 "schemas": ["urn:scim:schemas:core:2.0:User"], 1844 "userName": "Alice" 1845 } 1846 }, 1847 { 1848 "method": "POST", 1849 "path": "/Users", 1850 "bulkId": "ytrewq", 1851 "data": { 1852 "schemas": [ 1853 "urn:scim:schemas:core:2.0:User", 1854 "urn:scim:schemas:extension:enterprise:2.0:User" 1855 ], 1856 "userName": "Bob", 1857 "urn:scim:schemas:extension:enterprise:2.0:User": { 1858 "employeeNumber": "11250", 1859 "manager": { 1860 "managerId": "batchId:qwerty", 1861 "displayName": "Alice" 1862 } 1863 } 1864 } 1865 } 1866 ] 1867 } 1869 The service provider MUST try to resolve circular cross references 1870 between resources in a single bulk job but MAY stop after a failed 1871 attempt and instead return the status code 409 Conflict. The 1872 following example exhibits the potential conflict. 1874 POST /v2/Bulk 1875 Host: example.com 1876 Accept: application/json 1877 Content-Type: application/json 1878 Authorization: Bearer h480djs93hd8 1879 Content-Length: ... 1881 { 1882 "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], 1883 "Operations": [ 1884 { 1885 "method": "POST", 1886 "path": "/Groups", 1887 "bulkId": "qwerty", 1888 "data": { 1889 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1890 "displayName": "Group A", 1891 "members": [ 1892 { 1893 "type": "group", 1894 "value": "bulkId:ytrewq" 1895 } 1896 ] 1897 } 1898 }, 1899 { 1900 "method": "POST", 1901 "path": "/Groups", 1902 "bulkId": "ytrewq", 1903 "data": { 1904 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1905 "displayName": "Group B", 1906 "members": [ 1907 { 1908 "type": "group", 1909 "value": "bulkId:qwerty" 1910 } 1911 ] 1912 } 1913 } 1914 ] 1915 } 1917 If the service provider resolved the above circular references the 1918 following is returned from a subsequent GET request. 1920 GET /v2/Groups?filter=displayName sw 'Group' 1921 Host: example.com 1922 Accept: application/json 1923 Authorization: Bearer h480djs93hd8 1925 HTTP/1.1 200 OK 1926 Content-Type: application/json 1928 { 1929 "schemas": ["urn:scim:schemas:core:2.0:ListResponse"], 1930 "totalResults": 2, 1931 "Resources": [ 1932 { 1933 "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1934 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1935 "displayName": "Group A", 1936 "meta": { 1937 "resourceType": "Group", 1938 "created": "2011-08-01T18:29:49.793Z", 1939 "lastModified": "2011-08-01T18:29:51.135Z", 1940 "location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1941 "version": "W\/\"mvwNGaxB5SDq074p\"" 1942 }, 1943 "members": [ 1944 { 1945 "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1946 "$ref": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1947 "type": "Group" 1948 } 1949 ] 1950 }, 1951 { 1952 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1953 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1954 "displayName": "Group B", 1955 "meta": { 1956 "resourceType": "Group", 1957 "created": "2011-08-01T18:29:50.873Z", 1958 "lastModified": "2011-08-01T18:29:50.873Z", 1959 "location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1960 "version": "W\/\"wGB85s2QJMjiNnuI\"" 1961 }, 1962 "members": [ 1963 { 1964 "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1965 "$ref": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1966 "type": "Group" 1967 } 1968 ] 1969 } 1970 ] 1971 } 1972 The service provider MUST define the maximum number of operations and 1973 maximum payload size a client may send in a single request. If 1974 either limits are exceeded the service provider MUST return the HTTP 1975 response code 413 Request Entity Too Large. The returned response 1976 MUST specify the limit exceeded in the body of the error response. 1978 The following example the client sent a request exceeding the service 1979 provider's max payload size of 1 megabyte. 1981 POST /v2/Bulk 1982 Host: example.com 1983 Accept: application/json 1984 Content-Type: application/json 1985 Authorization: Bearer h480djs93hd8 1986 Content-Length: 4294967296 1988 ... 1990 HTTP/1.1 413 Request Entity Too Large 1991 Content-Type: application/json 1992 Location: https://example.com/v2/Bulk/yfCrVJhFIJagAHj8 1994 { 1995 "schemas":["urn:scim:schemas:core:2.0:Error"], 1996 "Errors":[ 1997 { 1998 "description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).", 1999 "code":"413" 2000 } 2001 ] 2002 } 2004 3.6. Data Input/Output Formats 2006 Clients MUST specify the format in which the data is submitted via 2007 the Section 14.17 HTTP header content-type [RFC2616] and MAY specify 2008 the desired response data format via an HTTP Accept Header; 2009 e.g.,"Accept: application/json" or via URI suffix; e.g., 2011 GET /Users/2819c223-7f76-453a-919d-413861904646.json 2012 Host: example.com 2014 Service providers MUST support the Accept Headers "Accept: 2015 application/json" for [RFC7159]. The format defaults to JSON if no 2016 format is specified. 2018 Singular attributes are encoded as string name-value-pairs in JSON; 2019 e.g., 2021 "attribute": "value" 2023 Multi-valued attributes in JSON are encoded as arrays; e.g., 2025 "attributes": [ "value1", "value2" ] 2027 Elements with nested elements are represented as objects in JSON; 2028 e.g, 2030 "attribute": { "subattribute1": "value1", "subattribute2": "value2" } 2032 3.7. Additional retrieval query parameters 2034 Clients MAY request a partial resource representation on any 2035 operation that returns a resource within the response by specifying 2036 the URL query parameter 'attributes'. When specified, each resource 2037 returned MUST contain the minimal set of resource attributes and MUST 2038 contain no other attributes or Sub-Attributes than those explicitly 2039 requested. The query parameter attributes value is a comma separated 2040 list of resource attribute names in standard attribute notation 2041 (Section 3.8) form (e.g. userName, name, emails). 2043 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName 2044 Host: example.com 2045 Accept: application/json 2046 Authorization: Bearer h480djs93hd8 2048 Giving the response 2050 HTTP/1.1 200 OK 2051 Content-Type: application/json 2052 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2053 ETag: W/"a330bc54f0671c9" 2055 { 2056 "schemas":["urn:scim:schemas:core:2.0:User"], 2057 "id":"2819c223-7f76-453a-919d-413861904646", 2058 "userName":"bjensen", 2059 "meta":{ 2060 "resourceType": "User", 2061 "created":"2011-08-01T18:29:49.793Z", 2062 "lastModified":"2011-08-01T18:29:49.793Z", 2063 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2064 "version":"W\/\"a330bc54f0671c9\"" 2065 } 2066 } 2068 3.8. Attribute Notation 2070 All operations share a common scheme for referencing simple and 2071 complex attributes. In general, attributes are identified by 2072 prefixing the attribute name with its schema URN separated by a ':' 2073 character; e.g., the core User resource attribute 'userName' is 2074 identified as 'urn:scim:schemas:core:2.0:User:userName'. Clients MAY 2075 omit core schema attribute URN prefixes though MUST fully qualify 2076 extended attributes with the associated resource URN; e.g., the 2077 attribute 'age' defined in 'urn:hr:schemas:user' is fully encoded as 2078 'urn:hr:schemas:user:age'. A Complex attributes' Sub-Attributes are 2079 referenced via nested, dot ('.') notation; i.e., {urn}:{Attribute 2080 name}.{Sub-Attribute name}. For example, the fully qualified path for 2081 a User's givenName is urn:scim:schemas:core:2.0:User:name.givenName 2082 All facets (URN, attribute and Sub-Attribute name) of the fully 2083 encoded Attribute name are case insensitive. 2085 3.9. HTTP Response Codes 2087 The SCIM Protocol uses the response status codes defined in HTTP 2088 Section 10 [RFC2616] to indicate operation success or failure. In 2089 addition to returning a HTTP response code implementers MUST return 2090 the errors in the body of the response in the client requested format 2091 containing the error response and, per the HTTP specification, human- 2092 readable explanations. Error responses are identified using the 2093 following URI: 'urn:scim:schemas:core:2.0:Error'. The following 2094 multi-valued attribute is defined in addition to those attributes 2095 defined in SCIM Core Schema: 2097 Errors The list of errors encountered by the service provider. The 2098 value attribute is a complex type with the following sub- 2099 attributes. 2101 description A human-readable explanation of the error. REQUIRED. 2103 code A string indicating the HTTP response code. REQUIRED. 2105 Implementers SHOULD handle the identified errors as described below. 2107 +--------------+---------------+------------------------------------+ 2108 | Code | Applicability | Suggested Explanation | 2109 +--------------+---------------+------------------------------------+ 2110 | 307 | GET, POST, | The client is directed to repeat | 2111 | TEMPORARY | PUT, PATCH, | the same HTTP request at the | 2112 | REDIRECT | DELETE | location identified. The client | 2113 | | | SHOULD NOT use the location | 2114 | | | provided in the response as a | 2115 | | | permanent reference to the | 2116 | | | resource and SHOULD continue to | 2117 | | | use the original request URI | 2118 | | | [I-D.ietf-httpbis-p2-semantics]. | 2119 | 308 | GET, POST, | The client is directed to repeat | 2120 | PERMANENT | PUT, PATCH, | the same HTTP request at the | 2121 | REDIRECT | DELETE | location identified. The client | 2122 | | | SHOULD use the location provided | 2123 | | | in the response as the permanent | 2124 | | | reference to the resource | 2125 | | | [I-D.reschke-http-status-308]. | 2126 | 400 BAD | GET, POST, | Request is unparseable, | 2127 | REQUEST | PUT, PATCH, | syntactically incorrect, or | 2128 | | DELETE | violates schema | 2129 | 401 | GET, POST, | Authorization failure | 2130 | UNAUTHORIZED | PUT, PATCH, | | 2131 | | DELETE | | 2132 | 403 | GET, POST, | Server does not support requested | 2133 | FORBIDDEN | PUT, PATCH, | operation | 2134 | | DELETE | | 2135 | 404 NOT | GET, PUT, | Specified resource; e.g., User, | 2136 | FOUND | PATCH, DELETE | does not exist | 2137 | 409 CONFLICT | POST, PUT, | The specified version number does | 2138 | | PATCH, DELETE | not match the resource's latest | 2139 | | | version number or a service | 2140 | | | provider refused to create a new, | 2141 | | | duplicate resource | 2142 | 412 | PUT, PATCH,D | Failed to update as resource {id} | 2143 | PRECONDITION | ELETE | changed on the server last | 2144 | FAILED | | retrieved | 2145 | 413 REQUEST | POST | {"maxOperations": | 2146 | ENTITY TOO | | 1000,"maxPayload": 1048576} | 2147 | LARGE | | | 2148 | 500 INTERNAL | GET, POST, | An internal error. Implementers | 2149 | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive | 2150 | | DELETE | debugging advice | 2151 | 501 NOT | GET, POST, | Service Provider does not support | 2152 | IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH | 2153 | | DELETE | | 2154 +--------------+---------------+------------------------------------+ 2156 Table 7: Defined error cases 2158 Error example in response to a non-existent GET request. 2160 HTTP/1.1 404 NOT FOUND 2162 { 2163 "schemas": ["urn:scim:schemas:core:2.0:Error"], 2164 "Errors":[ 2165 { 2166 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 2167 "code":"404" 2168 } 2169 ] 2170 } 2172 3.10. API Versioning 2174 The Base URL MAY be appended with a version identifier as a separate 2175 segment in the URL path. At this time the only valid identifier is 2176 'v1'. If specified, the version identifier MUST appear in the URL 2177 path immediately preceding the resource endpoint and conform to the 2178 following scheme: the character 'v' followed by the desired SCIM 2179 version number; e.g., a version 'v1' User request is specified as /v2 2180 /Users. When specified service providers MUST perform the operation 2181 using the desired version or reject the request. When omitted 2182 service providers SHOULD perform the operation using the most recent 2183 API supported by the service provider. 2185 3.11. Versioning Resources 2187 The API supports resource versioning via standard HTTP 2188 ETagsSection 14.19 [RFC2616]. Service providers MAY support weak 2189 ETags as the preferred mechanism for performing conditional 2190 retrievals and ensuring clients do not inadvertently overwrite each 2191 others changes, respectively. When supported SCIM ETags MUST be 2192 specified as an HTTP header and SHOULD be specified within the 2193 'version' attribute contained in the resource's 'meta' attribute. 2195 Example: 2197 POST /Users HTTP/1.1 2198 Host: example.com 2199 Content-Type: application/json 2200 Authorization: Bearer h480djs93hd8 2201 Content-Length: ... 2203 { 2204 "schemas":["urn:scim:schemas:core:2.0:User"], 2205 "userName":"bjensen", 2206 "externalId":"bjensen", 2207 "name":{ 2208 "formatted":"Ms. Barbara J Jensen III", 2209 "familyName":"Jensen", 2210 "givenName":"Barbara" 2211 } 2212 } 2214 The server responds with an ETag in the response header and meta 2215 structure. 2217 HTTP/1.1 201 Created 2218 Content-Type: application/json 2219 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2220 ETag: W/"e180ee84f0671b1" 2222 { 2223 "schemas":["urn:scim:schemas:core:2.0:User"], 2224 "id":"2819c223-7f76-453a-919d-413861904646", 2225 "meta":{ 2226 "resourceType":"User", 2227 "created":"2011-08-01T21:32:44.882Z", 2228 "lastModified":"2011-08-01T21:32:44.882Z", 2229 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2230 "version":"W\/\"e180ee84f0671b1\"" 2231 }, 2232 "name":{ 2233 "formatted":"Ms. Barbara J Jensen III", 2234 "familyName":"Jensen", 2235 "givenName":"Barbara" 2236 }, 2237 "userName":"bjensen" 2238 } 2239 With the returned ETag, clients MAY choose to retrieve the resource 2240 only if the resource has been modified. 2242 Conditional retrieval example using If-None-Match Section 14.26 2243 [RFC2616] header: 2245 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName 2246 Host: example.com 2247 Accept: application/json 2248 Authorization: Bearer h480djs93hd8 2249 If-None-Match: W/"e180ee84f0671b1" 2251 If the resource has not changed the service provider simply returns 2252 an empty body with a 304 "Not Modified" response code. 2254 If the service providers supports versioning of resources the client 2255 MUST supply an If-Match Section 14.24 [RFC2616] header for PUT and 2256 PATCH operations to ensure that the requested operation succeeds only 2257 if the supplied ETag matches the latest service provider resource; 2258 e.g., If-Match: W/"e180ee84f0671b1" 2260 3.12. HTTP Method Overloading 2262 In recognition that some clients, servers and firewalls prevent PUT, 2263 PATCH and DELETE operations a client MAY override the POST operation 2264 by specifying the custom header "X-HTTP-Method-Override" with the 2265 desired PUT, PATCH, DELETE operation. For example: 2267 POST /Users/2819c223-7f76-453a-919d-413861904646 2268 X-HTTP-Method-Override: DELETE 2270 4. Multi-Tenancy 2272 A single service provider may expose the SCIM protocol to multiple 2273 clients. Depending on the nature of the service, the clients may 2274 have authority to access and alter resources initially created by 2275 other clients. Alternatively, clients may expect to access disjoint 2276 sets of resources, and may expect that their resources are 2277 inaccessible by other clients. These scenarios are called "multi- 2278 tenancy", where each client is understood to be or represent a 2279 "tenant" of the service provider. Clients may also be multi- 2280 tenanted. 2282 The following common cases may occur: 2284 1. All clients share all resources (no tenancy) 2285 2. Each single client creates and accesses a private subset of 2286 resources (1 client:1 Tenant) 2288 3. Sets of clients share sets of resources (M clients:1 Tenant) 2290 4. One client to Multiple Tenants (1 client:M Tenants) 2292 Service providers may implement any subset of the above cases. 2294 Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a 2295 scheme for multi-tenancy. 2297 The SCIM protocol does not prescribe the mechanisms whereby clients 2298 and service providers interact for: 2300 o Registering or provisioning Tenants 2302 o Associating a subset of clients with a subset of the Tenants 2304 o Indicating which tenant is associated with the data in a request 2305 or response, or indicating which Tenant is the subject of a query 2307 o Implementers are encouraged to use mechanisms which comply with 2308 RESTful conventions. 2310 4.1. Associating Clients to Tenants 2312 The service provider MAY use the authentication mechanism (Section 2) 2313 to determine the identity of the client, and thus infer the 2314 associated Tenant. 2316 For implementations where a client is associated with more than one 2317 Tenant, the service provider MAY use one of the following methods for 2318 explicit specification of the Tenant. 2320 If any of these methods of allowing the client to explicitly specify 2321 the Tenant are employed, the service provider should ensure that 2322 access controls are in place to prevent or allow cross-tenant use 2323 cases. 2325 The service provider should consider precedence in cases where a 2326 client may explicitly specify a Tenant while being implicitly 2327 associated with a different Tenant. 2329 4.1.1. URL Prefix Example 2331 https://www.example.com/Tenants/{tenant_id}/v2/Users 2333 4.1.2. Subdomain Example 2335 https://{tenant_id}.example.com/v2/Groups 2337 4.1.3. HTTP Header 2339 The service provider may recognize a {tenant_id} provided by the 2340 client in the HTTP Header "SCIM_TENANT_ID" as the indicator of the 2341 desired target Tenant. 2343 In all of these methods, the {tenant_id} is a unique identifier for 2344 the Tenant as defined by the service provider. 2346 4.2. SCIM Identifiers with Multiple Tenants 2348 Considerations for a Multi-Tenant Implementation: 2350 The service provider may choose to implement SCIM ids which are 2351 unique across all resources for all Tenants, but this is not 2352 required. 2354 The externalId, defined by the client, is required to be unique ONLY 2355 within the resources associated with the associated Tenant. 2357 5. Security Considerations 2359 The SCIM Protocol is based on HTTP and thus subject to the security 2360 considerations found in Section 15 of [RFC2616]. SCIM resources 2361 (e.g., Users and Groups) can contain sensitive information. 2362 Therefore, SCIM clients and service providers MUST implement TLS. 2363 Which version(s) ought to be implemented will vary over time, and 2364 depend on the widespread deployment and known security 2365 vulnerabilities at the time of implementation. At the time of this 2366 writing, TLS version 1.2 [RFC5246]] is the most recent version, but 2367 has very limited actual deployment, and might not be readily 2368 available in implementation toolkits. TLS version 1.0 [[RFC2246]] is 2369 the most widely deployed version, and will give the broadest 2370 interoperability. 2372 6. References 2373 6.1. Normative References 2375 [I-D.ietf-httpbis-p2-semantics] 2376 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2377 (HTTP/1.1): Semantics and Content", draft-ietf- 2378 httpbis-p2-semantics-25 (work in progress), November 2013. 2380 [I-D.ietf-scim-core-schema] 2381 Grizzle, K., Hunt, P., Wahlstroem, E., and C. Mortimore, 2382 "System for Cross-Domain Identity Management: Core 2383 Schema", draft-ietf-scim-core-schema-03 (work in 2384 progress), February 2014. 2386 [I-D.reschke-http-status-308] 2387 Reschke, J., "The Hypertext Transfer Protocol (HTTP) 2388 Status Code 308 (Permanent Redirect)", draft-reschke-http- 2389 status-308-07 (work in progress), March 2012. 2391 [IANA.Language] 2392 Internet Assigned Numbers Authority (IANA), "Language 2393 Subtag Registry", 2005. 2395 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2396 Requirement Levels", BCP 14, RFC 2119, March 1997. 2398 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2399 RFC 2246, January 1999. 2401 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2402 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2403 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2405 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2406 Resource Identifier (URI): Generic Syntax", STD 66, RFC 2407 3986, January 2005. 2409 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2410 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2412 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2413 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2415 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 2416 5789, March 2010. 2418 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 2419 Framework: Bearer Token Usage", RFC 6750, October 2012. 2421 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 2422 Interchange Format", RFC 7159, March 2014. 2424 6.2. Informative References 2426 [OpenSearch] 2427 Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . 2429 [Order-Operations] 2430 Wikipedia, "Order of Operations: Programming Languages", . 2432 [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation 2433 (JSON) Patch", RFC 6902, April 2013. 2435 Appendix A. Contributors 2437 Samuel Erdtman (samuel@erdtman.se) 2439 Patrick Harding (pharding@pingidentity.com) 2441 Appendix B. Acknowledgments 2443 The editors would like to acknowledge the contribution and work of 2444 the past draft editors: 2446 Trey Drake, UnboundID 2448 Chuck Mortimore, Salesforce 2450 The editor would like to thank the participants in the the SCIM 2451 working group for their support of this specification. 2453 Appendix C. Change Log 2455 [[This section to be removed prior to publication as an RFC]] 2457 Draft 02 - KG - Addition of schema extensibility 2459 Draft 03 - PH - Revisions based on following tickets: 2461 24 - Add filter negation 2463 39 - Clarification on response for DELETE 2465 42 - Make root searches optional 2467 49 - Add "ew" filter 2468 50 - Filters for multi-valued complex attributes 2470 51 - Search by Schema 2472 53 - Standard use of term client (some was consumer) 2474 55 - Redirect support (3xx) 2476 56 - Make manager attribute consistent with other $ref attrs 2478 57 - Update all "/v1" examples to '/v2" 2480 59 - Fix capitalization per IETF editor practices 2482 60 - Changed tags to normal and tags 2484 Draft 04 - PH - Revisions based on the following tickets: 2486 18 - New PATCH command based on JSON Patch (RFC6902) 2488 - Provided ABNF specification for filters (used in PATCH) 2490 - Updated references to RFC4627 to RFC7159 2492 Authors' Addresses 2494 Kelly Grizzle 2495 SailPoint 2497 Email: kelly.grizzle@sailpoint.com 2499 Phil Hunt (editor) 2500 Oracle Corporation 2502 Email: phil.hunt@yahoo.com 2504 Morteza Ansari 2505 Cisco 2507 Email: morteza.ansari@cisco.com 2509 Erik Wahlstroem 2510 Technology Nexus 2512 Email: erik.wahlstrom@nexussafe.com 2513 Chuck Mortimore 2514 Salesforce.com 2516 Email: cmortimore@salesforce.com