idnits 2.17.1 draft-ietf-scim-api-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 10, 2015) is 3361 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) == Outdated reference: A later version (-18) exists of draft-ietf-precis-saslprepbis-13 == Outdated reference: A later version (-22) exists of draft-ietf-scim-core-schema-16 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7233 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) == Outdated reference: A later version (-23) exists of draft-ietf-precis-framework-22 -- Obsolete informational reference (is this intentional?): RFC 7238 (Obsoleted by RFC 7538) Summary: 6 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Hunt, Ed. 3 Internet-Draft Oracle 4 Intended status: Standards Track K. Grizzle 5 Expires: August 14, 2015 SailPoint 6 M. Ansari 7 Cisco 8 E. Wahlstroem 9 Nexus Technology 10 C. Mortimore 11 Salesforce 12 February 10, 2015 14 System for Cross-Domain Identity Management: Protocol 15 draft-ietf-scim-api-15 17 Abstract 19 The System for Cross-Domain Identity Management (SCIM) specification 20 is an HTTP based protocol that makes managing identities in multi- 21 domain scenarios easier to support through a standardized services. 22 Examples include but are not limited to enterprise to cloud service 23 providers, and inter-cloud based scenarios. The specification suite 24 seeks to build upon experience with existing schemas and deployments, 25 placing specific emphasis on simplicity of development and 26 integration, while applying existing authentication, authorization, 27 and privacy models. SCIM's intent is to reduce the cost and 28 complexity of user management operations by providing a common user 29 schema and extension model and a service protocol defined by this 30 document. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on August 14, 2015. 49 Copyright Notice 51 Copyright (c) 2015 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 67 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3 68 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3 69 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 70 2. Authentication and Authorization . . . . . . . . . . . . . . 4 71 3. SCIM Protocol . . . . . . . . . . . . . . . . . . . . . . . . 5 72 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 6 73 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 9 74 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 9 75 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 9 76 3.2.2. Query Resources . . . . . . . . . . . . . . . . . . . 10 77 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 21 78 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 24 79 3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 25 80 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 27 81 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 41 82 3.5. Bulk Operations . . . . . . . . . . . . . . . . . . . . . 42 83 3.5.1. Circular Reference Processing . . . . . . . . . . . . 44 84 3.5.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 47 85 3.5.3. Response and Error Handling . . . . . . . . . . . . . 51 86 3.5.4. Maximum Operations . . . . . . . . . . . . . . . . . 57 87 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 58 88 3.7. Additional Operation Response Parameters . . . . . . . . 59 89 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 60 90 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 60 91 3.10. HTTP Status and Error Response Handling . . . . . . . . . 61 92 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 65 93 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 65 94 4. Service Provider Configuration Endpoints . . . . . . . . . . 67 95 5. Preparation and Comparison of Internationalized Strings . . . 69 96 6. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 70 97 6.1. Associating Clients to Tenants . . . . . . . . . . . . . 70 98 6.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 71 99 7. Security Considerations . . . . . . . . . . . . . . . . . . . 71 100 7.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 71 101 7.2. Disclosure of Sensitive Information in URIs . . . . . . . 72 102 7.3. Anonymous Requests . . . . . . . . . . . . . . . . . . . 72 103 7.4. HTTP Considerations . . . . . . . . . . . . . . . . . . . 73 104 7.5. Secure Storage and Handling of Sensitive Data . . . . . . 73 105 7.6. Case Insensitive Comparision & International Languages . 74 106 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 107 8.1. Media Type Registration . . . . . . . . . . . . . . . . . 74 108 8.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 75 109 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 76 110 9.1. Normative References . . . . . . . . . . . . . . . . . . 76 111 9.2. Informative References . . . . . . . . . . . . . . . . . 77 112 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 78 113 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 78 114 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 78 115 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82 117 1. Introduction and Overview 119 The SCIM Protocol is an application-level, HTTP protocol for 120 provisioning and managing identity data on the web and in cross- 121 domain environments such as enterprise to cloud, or inter-cloud 122 scenarios. The protocol supports creation, modification, retrieval, 123 and discovery of core identity resources such as Users and Groups, as 124 well as custom resources and resource extensions. 126 1.1. Intended Audience 128 This document is intended as a guide to SCIM protocol usage for both 129 SCIM HTTP service providers and HTTP clients who may provision 130 information to service providers or retrieve information from them. 132 1.2. Notational Conventions 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 136 document are to be interpreted as described in [RFC2119]. These 137 keywords are capitalized when used to unambiguously specify 138 requirements of the protocol or application features and behavior 139 that affect the interoperability and security of implementations. 140 When these words are not capitalized, they are meant in their 141 natural-language sense. 143 For purposes of readability examples are not URL encoded. 144 Implementers MUST percent encode URLs as described in Section 2.1 of 145 [RFC3986]. 147 Throughout this documents all figures MAY contain spaces and extra 148 line-wrapping for readability and space limitations. Similarly, some 149 URI's contained within examples, have been shortened for space and 150 readability reasons. 152 1.3. Definitions 154 Base URI 155 The SCIM HTTP protocol is described in terms of a path relative to 156 a Base URI. The Base URI MUST NOT contain a query string as 157 clients may append additional path information and query 158 parameters as part of forming the request. The base URI most 159 often is a URL which most often consists of the "https" protocol 160 scheme, a domain name and some initial path [RFC3986]. Example: 161 "https://example.com/scim/" 163 For readability, all examples in this document are expressed 164 assuming the SCIM service root and the server root are the same 165 (no path pre-fix). It is expected that SCIM servers may be 166 deployed using any URI path prefix. For example, a SCIM server 167 might be have a prefix of "https://example.com/", or 168 "https://example.com/scim/tenancypath/". Additionally client may 169 also apply a version number to the server root prefix (see 170 Section 3.11 ). 172 2. Authentication and Authorization 174 Because SCIM builds on the HTTP protocol, it does not itself define a 175 scheme for authentication and authorization. SCIM depends on 176 standard HTTP authentication schemes. Implementers SHOULD support 177 existing authentication/authorization schemes. In particular, OAuth2 178 (see [RFC6749], [RFC6750]) is RECOMMENDED. Appropriate security 179 considerations of the selected authentication and authorization 180 schemes SHOULD be taken. Because this protocol uses HTTP response 181 status codes as the primary means of reporting the result of a 182 request, servers are advised to respond to unauthorized or 183 unauthenticated requests using the 401 response code in accordance 184 with Section 3.1 of [RFC7235]. 186 All examples show an OAuth2 bearer token [RFC6750] (though it is not 187 required); e.g., 188 GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 189 Host: example.com 190 Authorization: Bearer h480djs93hd8 192 When processing requests, the service provider SHOULD consider the 193 subject performing the request and whether the action is appropriate 194 given the subject and the resource affected by the request. The 195 subject performing the request is usually determined from the 196 "Authorization" header present in the request. 198 3. SCIM Protocol 200 The SCIM protocol specifies well-known endpoints and HTTP methods for 201 managing resources defined in the core schema; i.e., "User" and 202 "Group" resources correspond to "/Users" and "/Groups" respectively. 203 Service providers that support extended resources SHOULD define 204 resource endpoints using the convention of pluralizing the resource 205 name defined in the extended schema by appending an 's'. Given there 206 are cases where resource pluralization is ambiguous; e.g., a resource 207 named "Person" is legitimately "Persons" and "People". Clients 208 SHOULD discover resource endpoints via the "/ResourceTypes" endpoint. 210 GET 211 Retrieves one or more complete or partial resources. 213 POST 214 Depending on the endpoint, creates new resources, create a search 215 request, or may be used to bulk modify resources. 217 PUT 218 Modifies a resource by replacing existing attributes with a 219 specified set of replacement attributes (replace). PUT MUST NOT 220 be used to create new resources. 222 PATCH 223 Modifies a resource with a set of client specified changes 224 (partial update). 226 DELETE 227 Deletes a resource. 229 Resource Endpoint Operations Description 230 -------- ---------------- ---------------------- -------------------- 231 User /Users GET (Section 3.2.1), Retrieve, Add, 232 POST (Section 3.1), Modify Users 233 PUT (Section 3.3.1), 234 PATCH (Section 3.3.2), 235 DELETE (Section 3.4) 236 Group /Groups GET (Section 3.2.1), Retrieve, Add, 237 POST (Section 3.1), Modify Groups 238 PUT (Section 3.3.1), 239 PATCH (Section 3.3.2), 240 DELETE (Section 3.4) 241 Self /Me GET, POST, PUT, PATCH, Alias for operations 242 DELETE (Section 3.9) against a resource 243 mapped to an 244 authenticated 245 Subject (e.g. User). 246 Service /ServiceProvider GET (Section 4) Retrieve service 247 Provider Config provider's 248 Config configuration 249 Resource /ResourceTypes GET (Section 4) Retrieve supported 250 Type resource types 251 Schema /Schemas GET (Section 4) Retrieve one or more 252 supported schemas. 253 Bulk /Bulk POST (Section 3.5) Bulk updates to one 254 or more resources 255 Search [prefix]/.search POST (Section 3.2.3) Search from system 256 root or within a 257 resource endpoint 258 for one or more 259 resource types using 260 POST. 262 Table 1: Defined endpoints 264 All requests to the service provider are made via HTTP Methods as per 265 Section 4.3 [RFC7231] on a URL derived from the Base URL. Responses 266 are returned in the body of the HTTP response, formatted as JSON. 267 Error status codes SHOULD be transmitted via the HTTP status code of 268 the response (if possible), and SHOULD also be specified in the body 269 of the response (see Section 3.10). 271 3.1. Creating Resources 273 To create new resources, clients send HTTP POST requests to the 274 resource endpoint such as: "/Users" or "/Groups". 276 The server SHALL process attributes according to the following 277 mutability rules: 279 o For attributes in the request body, whose mutability is 280 "readOnly", SHALL be ignored. 282 o For attributes whose mutability is "readWrite", that are omitted 283 from the request body, MAY be assumed to be not asserted by the 284 client. The service provider MAY assign a default value to non- 285 asserted attributes in the final resource representation. 287 o Service providers MAY take into account whether a client has 288 access to, or understands, all of the resource's attributes when 289 deciding whether non-asserted attributes should be defaulted. 290 Clients that intend to override server defaulted values for 291 attributes MAY specify "null" for a single-valued attribute or an 292 empty array "[]" for a multi-valued attribute to clear all values. 294 When the service provider successfully creates the new resource, an 295 HTTP response SHALL be returned with HTTP status "201" ("Created"). 296 The response body SHOULD contain the service provider's 297 representation of the newly created resource. The URI of the created 298 resource SHALL included in the HTTP "Location" header and in JSON 299 resource representation under the attribute "meta.location". Since 300 the server is free to alter and/or ignore POSTed content, returning 301 the full representation can be useful to the client, enabling it to 302 correlate the client and server views of the new resource. 304 If the service provider determines creation of the requested resource 305 conflicts with existing resources; e.g., a "User" resource with a 306 duplicate "userName", the service provider MUST return an HTTP Status 307 409, with "scimType" error code of "uniqueness" as per Section 3.10. 309 Below, in the following example, a client sends a POST request 310 containing a "User" to the "/Users" endpoint. 312 POST /Users HTTP/1.1 313 Host: example.com 314 Accept: application/scim+json 315 Content-Type: application/scim+json 316 Authorization: Bearer h480djs93hd8 317 Content-Length: ... 319 { 320 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 321 "userName":"bjensen", 322 "externalId":"bjensen", 323 "name":{ 324 "formatted":"Ms. Barbara J Jensen III", 325 "familyName":"Jensen", 326 "givenName":"Barbara" 327 } 328 } 330 In response to the example request above, the server signals a 331 successful creation with an HTTP status code 201 (Created) and 332 returns a representation of the resource created. 334 HTTP/1.1 201 Created 335 Content-Type: application/scim+json 336 Location: 337 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 338 ETag: W/"e180ee84f0671b1" 340 { 341 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 342 "id":"2819c223-7f76-453a-919d-413861904646", 343 "externalId":"bjensen", 344 "meta":{ 345 "resourceType":"User", 346 "created":"2011-08-01T21:32:44.882Z", 347 "lastModified":"2011-08-01T21:32:44.882Z", 348 "location": 349 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 350 "version":"W\/\"e180ee84f0671b1\"" 351 }, 352 "name":{ 353 "formatted":"Ms. Barbara J Jensen III", 354 "familyName":"Jensen", 355 "givenName":"Barbara" 356 }, 357 "userName":"bjensen" 358 } 360 3.1.1. Resource Types 362 When adding a resource to a specific endpoint, the meta attribute 363 "resourceType" SHALL be set by the HTTP service provider to the 364 corresponding resource type for the endpoint. For example, "/Users" 365 will set "resourceType" to "User", and "/Groups" will set 366 "resourceType" to "Group". 368 3.2. Retrieving Resources 370 Resources are retrieved via opaque, unique URLs or via Query. The 371 attributes returned are defined in the server's attribute schema (see 372 Section 10 [I-D.ietf-scim-core-schema]) and request parameters (see 373 Section 3.7). By default, resource attributes returned in a response 374 are those whose schema "returned" setting is "always" or "default". 376 3.2.1. Retrieving a known Resource 378 To retrieve a known resource, clients send GET requests to the 379 resource endpoint; e.g., "/Users/{id}" or "/Groups/{id}", or 380 "/Schemas/{id}". 382 If the resource exists the server responds with HTTP Status code 200 383 (OK) and includes the result in the body of the response. 385 The below example retrieves a single User via the "/Users" endpoint. 387 GET /Users/2819c223-7f76-453a-919d-413861904646 388 Host: example.com 389 Accept: application/scim+json 390 Authorization: Bearer h480djs93hd8 392 The server responds with: 394 HTTP/1.1 200 OK 395 Content-Type: application/scim+json 396 Location: 397 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 398 ETag: W/"f250dd84f0671c3" 400 { 401 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 402 "id":"2819c223-7f76-453a-919d-413861904646", 403 "externalId":"bjensen", 404 "meta":{ 405 "resourceType":"User", 406 "created":"2011-08-01T18:29:49.793Z", 407 "lastModified":"2011-08-01T18:29:49.793Z", 408 "location": 409 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 410 "version":"W\/\"f250dd84f0671c3\"" 411 }, 412 "name":{ 413 "formatted":"Ms. Barbara J Jensen III", 414 "familyName":"Jensen", 415 "givenName":"Barbara" 416 }, 417 "userName":"bjensen", 418 "phoneNumbers":[ 419 { 420 "value":"555-555-8377", 421 "type":"work" 422 } 423 ], 424 "emails":[ 425 { 426 "value":"bjensen@example.com", 427 "type":"work" 428 } 429 ] 430 } 432 3.2.2. Query Resources 434 The SCIM protocol defines a standard set of query parameters that can 435 be used to filter, sort, and paginate to return zero or more 436 resources in a query response. Queries MAY be made against a single 437 resource or a resource type endpoint (e.g. "/Users"). SCIM service 438 providers MAY support additional query parameters not specified here 439 and SHOULD ignore any query parameters they do not recognize. 441 Responses MUST be identified using the following URI: 442 "urn:ietf:params:scim:api:messages:2.0:ListResponse". The following 443 attributes are defined for responses: 445 totalResults The total number of results returned by the list or 446 query operation. This may not be equal to the number of elements 447 in the resources attribute of the list response if pagination 448 (Section 3.2.2.4) is requested. REQUIRED. 450 Resources A multi-valued list of complex objects containing the 451 requested resources. This may be a subset of the full set of 452 resources if pagination (Section 3.2.2.4) is requested. REQUIRED 453 if "totalResults" is non-zero. 455 startIndex The 1-based index of the first result in the current set 456 of list results. REQUIRED when partial results returned due to 457 pagination. 459 itemsPerPage The number of resources returned in a list response 460 page. REQUIRED when partial results returned due to pagination. 462 A query that does not return any matches SHALL return success (HTTP 463 Status 200) with "totalResults" set to a value of 0. 465 The query example below requests the userName for all Users: 467 GET /Users?attributes=userName 468 Host: example.com 469 Accept: application/scim+json 470 Authorization: Bearer h480djs93hd8 472 The following is an example response to the query above: 474 HTTP/1.1 200 OK 475 Content-Type: application/scim+json 477 { 478 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 479 "totalResults":2, 480 "Resources":[ 481 { 482 "userName":"bjensen" 483 }, 484 { 485 "userName":"jsmith" 486 } 487 ] 488 } 490 3.2.2.1. Query Endpoints 492 Queries MAY be performed against a SCIM resource object, a resource 493 type endpoint, or a SCIM server root. For example: 495 "/Users/{id}" 497 "/Users" 499 "/Groups" 501 A query against a server root indicates that ALL resources within the 502 server SHALL be included subject to filtering. A filter expression 503 using "meta.resourceType" MAY be used to restrict results to one or 504 more specific resource types (to exclude others). For example: 506 filter=(meta.resourceType eq User) or (meta.resourceType eq Group) 508 If a SCIM service provider determines that too many results would be 509 returned (e.g. because a client queried a resource type endpoint or 510 the server base URI), the server SHALL reject the request by 511 returning an HTTP response with "status" 400 and json attribute 512 "scimType" set to "tooMany" (see Table 8). 514 When processing query operations across endpoints that include more 515 than one SCIM resource type (e.g. a query from the server root 516 endpoint), filters MUST be processed as outlined in Section 3.2.2.2. 517 For filtered attributes that are not part of a particular resource 518 type, the service provider SHALL treat the attribute as if there is 519 no attribute value. For example, a presence or equality filter for 520 an undefined attribute evaluates as FALSE. 522 3.2.2.2. Filtering 524 Filtering is an OPTIONAL parameter for SCIM service providers. 525 Clients MAY discover service provider filter capabilities by looking 526 at the "filter" attribute of the "ServiceProviderConfig" (see 527 Section 8 [I-D.ietf-scim-core-schema]). Clients MAY request a subset 528 of resources by specifying the "filter" query parameter containing a 529 filter expression. When specified only those resources matching the 530 filter expression SHALL be returned. The expression language that is 531 used in the filter parameter supports references to attributes and 532 literals. 534 Attribute names and attribute operators used in filters are case 535 insensitive. For example, the following two expressions will 536 evaluate to the same logical value: 538 filter=userName Eq "john" 540 filter=Username eq "john" 542 The filter parameter MUST contain at least one valid Boolean 543 expression. Each expression MUST contain an attribute name followed 544 by an attribute operator and optional value. Multiple expressions 545 MAY be combined using the two logical operators. Furthermore 546 expressions can be grouped together using "()". 548 The operators supported in the expression are listed in the following 549 table. 551 +----------+-------------+------------------------------------------+ 552 | Operator | Description | Behavior | 553 +----------+-------------+------------------------------------------+ 554 | eq | equal | The attribute and operator values must | 555 | | | be identical for a match. | 556 | ne | not equal | The attribute and operator values are | 557 | | | not identical. | 558 | co | contains | The entire operator value must be a | 559 | | | substring of the attribute value for a | 560 | | | match. | 561 | sw | starts with | The entire operator value must be a | 562 | | | substring of the attribute value, | 563 | | | starting at the beginning of the | 564 | | | attribute value. This criterion is | 565 | | | satisfied if the two strings are | 566 | | | identical. | 567 | ew | ends with | The entire operator value must be a | 568 | | | substring of the attribute value, | 569 | | | matching at the end of the attribute | 570 | | | value. This criterion is satisfied if | 571 | | | the two strings are identical. | 572 | pr | present | If the attribute has a non-empty or non- | 573 | | (has value) | null value, or if it contains a non- | 574 | | | empty node for complex attributes there | 575 | | | is a match. | 576 | gt | greater | If the attribute value is greater than | 577 | | than | operator value, there is a match. The | 578 | | | actual comparison is dependent on the | 579 | | | attribute type. For string attribute | 580 | | | types, this is a lexicographical | 581 | | | comparison and for DateTime types, it is | 582 | | | a chronological comparison. For Integer | 583 | | | attributes it is a comparison by numeric | 584 | | | value. Boolean and Binary attributes | 585 | | | SHALL cause a failed response (HTTP | 586 | | | Status 400) with scimType of | 587 | | | invlaidFiler. | 588 | ge | greater | If the attribute value is greater than | 589 | | than or | or equal to the operator value, there is | 590 | | equal | a match. The actual comparison is | 591 | | | dependent on the attribute type. For | 592 | | | string attribute types, this is a | 593 | | | lexicographical comparison and for | 594 | | | DateTime types, it is a chronological | 595 | | | comparison. For Integer attributes it is | 596 | | | a comparison by numeric value. Boolean | 597 | | | and Binary attributes SHALL cause a | 598 | | | failed response (HTTP Status 400) with | 599 | | | scimType of invlaidFiler. | 600 | lt | less than | If the attribute value is less than | 601 | | | operator value, there is a match. The | 602 | | | actual comparison is dependent on the | 603 | | | attribute type. For string attribute | 604 | | | types, this is a lexicographical | 605 | | | comparison and for DateTime types, it is | 606 | | | a chronological comparison. For Integer | 607 | | | attributes it is a comparison by numeric | 608 | | | value. Boolean and Binary attributes | 609 | | | SHALL cause a failed response (HTTP | 610 | | | Status 400) with scimType of | 611 | | | invlaidFiler. | 612 | le | less than | If the attribute value is less than or | 613 | | or equal | equal to the operator value, there is a | 614 | | | match. The actual comparison is | 615 | | | dependent on the attribute type. For | 616 | | | string attribute types, this is a | 617 | | | lexicographical comparison and for | 618 | | | DateTime types, it is a chronological | 619 | | | comparison. For Integer attributes it is | 620 | | | a comparison by numeric value. Boolean | 621 | | | and Binary attributes SHALL cause a | 622 | | | failed response (HTTP Status 400) with | 623 | | | scimType of invlaidFiler. | 624 +----------+-------------+------------------------------------------+ 626 Table 2: Attribute Operators 628 +----------+-------------+------------------------------------------+ 629 | Operator | Description | Behavior | 630 +----------+-------------+------------------------------------------+ 631 | and | Logical And | The filter is only a match if both | 632 | | | expressions evaluate to true. | 633 | or | Logical or | The filter is a match if either | 634 | | | expression evaluates to true. | 635 | not | Not | The filter is a match if the expression | 636 | | function | evaluates to false. | 637 +----------+-------------+------------------------------------------+ 639 Table 3: Logical Operators 641 +----------+-------------+------------------------------------------+ 642 | Operator | Description | Behavior | 643 +----------+-------------+------------------------------------------+ 644 | ( ) | Precedence | Boolean expressions may be grouped using | 645 | | grouping | parentheses to change the standard order | 646 | | | of operations; i.e., evaluate OR logical | 647 | | | operators before logical AND operators. | 648 | [ ] | Complex | Service providers MAY support complex | 649 | | attribute | filters where expressions MUST be | 650 | | filter | applied to the same value of a parent | 651 | | grouping | attribute specified immediately before | 652 | | | the left square bracket ("["). The | 653 | | | expression within square brackets ("[" | 654 | | | and "]") MUST be a valid filter | 655 | | | expression based upon sub-attributes of | 656 | | | the parent attribute. Nested expressions | 657 | | | MAY be used. See examples below. | 658 +----------+-------------+------------------------------------------+ 660 Table 4: Grouping Operators 662 SCIM filters MUST conform to the following ABNF rules as per 663 [RFC5234] below: 665 FILTER = attrExp / logExp / valuePath / *1"not" "(" FILTER ")" 667 valuePath = attrPath "[" valFilter "]" 668 ; FILTER uses sub-attribs of a parent attrPath 670 valFilter = attrExp / logExp / *1"not" "(" valFilter ")" 672 attrExp = (attrPath SP "pr") / 673 (attrPath SP compareOp SP compValue) 675 logExp = FILTER SP ("and" / "or") SP FILTER 677 compValue = false / null / true / number / string 678 ; rules from JSON (RFC7159) 680 compareOp = "eq" / "ne" / "co" / 681 "sw" / "ew" / 682 "gt" / "lt" / 683 "ge" / "le" 685 attrPath = [URI ":"] ATTRNAME *1subAttr 686 ; SCIM attribute name 687 ; URI is SCIM "schema" URI 689 ATTRNAME = ALPHA *(nameChar) 691 nameChar = "-" / "_" / DIGIT / ALPHA 693 subAttr = "." ATTRNAME 694 ; a sub-attribute of a complex attribute 696 Figure 1: ABNF Specification of SCIM Filters 698 In the above ABNF, the "compValue" (comparison value) rule is built 699 on JSON Data Interchange format ABNF rules as specified in [RFC7159], 700 "DIGIT" and "ALPHA" are defined per Appendix B.1 of [RFC5234] and, 701 "URI" is defined per Appendix A of [RFC3986]. 703 Filters MUST be evaluated using standard order of operations 704 [Order-Operations]. Attribute operators have the highest precedence, 705 followed by the grouping operator (i.e, parentheses), followed by the 706 logical AND operator, followed by the logical OR operator. 708 If the specified attribute in a filter expression is a multi-valued 709 attribute, the resource MUST match if any of the instances of the 710 given attribute match the specified criterion; e.g. if a User has 711 multiple emails values, only one has to match for the entire User to 712 match. For complex attributes, a fully qualified Sub-Attribute MUST 713 be specified using standard attribute notation (Section 3.8). For 714 example, to filter by userName the parameter value is userName and to 715 filter by first name, the parameter value is name.givenName. 717 Providers MAY support additional filter operations if they choose. 718 Providers MUST decline to filter results if the specified filter 719 operation is not recognized and return a HTTP 400 error with an 720 appropriate human readable response. For example, if a client 721 specified an unsupported operator named 'regex' the service provider 722 should specify an error response description identifying the client 723 error; e.g., 'The operator 'regex' is not supported.' 725 String type attributes are case insensitive by default unless the 726 attribute type is defined as case exact. Attribute comparison 727 operators 'eq', 'co', and 'sw' MUST perform caseIgnore matching for 728 all string attributes unless the attribute is defined as case exact. 729 By default all string attributes are case insensitive. 731 Clients MAY query by schema or schema extensions by using a filter 732 expression including the "schemas" attribute. 734 The following are examples of valid filters. Some attributes (e.g. 735 rooms and rooms.number) are hypothetical extensions and are not part 736 of SCIM core schema: 738 filter=userName eq "bjensen" 740 filter=name.familyName co "O'Malley" 742 filter=userName sw "J" 744 filter=urn:ietf:params:scim:schemas:core:2.0:User:userName sw "J" 746 filter=title pr 748 filter=meta.lastModified gt "2011-05-13T04:42:34Z" 750 filter=meta.lastModified ge "2011-05-13T04:42:34Z" 752 filter=meta.lastModified lt "2011-05-13T04:42:34Z" 754 filter=meta.lastModified le "2011-05-13T04:42:34Z" 756 filter=title pr and userType eq "Employee" 758 filter=title pr or userType eq "Intern" 760 filter= 761 schemas eq "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" 763 filter=userType eq "Employee" and (emails co "example.com" or emails 764 co "example.org") 766 filter=userType ne "Employee" and not (emails co "example.com" or 767 emails co "example.org") 769 filter=userType eq "Employee" and (emails.type eq "work") 771 filter=userType eq "Employee" and emails[type eq "work" and 772 value co "@example.com"] 774 filter=emails[type eq "work" and value co "@example.com"] or 775 ims[type eq "xmpp" and value co "@foo.com"] 777 Figure 2: Example Filters 779 3.2.2.3. Sorting 781 Sort is OPTIONAL. Sorting allows clients to specify the order in 782 which resources are returned by specifying a combination of sortBy 783 and sortOrder URL parameters. 785 sortBy: The sortBy parameter specifies the attribute whose value 786 SHALL be used to order the returned responses. If the sortBy 787 attribute corresponds to a singular attribute, resources are 788 sorted according to that attribute's value; if it's a multi-valued 789 attribute, resources are sorted by the value of the primary 790 attribute (see Section 2.2 [I-D.ietf-scim-core-schema]), if any, 791 or else the first value in the list, if any. If the attribute is 792 complex the attribute name must be a path to a sub-attribute in 793 standard attribute notation (Section 3.8) ; e.g., 794 "sortBy=name.givenName". For all attribute types, if there is no 795 data for the specified "sortBy" value they are sorted via the 796 "sortOrder" parameter; i.e., they are ordered last if ascending 797 and first if descending. 799 sortOrder: The order in which the sortBy parameter is applied. 800 Allowed values are "ascending" and "descending". If a value for 801 sortBy is provided and no sortOrder is specified, the sortOrder 802 SHALL default to ascending. String type attributes are case 803 insensitive by default unless the attribute type is defined as a 804 case exact string. "sortOrder" MUST sort according to the 805 attribute type; i.e., for case insensitive attributes, sort the 806 result using case insensitive, unicode alphabetic sort order, with 807 no specific locale implied and for case exact attribute types, 808 sort the result using case sensitive, Unicode alphabetic sort 809 order. 811 3.2.2.4. Pagination 813 Pagination parameters can be used together to "page through" large 814 numbers of resources so as not to overwhelm the client or service 815 provider. Pagination is not session based hence clients SHOULD never 816 assume repeatable results. For example, a request for a list of 10 817 resources beginning with a startIndex of 1 may return different 818 results when repeated as a resource in the original result could be 819 deleted or new ones could be added in-between requests. Pagination 820 parameters and general behavior are derived from the OpenSearch 821 Protocol [OpenSearch]. 823 The following table describes the URL pagination parameters. 825 +------------+----------------------------+-------------------------+ 826 | Parameter | Description | Default | 827 +------------+----------------------------+-------------------------+ 828 | startIndex | The 1-based index of the | 1 | 829 | | first query result. A | | 830 | | value less than 1 SHALL be | | 831 | | interpreted as 1. | | 832 | count | Non-negative Integer. | None. When specified | 833 | | Specifies the desired | the service provider | 834 | | maximum number of query | MUST NOT return more | 835 | | results per page; e.g., | results than specified | 836 | | 10. A negative value SHALL | though MAY return fewer | 837 | | be interpreted as "0". A | results. If | 838 | | value of "0" indicates no | unspecified, the | 839 | | resource results are to be | maximum number of | 840 | | returned except for | results is set by the | 841 | | "totalResults". | service provider. | 842 +------------+----------------------------+-------------------------+ 844 Table 5: Pagination Request parameters 846 The following table describes the query response pagination 847 attributes specified by the service provider. 849 +--------------+----------------------------------------------------+ 850 | Element | Description | 851 +--------------+----------------------------------------------------+ 852 | itemsPerPage | Non-negative Integer. Specifies the number of | 853 | | query results returned in a query response page; | 854 | | e.g., 10. | 855 | totalResults | Non-negative Integer. Specifies the total number | 856 | | of results matching the client query; e.g., 1000. | 857 | startIndex | The 1-based index of the first result in the | 858 | | current set of query results; e.g., 1. | 859 +--------------+----------------------------------------------------+ 861 Table 6: Pagination Response Elements 863 For example, to retrieve the first 10 Users set the startIndex to 1 864 and the count to 10: 866 GET /Users?startIndex=1&count=10 867 Host: example.com 868 Accept: application/scim+json 869 Authorization: Bearer h480djs93hd8 870 The response to the query above returns metadata regarding paging 871 similar to the following example (actual resources removed for 872 brevity): 874 { 875 "totalResults":100, 876 "itemsPerPage":10, 877 "startIndex":1, 878 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 879 "Resources":[{ 880 ... 881 }] 882 } 884 Figure 3: ListResponse format for returning multiple resources 886 Given the example above, to continue paging set the startIndex to 11 887 and re-fetch; i.e., /Users?startIndex=11&count=10 889 3.2.2.5. Attributes 891 The following attributes control which attributes SHALL be returned 892 with a returned resource. SCIM clients MAY use up to one of these 893 two OPTIONAL parameters which MUST be supported by SCIM service 894 providers: 896 attributes A multi-valued list of strings indicating the names of 897 resource attributes to return in the response overriding the set 898 of attributes that would be returned by default. Attribute names 899 MUST be in standard.attribute notation (Section 3.8) form. See 900 additional retrieval query parameters (Section 3.7). 902 excludedAttributes A multi-valued list of strings indicating the 903 names of resource attributes to be removed from the default set of 904 attributes to return. This parameter SHALL have no effect on 905 attributes whose schema "returned" setting is "always" see Server 906 Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in 907 standard attribute notation (Section 3.8) form. See additional 908 retrieval query parameters (Section 3.7). 910 3.2.3. Querying Resources Using HTTP POST 912 Clients MAY execute queries without passing parameters on the URL by 913 using the HTTP POST verb combined with the '/.search' path extension. 914 The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL 915 be used to indicate the HTTP POST verb is intended to be a query 916 operation. 918 To create a new query result set, a SCIM client sends an HTTP POST 919 request to the desired SCIM resource endpoint (ending in '/.search'). 920 The body of the POST request MAY include any of the parameters as 921 defined in Section 3.2.2. 923 Query requests MUST be identified using the following URI: 924 'urn:ietf:params:scim:api:messages:2.0:SearchRequest'. The following 925 attributes are defined for query requests: 927 attributes A multi-valued list of strings indicating the names of 928 resource attributes to return in the response overriding the set 929 of attributes that would be returned by default. Attribute names 930 MUST be in standard attribute notation (Section 3.8) form. See 931 additional retrieval query parameters (Section 3.7). OPTIONAL. 933 excludedAttributes A multi-valued list of strings indicating the 934 names of resource attributes to be removed from the default set of 935 attributes to return. This parameter SHALL have no effect on 936 attributes whose schema "returned" setting is "always" see Server 937 Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in 938 standard attribute notation (Section 3.8) form. See additional 939 retrieval query parameters (Section 3.7). OPTIONAL. 941 filter The filter string used to request a subset of resources. The 942 filter string MUST be a valid filter (Section 3.2.2.2) expression. 943 OPTIONAL. 945 sortBy A string indicating the attribute whose value SHALL be used 946 to order the returned responses. The sortBy attribute MUST be in 947 standard attribute notation (Section 3.8) form. See sorting 948 (Section 3.2.2.3). OPTIONAL. 950 sortOrder A string indicating the order in which the sortBy 951 parameter is applied. Allowed values are "ascending" and 952 "descending". See sorting (Section 3.2.2.3). OPTIONAL. 954 startIndex An integer indicating the 1-based index of the first 955 query result. See pagination (Section 3.2.2.4). OPTIONAL. 957 count An integer indicating the desired maximum number of query 958 results per page. See pagination (Section 3.2.2.4). OPTIONAL. 960 After receiving a HTTP POST request, a response is returned as 961 specified in Section 3.2.2. 963 The following example shows an HTTP POST Query request with search 964 parameters attributes, filter, and count included: 966 POST /.search 967 Host: example.com 968 Accept: application/scim+json 969 Content-Type: application/scim+json 970 Authorization: Bearer h480djs93hd8 971 Content-Length: ... 973 { 974 "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], 975 "attributes": ["displayName", "userName"], 976 "filter": 977 "displayName sw \"smith\"", 978 "startIndex": 1, 979 "count": 10 980 } 982 Figure 4: Example POST Query Request 984 A query response is shown with the first page of results. For 985 brevity reasons, only two matches are shown: one User and one Group. 987 HTTP/1.1 200 OK 988 Content-Type: application/scim+json 989 Location: https://example.com/.search 990 { 991 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 992 "totalResults":100, 993 "itemsPerPage":10, 994 "startIndex":1, 995 "Resources":[ 996 { 997 "meta":{ 998 "location": 999 "https://example.com/Users/2819c223-7f76-413861904646", 1000 "resourceType":"User", 1001 "lastModified": ... 1002 }, 1003 "userName":"jsmith", 1004 "displayName":"Smith, James" 1005 }, 1006 { 1007 "meta":{ 1008 "location": 1009 "https://example.com/Groups/c8596b90-7539-4f20968d1908", 1010 "resourceType":"Group", 1011 "lastModified": ... 1012 }, 1013 "displayName":"Smith Family" 1014 }, 1015 ... 1016 ] 1017 } 1019 Figure 5: Example POST Query Response 1021 3.3. Modifying Resources 1023 Resources can be modified in whole or in part via PUT or PATCH, 1024 respectively. Implementers MUST support PUT as specified in 1025 Section 4.3 [RFC7231]. Resources such as Groups may be very large 1026 hence implementers SHOULD support HTTP PATCH [RFC5789] to enable 1027 partial resource modifications. 1029 3.3.1. Replacing with PUT 1031 HTTP PUT is used to perform a full update of a resource's attributes. 1032 Clients that MAY have previously retrieved the entire resource in 1033 advance and revised it, MAY replace the resource using an HTTP PUT. 1034 Because SCIM resource identifiers are typically assigned by the 1035 service provider, HTTP PUT MUST NOT be used to create new resources. 1037 As the operation intent is to replace all attributes, SCIM clients 1038 MAY send all attributes regardless of each attribute's mutability. 1039 The server will apply attribute by attribute replace according to the 1040 following attribute mutability rules: 1042 readWrite, writeOnly Any values provided SHALL replace the existing 1043 attribute values. 1045 Attributes whose mutability is "readWrite", that are omitted from 1046 the request body, MAY be assumed to be not asserted by the client. 1047 The service provider MAY assume any existing values are to be 1048 cleared or the service provider MAY assign a default value to the 1049 final resource representation. Service providers MAY take into 1050 account whether a client has access to, or understands, all of the 1051 resource's attributes when deciding whether non-asserted 1052 attributes SHALL be removed or defaulted. Clients that would like 1053 to override a server defaults, MAY specify "null" for a single- 1054 valued attribute or an empty array "[]" for a multi-valued 1055 attribute to clear all values. 1057 immutable If value(s) are already set for the attribute, the input 1058 value(s) MUST match or HTTP status 400 SHOULD be returned with 1059 error code "mutability". If the service provider has no existing 1060 values, the new value(s) SHALL be applied. 1062 readOnly Any values provided (e.g. meta.resourceType) SHALL be 1063 ignored. 1065 If an attribute is "required", clients MUST specify the attribute in 1066 the PUT request. 1068 Unless otherwise specified a successful PUT operation returns a 200 1069 OK response code and the entire resource within the response body, 1070 enabling the client to correlate the client's and the service 1071 provider's views of the updated resource. Example: 1073 PUT /Users/2819c223-7f76-453a-919d-413861904646 1074 Host: example.com 1075 Accept: application/scim+json 1076 Content-Type: application/scim+json 1077 Authorization: Bearer h480djs93hd8 1078 If-Match: W/"a330bc54f0671c9" 1080 { 1081 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 1082 "id":"2819c223-7f76-453a-919d-413861904646", 1083 "userName":"bjensen", 1084 "externalId":"bjensen", 1085 "name":{ 1086 "formatted":"Ms. Barbara J Jensen III", 1087 "familyName":"Jensen", 1088 "givenName":"Barbara", 1089 "middleName":"Jane" 1090 }, 1091 "roles":[], 1092 "emails":[ 1093 { 1094 "value":"bjensen@example.com" 1095 }, 1096 { 1097 "value":"babs@jensen.org" 1098 } 1099 ] 1100 } 1101 The service responds with the entire, updated User: 1103 HTTP/1.1 200 OK 1104 Content-Type: application/scim+json 1105 ETag: W/"b431af54f0671a2" 1106 Location: 1107 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646" 1108 { 1109 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 1110 "id":"2819c223-7f76-453a-919d-413861904646", 1111 "userName":"bjensen", 1112 "externalId":"bjensen", 1113 "name":{ 1114 "formatted":"Ms. Barbara J Jensen III", 1115 "familyName":"Jensen", 1116 "givenName":"Barbara", 1117 "middleName":"Jane" 1118 }, 1119 "emails":[ 1120 { 1121 "value":"bjensen@example.com" 1122 }, 1123 { 1124 "value":"babs@jensen.org" 1125 } 1126 ], 1127 "meta": { 1128 "resourceType":"User", 1129 "created":"2011-08-08T04:56:22Z", 1130 "lastModified":"2011-08-08T08:00:12Z", 1131 "location": 1132 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 1133 "version":"W\/\"b431af54f0671a2\"" 1134 } 1135 } 1137 3.3.2. Modifying with PATCH 1139 HTTP PATCH is an OPTIONAL server function that enables clients to 1140 update one or more attributes of a SCIM resource using a sequence of 1141 operations to "add", "remove", or "replace" values. The general form 1142 of the SCIM patch request is based on JavaScript Object Notation 1143 (JSON) Patch [RFC6902]. One difference between SCIM patch and JSON 1144 patch is that SCIM servers do not support array indexing and may not 1145 support all [RFC6902] operation types. 1147 The body of each request MUST contain the following "schemas" 1148 attribute with the URI value of: 1149 "urn:ietf:params:scim:api:messages:2.0:PatchOp". 1151 The body of an HTTP PATCH request MUST contain the attribute 1152 "Operations", whose value is an array of one or more patch 1153 operations. Each patch operation object MUST have exactly one "op" 1154 member, whose value indicates the operation to perform and MAY be one 1155 of "add", "remove", or "replace". The semantics of each operation 1156 are defined in the following sub-sections. 1158 The following is an example representation of a PATCH request showing 1159 the basic JSON structure (non-normative): 1161 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1162 "Operations":[ 1163 { 1164 "op":"add", 1165 "path":"members", 1166 "value":[ 1167 { 1168 "display": "Babs Jensen", 1169 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1170 "value": "2819c223-7f76-453a-919d-413861904646" 1171 } 1172 ] 1173 }, 1174 ... + additional operations if needed ... 1175 ] 1176 } 1178 Figure 6: Example JSON body for SCIM PATCH Request 1180 A "path" attribute value is a String containing an attribute path 1181 describing the target of the operation. The "path" attribute is 1182 OPTIONAL for "add" and "replace" and is REQUIRED for "remove" 1183 operations. See relevant operation sections below for details. 1185 The "path" attribute is described by the following ABNF syntax rule: 1187 PATH = attrPath / valuePath [subAttr] 1189 Figure 7: SCIM Patch PATH Rule 1191 The ABNF rules, "attrPath", "valuePath", and "subAttr" are defined in 1192 Section 3.2.2.2. The "valuePath" rule allows specific values of a 1193 complex, multi-valued attribute to be selected. 1195 Valid examples of "path" values are as follows: 1197 "path":"members" 1199 "path":"name.familyName" 1201 "path":"addresses[type eq \"work\"]" 1203 "path":"members[value eq 1204 \"2819c223-7f76-453a-919d-413861904646\"]" 1206 "path":"members[value eq 1207 \"2819c223-7f76-453a-919d-413861904646\"].displayName" 1209 Figure 8: Example Path Values 1211 Each operation against an attribute MUST be compatible with the 1212 attribute's mutability and schema as defined in the Attribute Types 1213 Section of [I-D.ietf-scim-core-schema]. For example, a client MUST 1214 NOT modify an attribute that has mutability "readOnly" or 1215 "immutable". However, a client MAY "add" a value to an "immutable" 1216 attribute if the attribute had no previous value. An operation that 1217 is not compatibile with an attribute's mutability or schema SHALL 1218 return the appropriate HTTP response status code and a JSON detail 1219 error response as defined in Section 3.10. 1221 The attribute notation rules described in Section 3.8 apply for 1222 describing attribute paths. For all operations, the value of the 1223 "schemas" attribute on the SCIM service provider's representation of 1224 the resource SHALL be assumed by default. If one of the PATCH 1225 operations modifies the "schemas" attribute, subsequent operations 1226 SHALL assume the modified state of the "schemas" attribute. Clients 1227 MAY implicitly modify the "schemas" attribute by adding (or 1228 replacing) an attribute with its fully qualified name including 1229 schema URN. For example, adding the attribute "urn:ietf:params:scim: 1230 schemas:extension:enterprise:2.0:User:employeeNumber", automatically 1231 adds the value 1232 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" to the 1233 resource's "schemas" attribute. 1235 Each patch operation represents a single action to be applied to the 1236 same SCIM resource specified by the request URI. Operations are 1237 applied sequentially in the order they appear in the array. Each 1238 operation in the sequence is applied to the target resource; the 1239 resulting resource becomes the target of the next operation. 1240 Evaluation continues until all operations are successfully applied or 1241 until an error condition is encountered. 1243 For a multi-valued attributes, a patch operation that sets a value's 1244 "primary" attribute to "true", SHALL cause the server to 1245 automatically set "primary" to "false" for any other values in the 1246 array as only one value MAY be primary. 1248 A patch request, regardless of the number of operations, SHALL be 1249 treated as atomic. If a single operation encounters an error 1250 condition, the original SCIM resource MUST be restored, and a failure 1251 status SHALL be returned. 1253 If a request fails, the server SHALL return an HTTP response status 1254 code and a JSON detail error response as defined in Section 3.10. 1256 On successful completion, the server MUST return either a 200 OK 1257 response code and the entire resource (subject to the "attributes" 1258 query parameter - see Additional Retrieval Query Parameters 1259 (Section 3.7) ) within the response body, or a 204 No Content 1260 response code and the appropriate response headers for a successful 1261 patch request. The server MUST return a 200 OK if the "attributes" 1262 parameter is specified on the request. 1264 3.3.2.1. Add Operation 1266 The "add" operation is used to add a new attribute value to an 1267 existing resource. 1269 The operation MUST contain a "value" member whose content specifies 1270 the value to be added. The value MAY be a quoted value OR it may be 1271 a JSON object containing the sub-attributes of the complex attribute 1272 specified in the operation's "path". 1274 The result of the add operation depends upon what the target location 1275 indicated by "path" references: 1277 o If omitted, the target location is assumed to be the resource 1278 itself. The "value" parameter contains a set of attributes to be 1279 added to the resource. 1281 o If the target location does not exist, the attribute and value is 1282 added. 1284 o If the target location specifies a complex attribute, a set of 1285 sub-attributes SHALL be specified in the "value" parameter. 1287 o If the target location specifies a multi-valued attribute, a new 1288 value is added to the attribute. 1290 o if the target location specifies a single-valued attribute, the 1291 existing value is replaced. 1293 o If the target location specifies an attribute that does not exist 1294 (has no value), the attribute is added with the new value. 1296 o If the target location exists, the value is replaced. 1298 o If the target location already contains the value specified, no 1299 changes SHOULD be made to the resource and a success response 1300 SHOULD be returned. Unless other operations change the resource, 1301 this operation SHALL NOT change the modify timestamp of the 1302 resource. 1304 The following example shows how to add a member to a group. Some 1305 text removed for readability ("..."): 1307 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1308 Host: example.com 1309 Accept: application/scim+json 1310 Content-Type: application/scim+json 1311 Authorization: Bearer h480djs93hd8 1312 If-Match: W/"a330bc54f0671c9" 1313 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1314 "Operations":[ 1315 { 1316 "op":"add", 1317 "path":"members", 1318 "value":[ 1319 { 1320 "display": "Babs Jensen", 1321 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1322 "value": "2819c223-7f76-453a-919d-413861904646" 1323 } 1324 ] 1325 } 1326 ] 1327 } 1329 If the user was already a member of this group, no changes should be 1330 made to the resource and a success response should be returned. The 1331 server responds with either the entire updated Group or no response 1332 body: 1334 HTTP/1.1 204 No Content 1335 Authorization: Bearer h480djs93hd8 1336 ETag: W/"b431af54f0671a2" 1337 Location: 1338 "https://example.com/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" 1340 The following example shows how to add one or more attributes to a 1341 User resource without using a "path" attribute. 1343 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1344 Host: example.com 1345 Accept: application/scim+json 1346 Content-Type: application/scim+json 1347 Authorization: Bearer h480djs93hd8 1348 If-Match: W/"a330bc54f0671c9" 1350 { 1351 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1352 "Operations":[{ 1353 "op":"add", 1354 "value":{ 1355 "emails":[ 1356 { 1357 "value":"babs@jensen.org", 1358 "type":"home" 1359 } 1360 ], 1361 "nickname":"Babs" 1362 }] 1363 } 1365 In the above example, an additional value is added to the multi- 1366 valued attribute "emails". The second attribute, "nickname" is added 1367 to the User resource. If the resource already had an existing 1368 "nickname", the value is replaced per the processing rules above for 1369 single-valued attributes. 1371 3.3.2.2. Remove Operation 1373 The "remove" operation removes the value at the target location 1374 specified by the required attribute "path". The operation performs 1375 the following functions depending on the target location specified by 1376 "path" : 1378 o If "path" is unspecified, the operation fails with HTTP status 1379 "400" and "scimType" of "noTarget". 1381 o If the target location is a single-value attribute, the attribute 1382 and its associated value is removed and the attribute SHALL be 1383 considered unassigned. 1385 o If the target location is a multi-valued attribute and no filter 1386 is specified, the attribute and all values are removed and the 1387 attribute SHALL be considered unassigned. 1389 o If the target location is a multi-valued attribute and a complex 1390 filter is specified comparing a "value", the values matched by the 1391 filter are removed. If after removal of the selected values, no 1392 other values remain, the multi-valued attribute SHALL be 1393 considered unassigned. 1395 o If the target location is a complex-multi-valued attribute and a 1396 complex filter is specified based on the attribute's sub- 1397 attributes, the matching records are removed. Sub-attributes 1398 whose values have been removed SHALL be considered unassigned. If 1399 the complex-multi-valued attribute has no remaining records, the 1400 attribute SHALL be considered unassigned. 1402 If an attribute is removed or becomes unassigned and is defined as a 1403 required attribute or a read-only attribute, the server SHALL return 1404 an HTTP response status code and a JSON detail error response as 1405 defined in Section 3.10 with a "scimType" error of "mutability". 1407 The following example shows how to remove a member from a group. As 1408 with the previous example, the "display" sub-attribute is optional. 1409 If the user was not a member of this group, no changes should be made 1410 to the resource and a success response should be returned. 1412 Note that server responses have been omitted for the rest of the 1413 PATCH examples. 1415 Remove a single member from a group. Some text removed for 1416 readability ("..."): 1418 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1419 Host: example.com 1420 Accept: application/scim+json 1421 Content-Type: application/scim+json 1422 Authorization: Bearer h480djs93hd8 1423 If-Match: W/"a330bc54f0671c9" 1425 { 1426 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1427 "Operations":[{ 1428 "op":"remove", 1429 "path":"members[value eq \"2819c223-7f76-...413861904646\"]" 1430 }] 1431 } 1433 Remove all members of a group: 1435 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1436 Host: example.com 1437 Accept: application/scim+json 1438 Content-Type: application/scim+json 1439 Authorization: Bearer h480djs93hd8 1440 If-Match: W/"a330bc54f0671c9" 1442 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1443 "Operations":[{ 1444 "op":"remove","path":"members" 1445 }] 1446 } 1448 Removal of a value from a complex-multi-valued attribute (request 1449 headers removed for brevity): 1451 { 1452 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1453 "Operations": [{ 1454 "op":"remove", 1455 "path":"emails[type eq \"work\" and value ew \"example.com\"]" 1456 }] 1457 } 1458 Example request to remove and add a member. Some text removed for 1459 readability ("..."): 1461 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1462 Host: example.com 1463 Accept: application/scim+json 1464 Content-Type: application/scim+json 1465 Authorization: Bearer h480djs93hd8 1466 If-Match: W/"a330bc54f0671c9" 1467 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1468 "Operations": [ 1469 { 1470 "op":"remove", 1471 "path":"members[value eq\"2819c223...919d-413861904646\"]" 1472 }, 1473 { 1474 "op":"add", 1475 "path":"members", 1476 "value": [ 1477 { 1478 "display": "James Smith", 1479 "$ref":"https://example.com/v2/Users/08e1d05d...473d93df9210", 1480 "value": "08e1d05d...473d93df9210" 1481 } 1482 ] 1483 } 1484 ] 1485 } 1486 The following example shows how to replace all the members of a group 1487 with a different members list. Some text removed for readabilty 1488 ("..."): 1490 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1491 Host: example.com 1492 Accept: application/scim+json 1493 Content-Type: application/scim+json 1494 Authorization: Bearer h480djs93hd8 1495 If-Match: W/"a330bc54f0671c9" 1496 { 1497 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1498 "Operations": [ 1499 { 1500 "op":"remove","path":"members" 1501 }, 1502 { 1503 "op":"add", 1504 "path":"members", 1505 "value":[ 1506 { 1507 "display": "Babs Jensen", 1508 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1509 "value": "2819c223-7f76-453a-919d-413861904646" 1510 }, 1511 { 1512 "display": "James Smith", 1513 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1514 "value": "08e1d05d-121c-4561-8b96-473d93df9210" 1515 }] 1516 } 1517 ] 1518 } 1520 3.3.2.3. Replace Operation 1522 The "replace" operation replaces the value at the target location 1523 specified by the "path". The operation performs the following 1524 functions depending on the target location specified by "path" : 1526 o If the "path" parameter is omitted, the target is assumed to be 1527 the resource itself. In this case, the "value" attribute SHALL 1528 contain a list of one or more attributes that are to be replaced. 1530 o If the target location is a single-value attribute, the attributes 1531 value is replaced. 1533 o If the target location is a multi-valued attribute and no filter 1534 is specified, the attribute and all values are replaced. 1536 o If the target location path specifies an attribute that does not 1537 exist, the service provider SHALL treat the operation as an "add". 1539 o If the target location specifies a complex attribute, a set of 1540 sub-attributes SHALL be specified in the "value" parameter which 1541 replaces any existing values or adds where an attribute did not 1542 previously exist. Sub-attributes that are not specified in the 1543 "value" parameter are left unchanged. 1545 o If the target location is a multi-valued attribute and a value 1546 selction ("valuePath") filter is specified that matches one or 1547 more values of the mulit-valued attribute, then all matching 1548 record values SHALL be replaced. 1550 o If the target location is a complex-multi-valued attribute with a 1551 value selection filter ("valuePath") and a specific sub-attribute 1552 (e.g. "addresses[type eq "work"].streetAddress" ), the matching 1553 sub-attribute of all matching records is replaced. 1555 o If the target location is a mulit-valued attribute for which a 1556 value selection filter ("valuePath") has been supplied and no 1557 record match was made, the service provider SHALL fail by 1558 returning HTTP status "400", and a "scimType" of "noTarget". 1560 The following example shows how to replace all the members of a group 1561 with a different members list in a single replace operation. Some 1562 text removed for readability ("..."): 1564 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1565 Host: example.com 1566 Accept: application/scim+json 1567 Content-Type: application/scim+json 1568 Authorization: Bearer h480djs93hd8 1569 If-Match: W/"a330bc54f0671c9" 1571 { 1572 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1573 "Operations": [{ 1574 "op":"replace", 1575 "path":"members", 1576 "value":[ 1577 { 1578 "display": "Babs Jensen", 1579 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1580 "value": "2819c223...413861904646" 1581 }, 1582 { 1583 "display": "James Smith", 1584 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1585 "value": "08e1d05d...473d93df9210" 1586 } 1587 ] 1588 }] 1589 } 1590 The following example shows how to change a User's entire "work" 1591 address using a "valuePath" filter. Note that by setting "primary" 1592 to "true", the service provider will reset primary to "false" for any 1593 other existing values of "addresses". 1595 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1596 Host: example.com 1597 Accept: application/scim+json 1598 Content-Type: application/scim+json 1599 Authorization: Bearer h480djs93hd8 1600 If-Match: W/"a330bc54f0671c9" 1602 { 1603 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1604 "Operations": [{ 1605 "op":"replace", 1606 "path":"addresses[type eq \"work\"]", 1607 "value": 1608 { 1609 "type": "work", 1610 "streetAddress": "911 Universal City Plaza", 1611 "locality": "Hollywood", 1612 "region": "CA", 1613 "postalCode": "91608", 1614 "country": "US", 1615 "formatted": "911 Universal City Plaza\nHollywood, CA 91608 US", 1616 "primary": true 1617 } 1618 }] 1619 } 1620 The following example shows how to change a specific sub-attribute 1621 "streetAddress" of complex attribute "emails" selected by "valuePath" 1622 filter: 1624 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1625 Host: example.com 1626 Accept: application/scim+json 1627 Content-Type: application/scim+json 1628 Authorization: Bearer h480djs93hd8 1629 If-Match: W/"a330bc54f0671c9" 1631 { 1632 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1633 "Operations": [{ 1634 "op":"replace", 1635 "path":"addresses[type eq \"work\"].streetAddress", 1636 "value":"1010 Broadway Ave" 1637 }] 1638 } 1639 The following example shows how to replace all values of one or more 1640 specific attributes of a User resource. Note that other attributes 1641 are unaffected. 1643 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1644 Host: example.com 1645 Accept: application/scim+json 1646 Content-Type: application/scim+json 1647 Authorization: Bearer h480djs93hd8 1648 If-Match: W/"a330bc54f0671c9" 1650 { 1651 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1652 "Operations": [{ 1653 "op":"replace", 1654 "value":"{ 1655 "emails":[ 1656 { 1657 "value":"bjensen@example.com", 1658 "type":"work", 1659 "primary":true 1660 }, 1661 { 1662 "value":"babs@jensen.org", 1663 "type":"home" 1664 } 1665 ], 1666 "nickname":"Babs" 1667 }] 1668 } 1670 3.4. Deleting Resources 1672 Clients request resource removal via DELETE. Service providers MAY 1673 choose not to permanently delete the resource, but MUST return a 404 1674 error code for all operations associated with the previously deleted 1675 Id. Service providers MUST also omit the resource from future query 1676 results. In addition the service provider SHOULD NOT consider the 1677 deleted resource in conflict calculation. For example if a User 1678 resource is deleted, a CREATE request for a User resource with the 1679 same userName as the previously deleted resource should not fail with 1680 a 409 error due to userName conflict. 1682 DELETE /Users/2819c223-7f76-453a-919d-413861904646 1683 Host: example.com 1684 Authorization: Bearer h480djs93hd8 1685 If-Match: W/"c310cd84f0281b7" 1687 In response to a successful delete, the server SHALL respond with 1688 successful HTTP status 204 (No Content). A non-normative example 1689 response: 1691 HTTP/1.1 204 No Content 1693 Example: client attempt to retrieve the previously deleted User 1695 GET /Users/2819c223-7f76-453a-919d-413861904646 1696 Host: example.com 1697 Authorization: Bearer h480djs93hd8 1699 Server Response: 1701 HTTP/1.1 404 NOT FOUND 1703 { 1704 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 1705 "Errors":[ 1706 { 1707 "description": 1708 "Resource 2819c223-7f76-453a-919d-413861904646 not found", 1709 "code":"404" 1710 } 1711 ] 1712 } 1714 3.5. Bulk Operations 1716 The SCIM bulk operation is an optional server feature that enables 1717 clients to send a potentially large collection of resource operations 1718 in a single request. The body of a a bulk operation contains a set 1719 of HTTP resource operations using one of the API supported HTTP 1720 methods; i.e., POST, PUT, PATCH or DELETE. 1722 Bulk requests are identified using the following URI: 1723 "urn:ietf:params:scim:api:messages:2.0:BulkRequest". Bulk responses 1724 are identified using the following URI: 1725 "urn:ietf:params:scim:api:messages:2.0:BulkResponse". Bulk requests 1726 and bulk responses share many attributes. Unless otherwise 1727 specified, each attribute below is present in both bulk requests and 1728 bulk responses. 1730 The following Singular Attribute is defined in addition to the common 1731 attributes defined in SCIM core schema. 1733 failOnErrors 1734 An Integer specifying the number of errors that the service 1735 provider will accept before the operation is terminated and an 1736 error response is returned. OPTIONAL in a request. Not valid in 1737 a response. 1739 The following Complex Multi-valued Attribute is defined in addition 1740 to the common attributes defined in core schema. 1742 Operations 1743 Defines operations within a bulk job. Each operation corresponds 1744 to a single HTTP request against a resource endpoint. REQUIRED. 1745 Operations has the following sub-attributes: 1747 method The HTTP method of the current operation. Possible values 1748 are POST, PUT, PATCH or DELETE. REQUIRED. 1750 bulkId The transient identifier of a newly created resource, 1751 unique within a bulk request and created by the client. The 1752 bulkId serves as a surrogate resource id enabling clients to 1753 uniquely identify newly created resources in the Response and 1754 cross reference new resources in and across operations within a 1755 bulk request. REQUIRED when method is POST. 1757 version The current resource version. Version is MAY be used if 1758 the service provider supports ETags and the method is PUT, 1759 PATCH, or DELETE. 1761 path The resource's relative path. If the method is POST the 1762 value must specify a resource type endpoint; e.g., /Users or 1763 /Groups whereas all other method values must specify the path 1764 to a specific resource; e.g., /Users/2819c223-7f76-453a-919d- 1765 413861904646. REQUIRED in a request. 1767 data The resource data as it would appear for a single POST, PUT 1768 or PATCH resource operation. REQUIRED in a request when method 1769 is POST, PUT and PATCH. 1771 location The resource endpoint URL. REQUIRED in a response, 1772 except in the event of a POST failure. 1774 response The HTTP response body to the specified request 1775 operation. When indicating a response with an HTTP status 1776 other than a 200 series response, the response body MUST be 1777 included. For normal completion, the server MAY elect to omit 1778 the response body. 1780 status The HTTP response status code to the requested operation. 1781 When indicating an error, the "response" attribute MUST contain 1782 the detailed error response as per Section 3.10. 1784 If a bulk job is processed successfully the HTTP response code 200 OK 1785 MUST be returned, otherwise an appropriate HTTP error code MUST be 1786 returned. 1788 The service provider MUST continue performing as many changes as 1789 possible and disregard partial failures. The client MAY override 1790 this behavior by specifying a value for the "failOnErrors" attribute. 1791 The failOnErrors attribute defines the number of errors that the 1792 service provider should accept before failing the remaining 1793 operations returning the response. 1795 To be able to reference a newly created resource the attribute bulkId 1796 MUST be specified when creating new resources. The "bulkId" is 1797 defined by the client as a surrogate identifier in a POST operation 1798 (see Section 3.5.2). The service provider MUST return the same 1799 "bulkId" together with the newly created resource. The "bulkId" can 1800 then be used by the client to map the service provider id with the 1801 "bulkId" of the created resource. 1803 A SCIM service provider MAY elect to optimize a sequence operations 1804 received (e.g. to improve processing performance). When doing so, 1805 the service provider MUST ensure the clients intent is preserved and 1806 the same stateful result is achieved as for non-optimized processing. 1807 For example, before a "User" can be added to a "Group", they must 1808 first be created. Processing these requests out of order, might 1809 result in a failure to add the new "User" to the "Group". 1811 3.5.1. Circular Reference Processing 1813 The service provider MUST try to resolve circular cross references 1814 between resources in a single bulk job but MAY stop after a failed 1815 attempt and instead return the status code 409 Conflict. The 1816 following example exhibits the potential conflict. 1818 POST /v2/Bulk 1819 Host: example.com 1820 Accept: application/scim+json 1821 Content-Type: application/scim+json 1822 Authorization: Bearer h480djs93hd8 1823 Content-Length: ... 1825 { 1826 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 1827 "Operations": [ 1828 { 1829 "method": "POST", 1830 "path": "/Groups", 1831 "bulkId": "qwerty", 1832 "data": { 1833 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1834 "displayName": "Group A", 1835 "members": [ 1836 { 1837 "type": "Group", 1838 "value": "bulkId:ytrewq" 1839 } 1840 ] 1841 } 1842 }, 1843 { 1844 "method": "POST", 1845 "path": "/Groups", 1846 "bulkId": "ytrewq", 1847 "data": { 1848 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1849 "displayName": "Group B", 1850 "members": [ 1851 { 1852 "type": "Group", 1853 "value": "bulkId:qwerty" 1854 } 1855 ] 1856 } 1857 } 1858 ] 1859 } 1861 If the service provider resolved the above circular references the 1862 following is returned from a subsequent GET request. 1864 GET /v2/Groups?filter=displayName sw 'Group' 1865 Host: example.com 1866 Accept: application/scim+json 1867 Authorization: Bearer h480djs93hd8 1869 HTTP/1.1 200 OK 1870 Content-Type: application/scim+json 1872 { 1873 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 1874 "totalResults": 2, 1875 "Resources": [ 1876 { 1877 "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1878 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1879 "displayName": "Group A", 1880 "meta": { 1881 "resourceType": "Group", 1882 "created": "2011-08-01T18:29:49.793Z", 1883 "lastModified": "2011-08-01T18:29:51.135Z", 1884 "location": 1885 "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1886 "version": "W\/\"mvwNGaxB5SDq074p\"" 1887 }, 1888 "members": [ 1889 { 1890 "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1891 "$ref": 1892 "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1893 "type": "Group" 1894 } 1895 ] 1896 }, 1897 { 1898 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1899 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1900 "displayName": "Group B", 1901 "meta": { 1902 "resourceType": "Group", 1903 "created": "2011-08-01T18:29:50.873Z", 1904 "lastModified": "2011-08-01T18:29:50.873Z", 1905 "location": 1906 "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1907 "version": "W\/\"wGB85s2QJMjiNnuI\"" 1908 }, 1909 "members": [ 1910 { 1911 "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1912 "$ref": 1913 "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1914 "type": "Group" 1915 } 1916 ] 1917 } 1918 ] 1919 } 1921 3.5.2. BulkdId Temporary Identifiers 1923 A SCIM client can, within one bulk operation, create a new "User", a 1924 new "Group" and add the newly created "User" to the newly created 1925 "Group". In order to add the new "User" to the "Group" the client 1926 must use the surrogate id attribute, "bulkId", to reference the User. 1927 The "bulkId" attribute value must be pre-pended with the literal 1928 "bulkId:"; e.g., if the bulkId is 'qwerty', the value is 1929 "bulkId:qwerty". The service provider MUST replace the string 1930 "bulkId:qwerty" with the permanent resource id once created. 1932 To create multiple distinct requests, each with their own "bulkId", 1933 the SCIM client specifies different "bulkId" values for each separate 1934 request. 1936 The following example creates a User with the "userName" 'Alice' and 1937 a "Group" with the "displayName" 'Tour Guides' with Alice as a 1938 member. Notice that each operation has its own "bulkId" value. 1939 However, the second operation (whose "bulkId" is "ytrewq") refers to 1940 the "bulkId" of "qwerty" in order to add Alice to new 'Tour Guides' 1941 group. 1943 POST /v2/Bulk 1944 Host: example.com 1945 Accept: application/scim+json 1946 Content-Type: application/scim+json 1947 Authorization: Bearer h480djs93hd8 1948 Content-Length: ... 1950 { 1951 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 1952 "Operations": [ 1953 { 1954 "method": "POST", 1955 "path": "/Users", 1956 "bulkId": "qwerty", 1957 "data": { 1958 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 1959 "userName": "Alice" 1960 } 1961 }, 1962 { 1963 "method": "POST", 1964 "path": "/Groups", 1965 "bulkId": "ytrewq", 1966 "data": { 1967 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1968 "displayName": "Tour Guides", 1969 "members": [ 1970 { 1971 "type": "User", 1972 "value": "bulkId:qwerty" 1973 } 1974 ] 1975 } 1976 } 1977 ] 1978 } 1979 The service provider returns the following response: 1981 HTTP/1.1 200 OK 1982 Content-Type: application/json 1984 { 1985 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 1986 "Operations": [ 1987 { 1988 "location": 1989 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1990 "method": "POST", 1991 "bulkId": "qwerty", 1992 "version": "W\/\"4weymrEsh5O6cAEK\"", 1993 "status": { 1994 "code": "201" 1995 } 1996 }, 1997 { 1998 "location": 1999 "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 2000 "method": "POST", 2001 "bulkId": "ytrewq", 2002 "version": "W\/\"lha5bbazU3fNvfe5\"", 2003 "status": { 2004 "code": "201" 2005 } 2006 } 2007 ] 2008 } 2010 In the above example, the Alice User resource has an "id" of 2011 "92b725cd-9465-4e7d-8c16-01f8e146b87a" and the Tour Guides Group has 2012 an "id" of "e9e30dba-f08f-4109-8486-d5c6a331660a". 2014 A subsequent GET request for the 'Tour Guides' Group (with an "id" 2015 of"e9e30dba-f08f-4109-8486-d5c6a331660a") returns the following with 2016 Alice's "id" as the value for the member in the Group 'Tour Guides': 2018 HTTP/1.1 200 OK 2019 Content-Type: application/scim+json 2020 Location: 2021 https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 2022 ETag: W/"lha5bbazU3fNvfe5" 2024 { 2025 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 2026 "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", 2027 "displayName": "Tour Guides", 2028 "meta": { 2029 "resourceType": "Group", 2030 "created": "2011-08-01T18:29:49.793Z", 2031 "lastModified": "2011-08-01T20:31:02.315Z", 2032 "location": 2033 "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 2034 "version": "W\/\"lha5bbazU3fNvfe5\"" 2035 }, 2036 "members": [ 2037 { 2038 "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", 2039 "$ref": 2040 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2041 "type": "User" 2042 } 2043 ] 2044 } 2046 Extensions that include references to other resources MUST be handled 2047 in the same way by the service provider. The following example uses 2048 the bulkId attribute within the enterprise extension managerId 2049 attribute. 2051 POST /v2/Bulk 2052 Host: example.com 2053 Accept: application/scim+json 2054 Content-Type: application/scim+json 2055 Authorization: Bearer h480djs93hd8 2056 Content-Length: ... 2058 { 2059 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 2060 "Operations": [ 2061 { 2062 "method": "POST", 2063 "path": "/Users", 2064 "bulkId": "qwerty", 2065 "data": { 2066 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 2067 "userName": "Alice" 2068 } 2069 }, 2070 { 2071 "method": "POST", 2072 "path": "/Users", 2073 "bulkId": "ytrewq", 2074 "data": { 2075 "schemas": [ 2076 "urn:ietf:params:scim:schemas:core:2.0:User", 2077 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" 2078 ], 2079 "userName": "Bob", 2080 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { 2081 "employeeNumber": "11250", 2082 "manager": { 2083 "managerId": "batchId:qwerty", 2084 "displayName": "Alice" 2085 } 2086 } 2087 } 2088 } 2089 ] 2090 } 2092 3.5.3. Response and Error Handling 2094 The service provider response MUST include the result of all 2095 processed operations. A "location" attribute that includes the 2096 resource's endpoint MUST be returned for all operations excluding 2097 failed POSTs. The status attribute includes information about the 2098 success or failure of one operation within the bulk job. The 2099 attribute status MUST include the code attribute that holds the HTTP 2100 response code that would have been returned if a single HTTP request 2101 would have been used. If an error occurred the status MUST also 2102 include the description attribute containing a human readable 2103 explanation of the error. 2105 "status": "201" 2107 The following is an example of a status in a failed operation. 2109 "status": "400", 2110 "response":{ 2111 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2112 "scimType":"invalidSyntax" 2113 "detail": 2114 "Request is unparseable, syntactically incorrect, or violates schema.", 2115 "status":"400" 2116 } 2118 The following example shows how to add, update, and remove a user. 2119 The "failOnErrors" attribute is set to '1' indicating the service 2120 provider should return on the first error. The POST operation's 2121 bulkId value is set to 'qwerty' enabling the client to match the new 2122 User with the returned resource id '92b725cd-9465-4e7d- 2123 8c16-01f8e146b87a'. 2125 POST /v2/Bulk 2126 Host: example.com 2127 Accept: application/scim+json 2128 Content-Type: application/scim+json 2129 Authorization: Bearer h480djs93hd8 2130 Content-Length: ... 2132 { 2133 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 2134 "failOnErrors":1, 2135 "Operations":[ 2136 { 2137 "method":"POST", 2138 "path":"/Users", 2139 "bulkId":"qwerty", 2140 "data":{ 2141 "schemas": ["urn:ietf:params:scim:api:messages:2.0:User"], 2142 "userName":"Alice" 2143 } 2144 }, 2145 { 2146 "method":"PUT", 2147 "path":"/Users/b7c14771-226c-4d05-8860-134711653041", 2148 "version":"W\/\"3694e05e9dff591\"", 2149 "data":{ 2150 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 2151 "id":"b7c14771-226c-4d05-8860-134711653041", 2152 "userName":"Bob" 2153 } 2154 }, 2155 { 2156 "method": "PATCH", 2157 "path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2158 "version": "W/\"edac3253e2c0ef2\"", 2159 "data": {[ 2160 { 2161 "op": "remove", 2162 "path": "nickName" 2163 }, 2164 { 2165 "op": "add", 2166 "path": "userName", 2167 "value": "Dave" 2168 } 2169 ]} 2170 }, 2171 { 2172 "method":"DELETE", 2173 "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2174 "version":"W\/\"0ee8add0a938e1a\"" 2175 } 2176 ] 2177 } 2179 The service provider returns the following response. 2181 HTTP/1.1 200 OK 2182 Content-Type: application/scim+json 2184 { 2185 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2186 "Operations": [ 2187 { 2188 "location": 2189 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2190 "method": "POST", 2191 "bulkId": "qwerty", 2192 "version": "W\/\"oY4m4wn58tkVjJxK\"", 2193 "status": "201" 2194 }, 2195 { 2196 "location": 2197 "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 2198 "method": "PUT", 2199 "version": "W\/\"huJj29dMNgu3WXPD\"", 2200 "status": "200" 2201 }, 2202 { 2203 "location": 2204 "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2205 "method": "PATCH", 2206 "version": "W\/\"huJj29dMNgu3WXPD\"", 2207 "status": "200" 2208 }, 2209 { 2210 "location": 2211 "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2212 "method": "DELETE", 2213 "status": "204" 2214 } 2215 ] 2216 } 2218 The following response is returned if an error occurred when 2219 attempting to create the User 'Alice'. The service provider stops 2220 processing the bulk operation and immediately returns a response to 2221 the client. The response contains the error and any successful 2222 results prior to the error. 2224 HTTP/1.1 200 OK 2225 Content-Type: application/scim+json 2227 { 2228 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2229 "Operations": [ 2230 { 2231 "method": "POST", 2232 "bulkId": "qwerty", 2233 "status": "400", 2234 "response":{ 2235 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2236 "scimType":"invalidSyntax" 2237 "detail": 2238 "Request is unparseable, syntactically incorrect, or violates schema.", 2239 "status":"400" 2240 } 2241 } 2242 ] 2243 } 2245 If the "failOnErrors" attribute is not specified or the service 2246 provider has not reached the error limit defined by the client the 2247 service provider will continue to process all operations. The 2248 following is an example in which all operations failed. 2250 HTTP/1.1 200 OK 2251 Content-Type: application/scim+json 2253 { 2254 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2255 "Operations": [ 2256 { 2257 "method": "POST", 2258 "bulkId": "qwerty", 2259 "status": "400", 2260 "response":{ 2261 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2262 "scimType":"invalidSyntax" 2263 "detail": 2264 "Request is unparseable, syntactically incorrect, or violates schema.", 2265 "status":"400" 2266 } 2267 }, 2268 { 2269 "location": 2270 "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 2271 "method": "PUT", 2272 "status": "412", 2273 "response":{ 2274 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2275 "detail":"Failed to update. Resource changed on the server.", 2276 "status":"412" 2277 } 2278 }, 2279 { 2280 "location": 2281 "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2282 "method": "PATCH", 2283 "status": "412", 2284 "response":{ 2285 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2286 "detail":"Failed to update. Resource changed on the server.", 2287 "status":"412" 2288 } 2289 }, 2290 { 2291 "location": 2292 "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2293 "method": "DELETE", 2294 "status": "404", 2295 "response":{ 2296 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2297 "detail":"Resource does not exist.", 2298 "status":"404" 2299 } 2300 } 2301 ] 2302 } 2303 HTTP/1.1 200 OK 2304 Content-Type: application/scim+json 2306 { 2307 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2308 "Operations": [ 2309 { 2310 "location": 2311 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2312 "method": "POST", 2313 "bulkId": "qwerty", 2314 "version": "W\/\"4weymrEsh5O6cAEK\"", 2315 "status": "201" 2316 }, 2317 { 2318 "location": 2319 "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 2320 "method": "POST", 2321 "bulkId": "ytrewq", 2322 "version": "W\/\"lha5bbazU3fNvfe5\"", 2323 "status": "201" 2324 } 2325 ] 2326 } 2328 3.5.4. Maximum Operations 2330 The service provider MUST define the maximum number of operations and 2331 maximum payload size a client may send in a single request. These 2332 limits MAY be retrieved from the Service Provider Configuration (see 2333 'bulk' in Section 8 of [I-D.ietf-scim-core-schema]). If either 2334 limits are exceeded the service provider MUST return the HTTP 2335 response code 413 Request Entity Too Large. The returned response 2336 MUST specify the limit exceeded in the body of the error response. 2338 The following example the client sent a request exceeding the service 2339 provider's max payload size of 1 megabyte: 2341 POST /v2/Bulk 2342 Host: example.com 2343 Accept: application/scim+json 2344 Content-Type: application/scim+json 2345 Authorization: Bearer h480djs93hd8 2346 Content-Length: 4294967296 2348 ... 2350 In response to the over-sized request, the server responds with the 2351 following error: 2353 HTTP/1.1 413 Request Entity Too Large 2354 Content-Type: application/scim+json 2356 { 2357 "schemas":["urn:ietf:params:scim:api:messages:2.0:Error"], 2358 "status": "413", 2359 "detail": 2360 "The size of the bulk operation exceeds the maxPayloadSize (1048576)." 2361 } 2363 3.6. Data Input/Output Formats 2365 Servers MUST accept requests and respond with JSON structured 2366 responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default 2367 encoding format. 2369 Clients using other encodings MUST specify the format in which the 2370 data is submitted via HTTP header "Content-Type" as specified in 2371 Section 3.1.1.5 [RFC7231] and MAY specify the desired response data 2372 format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g., 2373 "Accept: application/scim+json" or via URI suffix; e.g., 2375 GET /Users/2819c223-7f76-453a-919d-413861904646.scim 2376 Host: example.com 2378 Service providers MUST support the accept header "Accept: 2379 application/scim+json" and SHOULD support header "Accept: 2380 application/json" both of which specify JSON documents conforming to 2381 [RFC7159]. The format defaults to "application/scim+json" if no 2382 format is specified. 2384 Singular attributes are encoded as string name-value-pairs in JSON; 2385 e.g., 2387 "attribute": "value" 2389 Multi-valued attributes in JSON are encoded as arrays; e.g., 2391 "attributes": [ "value1", "value2" ] 2393 Elements with nested elements are represented as objects in JSON; 2394 e.g, 2396 "attribute": { "subattribute1": "value1", "subattribute2": "value2" } 2398 3.7. Additional Operation Response Parameters 2400 For any SCIM operation where a resource representation is returned 2401 (e.g. HTTP GET), the attributes returned are defined as the minimum 2402 attribute set plus default attributes set. The minimum set are those 2403 attributes whose schema have "returned" set to "always". The default 2404 attribute set are those attributes whose schema have "returned" set 2405 to "default". 2407 Clients MAY request a partial resource representation on any 2408 operation that returns a resource within the response by specifying 2409 either of the mutually exclusive URL query parameters "attributes" OR 2410 "excludedAtributes" as follows: 2412 attributes When specified the default list of attributes SHALL be 2413 overridden and each resource returned MUST contain the 2414 minimum set of resource attributes and any attributes or sub- 2415 attributes explicitly requested by the "attributes" 2416 parameter. The query parameter attributes value is a comma 2417 separated list of resource attribute names in standard 2418 attribute notation (Section 3.8) form (e.g. userName, name, 2419 emails). 2421 excludedAttributes When specified, each resource returned MUST 2422 contain the minimal set of resource attributes. 2423 Additionally, the default set of attributes minus those 2424 attributes listed in "excludedAttributes" are also returned. 2425 The query parameter attributes value is a comma separated 2426 list of resource attribute names in standard attribute 2427 notation (Section 3.8) form (e.g. userName, name, emails). 2429 . 2431 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName 2432 Host: example.com 2433 Accept: application/scim+json 2434 Authorization: Bearer h480djs93hd8 2436 Giving the response 2437 HTTP/1.1 200 OK 2438 Content-Type: application/scim+json 2439 Location: 2440 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2441 ETag: W/"a330bc54f0671c9" 2443 { 2444 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2445 "id":"2819c223-7f76-453a-919d-413861904646", 2446 "userName":"bjensen", 2447 "meta":{ 2448 "resourceType": "User", 2449 "created":"2011-08-01T18:29:49.793Z", 2450 "lastModified":"2011-08-01T18:29:49.793Z", 2451 "location": 2452 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2453 "version":"W\/\"a330bc54f0671c9\"" 2454 } 2455 } 2457 3.8. Attribute Notation 2459 All operations share a common scheme for referencing simple and 2460 complex attributes. In general, attributes are identified by 2461 prefixing the attribute name with its schema URN separated by a ':' 2462 character; e.g., the core User resource attribute 'userName' is 2463 identified as "urn:ietf:params:scim:schemas:core:2.0:User:userName". 2464 Clients MAY omit core schema attribute URN prefixes though MUST fully 2465 qualify extended attributes with the associated resource URN; e.g., 2466 the attribute 'age' defined in 2467 "urn:ietf:params:scim:schemas:exampleCo:2.0:hr" is fully encoded as 2468 "urn:ietf:params:scim:schemas:exampleCo:2.0:hr:age". A Complex 2469 attributes' Sub-Attributes are referenced via nested, dot ('.') 2470 notation; i.e., {urn}:{Attribute name}.{Sub-Attribute name}. For 2471 example, the fully qualified path for a User's givenName is 2472 "urn:ietf:params:scim:schemas:core:2.0:User:name.givenName" All 2473 facets (URN, attribute and Sub-Attribute name) of the fully encoded 2474 Attribute name are case insensitive. 2476 3.9. "/Me" Authenticated Subject Alias 2478 A client MAY use a URL of the form "/Me" as a URI alias for 2479 the User or other resource associated with the currently 2480 authenticated subject for any SCIM operation. A service provider MAY 2481 respond in ONE of 3 ways: 2483 o A service provider that does NOT support this feature SHOULD 2484 respond with status 403 (FORBIDDEN). 2486 o A service provider MAY choose to redirect the client using HTTP 2487 status 308 to the resource associated with the authenticated 2488 subject. The client MAY then repeat the request at the indicated 2489 location. 2491 o A service provider MAY process the SCIM request directly. In any 2492 response, the HTTP "Location" header MUST be the permanent 2493 location of the aliased resource associated with the authenticated 2494 subject. 2496 When using the SCIM Create Resource command (HTTP POST) with the 2497 "/Me" alias, the desired resourceType being created is at the 2498 discretion of the service provider based on the authenticated subject 2499 (if not anonymous) making the request and any request body attributes 2500 (e.g. "schemas"). See Section 7.3 for information on security 2501 considerations related to this operation. 2503 3.10. HTTP Status and Error Response Handling 2505 The SCIM Protocol uses the HTTP status response status codes defined 2506 in Section 6 [RFC7231] to indicate operation success or failure. In 2507 addition to returning a HTTP response code implementers MUST return 2508 the errors in the body of the response in the client requested format 2509 containing the error response and, per the HTTP specification, human- 2510 readable explanations. Error responses are identified using the 2511 following "schema" URI: 2512 "urn:ietf:params:scim:api:messages:2.0:Error". The following 2513 attributes are defined for a SCIM error response using a JSON body: 2515 status 2516 The HTTP status code (see Section 6 [RFC7231]). REQUIRED 2518 scimType 2519 A SCIM detailed error keyword. See Table 8. OPTIONAL 2521 detail 2522 A detailed, human readable message. OPTIONAL 2524 Implementers SHOULD handle the identified HTTP status codes as 2525 described below. 2527 +--------------+---------------+------------------------------------+ 2528 | Status | Applicability | Suggested Explanation | 2529 +--------------+---------------+------------------------------------+ 2530 | 307 | GET, POST, | The client is directed to repeat | 2531 | TEMPORARY | PUT, PATCH, | the same HTTP request at the | 2532 | REDIRECT | DELETE | location identified. The client | 2533 | | | SHOULD NOT use the location | 2534 | | | provided in the response as a | 2535 | | | permanent reference to the | 2536 | | | resource and SHOULD continue to | 2537 | | | use the original request URI | 2538 | | | [RFC7231]. | 2539 | 308 | GET, POST, | The client is directed to repeat | 2540 | PERMANENT | PUT, PATCH, | the same HTTP request at the | 2541 | REDIRECT | DELETE | location identified. The client | 2542 | | | SHOULD use the location provided | 2543 | | | in the response as the permanent | 2544 | | | reference to the resource | 2545 | | | [RFC7238]. | 2546 | 400 BAD | GET, POST, | Request is unparseable, | 2547 | REQUEST | PUT, PATCH, | syntactically incorrect, or | 2548 | | DELETE | violates schema | 2549 | 401 | GET, POST, | Authorization failure | 2550 | UNAUTHORIZED | PUT, PATCH, | | 2551 | | DELETE | | 2552 | 403 | GET, POST, | Server does not support requested | 2553 | FORBIDDEN | PUT, PATCH, | operation | 2554 | | DELETE | | 2555 | 404 NOT | GET, POST, | Specified resource (e.g., User) or | 2556 | FOUND | PUT, PATCH, | end-point, does not exist | 2557 | | DELETE | | 2558 | 409 CONFLICT | POST, PUT, | The specified version number does | 2559 | | PATCH, DELETE | not match the resource's latest | 2560 | | | version number or a service | 2561 | | | provider refused to create a new, | 2562 | | | duplicate resource | 2563 | 412 | PUT, PATCH,D | Failed to update as resource {id} | 2564 | PRECONDITION | ELETE | changed on the server last | 2565 | FAILED | | retrieved | 2566 | 413 REQUEST | POST | {"maxOperations": | 2567 | ENTITY TOO | | 1000,"maxPayload": 1048576} | 2568 | LARGE | | | 2569 | 500 INTERNAL | GET, POST, | An internal error. Implementers | 2570 | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive | 2571 | | DELETE | debugging advice | 2572 | 501 NOT | GET, POST, | Service Provider does not support | 2573 | IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH | 2574 | | DELETE | | 2575 +--------------+---------------+------------------------------------+ 2577 Table 7: SCIM HTTP Status Code Usage 2579 For HTTP Status 400 (Bad Request) responses, the following detail 2580 error types are defined: 2582 +--------------+------------------------------+---------------------+ 2583 | scimType | Description | Applicability | 2584 +--------------+------------------------------+---------------------+ 2585 | invalidFilte | The specified filter syntax | GET(Section 3.2.2), | 2586 | r | was invalid (does not comply | POST (Search - | 2587 | | with Figure 1) or the | Section 3.2.3), | 2588 | | specified attribute and | PATCH (Path Filter | 2589 | | filter comparison | - Section 3.3.2) | 2590 | | combination is not | | 2591 | | supported. | | 2592 | tooMany | The specified filter yields | GET(Section 3.2.2), | 2593 | | many more results than the | POST (Search - | 2594 | | server is willing calculate | Section 3.2.3) | 2595 | | or process. For example, a | | 2596 | | filter such as "(userName | | 2597 | | pr)" by itself would return | | 2598 | | all entries with a | | 2599 | | "userName" and MAY not be | | 2600 | | acceptable to the service | | 2601 | | provider. | | 2602 | uniqueness | One or more of attribute | POST (Create - | 2603 | | values is already in use or | Section 3.1), PUT | 2604 | | is reserved. | (Section 3.3.1), | 2605 | | | PATCH (Section | 2606 | | | 3.3.2) | 2607 | mutability | The attempted modification | PUT (Section | 2608 | | is not compatible with the | 3.3.1), PATCH | 2609 | | target attributes mutability | (Section 3.3.2) | 2610 | | or current state (e.g. | | 2611 | | modification of an immutable | | 2612 | | attribute with an existing | | 2613 | | value). | | 2614 | invalidSynta | The request body message | POST (Search - | 2615 | x | structure was invalid or did | Section 3.2.2, | 2616 | | not conform to the request | Create - Section | 2617 | | schema. | 3.1, Bulk - Section | 2618 | | | 3.5), PUT (Section | 2619 | | | 3.3.1) | 2620 | invalidPath | The path attribute was | PATCH (Section | 2621 | | invalid or malformed (see | 3.3.2) | 2622 | | Figure 7). | | 2623 | noTarget | The specified "path" did not | PATCH (Section | 2624 | | yield an attribute or | 3.3.2) | 2625 | | attribute value that could | | 2626 | | be operated on. This occurs | | 2627 | | when the specified "path" | | 2628 | | value contains a filter that | | 2629 | | yields no match. | | 2630 | invalidValue | A required value was | GET (Section | 2631 | | missing, or the value | 3.2.2), POST | 2632 | | specified was not compatible | (Create - Section | 2633 | | with the operation or | 3.1, Query - | 2634 | | attribute type (see Section | Section 3.2.2), PUT | 2635 | | 2.1 [I-D.ietf-scim-core-sche | (Section 3.3.1), | 2636 | | ma]), or schema (see Section | PATCH (Section | 2637 | | 4 [I-D.ietf-scim-core-schema | 3.3.2) | 2638 | | ]). | | 2639 | invalidVers | The specified SCIM protocol | GET (Section | 2640 | | version is not supported | 3.2.2), POST (ALL), | 2641 | | (see Section 3.11). | PUT (Section | 2642 | | | 3.3.1), PATCH | 2643 | | | (Section 3.3.2), | 2644 | | | DELETE (Section | 2645 | | | 3.4) | 2646 +--------------+------------------------------+---------------------+ 2648 Table 8: Table of SCIM Detail Error Keyword Values 2650 Note that in the table above (Table 8), the applicability table 2651 applies to the normal HTTP method but MAY apply within a SCIM Bulk 2652 operation (via HTTP POST). 2654 Error example in response to a non-existent GET request. 2656 HTTP/1.1 404 NOT FOUND 2658 { 2659 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2660 "detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 2661 "status":"404 2662 } 2664 Error example in response to a PUT request. 2666 HTTP/1.1 400 BAD REQUEST 2668 { 2669 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2670 "scimType":"mutability" 2671 "detail":"Attribute 'id' is readOnly", 2672 "status":"400" 2673 } 2675 [[Editor's note: while the detail error codes seem to have consensus, 2676 there is a question about whether the error codes should be 2677 extensible so that individual service providers may define site 2678 specific codes. Should all scimTypes be URIs, so that scimTypes can 2679 be registered via IANA? Should there be a separate field defined for 2680 this purpose? Or, should custom signalling (for non-protocol/schema 2681 errors, be out of scope?]] 2683 3.11. API Versioning 2685 The Base URL MAY be appended with a version identifier as a separate 2686 segment in the URL path. At this time of this specification, the 2687 identifier is 'v2'. If specified, the version identifier MUST appear 2688 in the URL path immediately preceding the resource endpoint and 2689 conform to the following scheme: the character 'v' followed by the 2690 desired SCIM version number; e.g., a version 'v2' User request is 2691 specified as /v2/Users. When specified service providers MUST 2692 perform the operation using the desired version or reject the 2693 request. When omitted service providers SHOULD perform the operation 2694 using the most recent SCIM protocol version supported by the service 2695 provider. 2697 3.12. Versioning Resources 2699 The SCIM protocol supports resource versioning via standard HTTP 2700 ETags Section 2.3 [RFC7233]. Service providers MAY support weak 2701 ETags as the preferred mechanism for performing conditional 2702 retrievals and ensuring clients do not inadvertently overwrite each 2703 others changes, respectively. When supported SCIM ETags MUST be 2704 specified as an HTTP header and SHOULD be specified within the 2705 'version' attribute contained in the resource's 'meta' attribute. 2707 Example: 2709 POST /Users HTTP/1.1 2710 Host: example.com 2711 Content-Type: application/scim+json 2712 Authorization: Bearer h480djs93hd8 2713 Content-Length: ... 2715 { 2716 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2717 "userName":"bjensen", 2718 "externalId":"bjensen", 2719 "name":{ 2720 "formatted":"Ms. Barbara J Jensen III", 2721 "familyName":"Jensen", 2722 "givenName":"Barbara" 2723 } 2724 } 2726 The server responds with an ETag in the response header and meta 2727 structure. 2729 HTTP/1.1 201 Created 2730 Content-Type: application/scim+json 2731 Location: 2732 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2733 ETag: W/"e180ee84f0671b1" 2735 { 2736 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2737 "id":"2819c223-7f76-453a-919d-413861904646", 2738 "meta":{ 2739 "resourceType":"User", 2740 "created":"2011-08-01T21:32:44.882Z", 2741 "lastModified":"2011-08-01T21:32:44.882Z", 2742 "location": 2743 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2744 "version":"W\/\"e180ee84f0671b1\"" 2745 }, 2746 "name":{ 2747 "formatted":"Ms. Barbara J Jensen III", 2748 "familyName":"Jensen", 2749 "givenName":"Barbara" 2750 }, 2751 "userName":"bjensen" 2752 } 2754 With the returned ETag, clients MAY choose to retrieve the resource 2755 only if the resource has been modified. 2757 Conditional retrieval example using If-None-Match Section 3.2 2758 [RFC7233] header: 2760 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName 2761 Host: example.com 2762 Accept: application/scim+json 2763 Authorization: Bearer h480djs93hd8 2764 If-None-Match: W/"e180ee84f0671b1" 2766 If the resource has not changed the service provider simply returns 2767 an empty body with a 304 "Not Modified" response code. 2769 If the service providers supports versioning of resources the client 2770 MAY supply an If-Match Section 3.1 [RFC7233] header for PUT and PATCH 2771 operations to ensure that the requested operation succeeds only if 2772 the supplied ETag matches the latest service provider resource; e.g., 2773 If-Match: W/"e180ee84f0671b1" 2775 4. Service Provider Configuration Endpoints 2777 SCIM 2 defines 3 endpoints to facilitate discovery of SCIM service 2778 provider features and schema that MAY be retrieved using HTTP GET: 2780 /ServiceProviderConfig 2781 An HTTP GET to this endpoint will return a JSON structure that 2782 describes the SCIM specification features available on a service 2783 provider. This endpoint SHALL return responses with a JSON object 2784 using a "schemas" attribute of 2785 "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig". 2786 The attributes returned in the JSON object are defined in 2787 Section 5 [I-D.ietf-scim-core-schema]. An example representation 2788 of SCIM Service Provider configuration may be found in Section 8.5 2789 [I-D.ietf-scim-core-schema]. 2791 /Schemas 2792 An HTTP GET to this endpoint is used to retrieve information about 2793 resource schemas supported by a SCIM Service Provider. An HTTP 2794 GET to the endpoint "/Schemas" SHALL return all supported schemas 2795 in ListResponse format (see Figure 3). Individual schema 2796 definitions can be returned by appending the schema URI to the 2797 schemas endpoint. For example: 2799 /Schemas/urn:ietf:params:scim:schemas:core:2.0:User 2801 The contents of each schema returned is described in Section 7 2802 [I-D.ietf-scim-core-schema]. An example representation of SCIM 2803 schemas may be found in Section 8.7 [I-D.ietf-scim-core-schema]. 2805 /ResourceTypes 2806 An HTTP GET to this endpoint is used to discover the types of 2807 resources available on a SCIM Service Provider (e.g. Users and 2808 Groups). Each resource type defines the endpoints, the core 2809 schema URI that defines the resource, and any supported schema 2810 extensions. The attributes defining a resource type can be found 2811 in Section 6 [I-D.ietf-scim-core-schema], and an example 2812 representation can be found in Section 8.6 2813 [I-D.ietf-scim-core-schema]. 2815 In cases where a request is for a specific "ResourceType" or 2816 "Schema", the single JSON object is returned in the same way a single 2817 User or Group is retrieved as per Section 3.2.1. When returning 2818 multiple ResourceTypes or Schemas, the message form described by 2819 "urn:ietf:params:scim:api:messages:2.0:ListResponse" (ListResponse) 2820 form SHALL be used as shown in Figure 3 and Figure 9 below. Query 2821 parameters described in section 3.2 such as, sorting, attributes, and 2822 paging SHALL be ignored. If a "filter" is provided, the service 2823 provider SHOULD respond with HTTP Status 403 (FORBIDDEN) to ensure 2824 clients cannot incorrectly assume any matching conditions specified 2825 in a filter are true. 2827 The following is a non-normative example of an HTTP GET to the 2828 /ResourceTypes endpoint: 2830 { 2831 "totalResults":2, 2832 "itemsPerPage":10, 2833 "startIndex":1, 2834 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 2835 "Resources":[{ 2836 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"], 2837 "id":"User", 2838 "name":"User", 2839 "endpoint": "/Users", 2840 "description": "User Account", 2841 "schema": "urn:ietf:params:scim:schemas:core:2.0:User", 2842 "schemaExtensions": [{ 2843 "schema": 2844 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", 2845 "required": true 2846 }], 2847 "meta": { 2848 "location":"https://example.com/v2/ResourceTypes/User", 2849 "resourceType": "ResourceType" 2850 } 2851 }, 2852 { 2853 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"], 2854 "id":"Group", 2855 "name":"Group", 2856 "endpoint": "/Groups", 2857 "description": "Group", 2858 "schema": "urn:ietf:params:scim:schemas:core:2.0:Group", 2859 "meta": { 2860 "location":"https://example.com/v2/ResourceTypes/Group", 2861 "resourceType": "ResourceType" 2862 } 2863 }] 2864 } 2866 Figure 9: Example Resource Type JSON Representation 2868 5. Preparation and Comparison of Internationalized Strings 2870 To increase the likelihood that the input and comparison of unicode 2871 usernames and passwords will work in ways that make sense for typical 2872 users throughout the world there are special string preparation and 2873 comparison methods (PRECIS) that MUST be followed for usernames and 2874 passwords. Before comparing or evaluating uniqueness of a "userName" 2875 or "password" attribute, service providers MUST use the "PRECIS" 2876 profile described in Sections 4 and 5 respectively of 2877 [I-D.ietf-precis-saslprepbis] and is based on the "PRECIS" framework 2878 specification [I-D.ietf-precis-framework]. 2880 6. Multi-Tenancy 2882 A single service provider may expose the SCIM protocol to multiple 2883 clients. Depending on the nature of the service, the clients may 2884 have authority to access and alter resources initially created by 2885 other clients. Alternatively, clients may expect to access disjoint 2886 sets of resources, and may expect that their resources are 2887 inaccessible by other clients. These scenarios are called "multi- 2888 tenancy", where each client is understood to be or represent a 2889 "tenant" of the service provider. Clients may also be multi- 2890 tenanted. 2892 The following common cases may occur: 2894 1. All clients share all resources (no tenancy) 2896 2. Each single client creates and accesses a private subset of 2897 resources (1 client:1 Tenant) 2899 3. Sets of clients share sets of resources (M clients:1 Tenant) 2901 4. One client to Multiple Tenants (1 client:M Tenants) 2903 Service providers may implement any subset of the above cases. 2905 Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a 2906 scheme for multi-tenancy. 2908 The SCIM protocol does not prescribe the mechanisms whereby clients 2909 and service providers interact for: 2911 o Registering or provisioning Tenants 2913 o Associating a subset of clients with a subset of the Tenants 2915 o Indicating which tenant is associated with the data in a request 2916 or response, or indicating which Tenant is the subject of a query 2918 6.1. Associating Clients to Tenants 2920 The service provider MAY use the authentication mechanism (Section 2) 2921 to determine the identity of the client, and thus infer the 2922 associated Tenant. 2924 For implementations where a client is associated with more than one 2925 Tenant, the service provider MAY use one of the following methods for 2926 explicit specification of the Tenant. 2928 If any of these methods of allowing the client to explicitly specify 2929 the Tenant are employed, the service provider should ensure that 2930 access controls are in place to prevent or allow cross-tenant use 2931 cases. 2933 The service provider should consider precedence in cases where a 2934 client may explicitly specify a Tenant while being implicitly 2935 associated with a different Tenant. 2937 In all of these methods, the {tenant_id} is a unique identifier for 2938 the Tenant as defined by the service provider. 2940 o A URL prefix: "https://www.example.com/Tenants/{tenant_id}/v2/ 2941 Users" 2943 o A sub-domain: "https://{tenant_id}.example.com/v2/Groups" 2945 o The service provider may recognize a {tenant_id} provided by the 2946 client in an HTTP Header as the indicator of the desired target 2947 Tenant. 2949 6.2. SCIM Identifiers with Multiple Tenants 2951 Considerations for a Multi-Tenant Implementation: 2953 The service provider may choose to implement SCIM ids which are 2954 unique across all resources for all Tenants, but this is not 2955 required. 2957 The externalId, defined by the client, is required to be unique ONLY 2958 within the resources associated with the associated Tenant. 2960 7. Security Considerations 2962 7.1. TLS Support 2964 The SCIM Protocol layers on top of Hypertext Transfer Protocol and 2965 thus subject to the security considerations of HTTP Section 9 2966 [RFC7230] and its related specifications. 2968 SCIM resources (e.g., Users and Groups) can contain sensitive 2969 information. Therefore, SCIM clients and service providers MUST 2970 implement TLS. Which version(s) ought to be implemented will vary 2971 over time, and depend on the widespread deployment and known security 2972 vulnerabilities at the time of implementation. At the time of this 2973 writing, TLS version 1.2 [RFC5246] is the most recent version, but 2974 has very limited actual deployment, and might not be readily 2975 available in implementation toolkits. TLS version 1.0 [RFC5246] is 2976 the most widely deployed version, and will give the broadest 2977 interoperability. 2979 7.2. Disclosure of Sensitive Information in URIs 2981 As mentioned in ,Section 9.4 [RFC7231], SCIM clients requesting 2982 information using query filters using HTTP GET SHOULD give 2983 consideration to the information content of the filters and whether 2984 their exposure in a URI would represent a breach of security or 2985 confidentiality through leakage in a web browsers or server logs. 2986 This is particularly true for information that is legally considered 2987 "personally identifiable information" or is otherwise restricted by 2988 privacy laws. In these situations to ensure maximum security and 2989 confidentiality, clients SHOULD query using HTTP POST (see 2990 Section 3.2.3 ). 2992 Servers that receive HTTP GET requests using filters that contain 2993 restricted or confidential information SHOULD respond with HTTP 2994 status 403 indicating the operation is FORBIDDEN. A detailed error, 2995 "confidential_restricted" may be returned indicating the request must 2996 be submitted using POST. A non-normative example: 2998 HTTP/1.1 403 FORBIDDEN 3000 { 3001 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 3002 "Errors":[ 3003 { 3004 "description": 3005 "Query filter involving 'name' is restricted or confidential", 3006 "error":"confidential_restricted" 3007 } 3008 ] 3009 } 3011 7.3. Anonymous Requests 3013 If a SCIM service provider accepts anonymous requests such as SCIM 3014 resource creation requests (via HTTP POST), appropriate security 3015 measures should be put in place to prevent or limit exposure to 3016 attacks. The following counter-measures MAY be used: 3018 o Try to authenticate web UI components that forumulate the SCIM 3019 creation request. While the end-user MAY be anonymous, the web 3020 user interface component often has its own way to authenticate to 3021 the SCIM service provider (e.g. has an OAuth Client Credential 3022 [RFC6749]) and the web user interface component may implement its 3023 own measures (e.g. such as CAPTCHA) to ensure a ligitimate request 3024 is being made. 3026 o Limit the number of requests any particular client MAY make in a 3027 period of time. 3029 o For User resources, default newly created resource with an 3030 "active" setting of "false" and use a secondary confirmation 3031 process (e.g. email confirmation) to ensure the resource created 3032 is real. 3034 7.4. HTTP Considerations 3036 As an HTTP based protocol, implementers of SCIM SHOULD consider all 3037 security considerations of the HTTP/1.1 as enumerated in Section 1 3038 [RFC7230] 3040 As stated in Section 2.7.1 [RFC7230], a SCIM client MUST NOT generate 3041 the userinfo (i.e. username and password) component (and its "@" 3042 delimiter) when an "http" URI reference is generated with a message 3043 as they are now disallowed in HTTP. 3045 7.5. Secure Storage and Handling of Sensitive Data 3047 An attacker may obtain valid username/password combinations from the 3048 SCIM service provider's underlying database by gaining access to the 3049 database and/or launching injection attacks. This could lead to 3050 unintended disclosure of username/password combinations. The impact 3051 may extend beyond the domain of the SCIM service provider if the data 3052 was provisioned from other domains. 3054 Administrators should undertake industry best practices to protect 3055 the storage of credentials and in particular SHOULD follow 3056 recommendations outlines in Section 5.1.4.1 [RFC6819]. These 3057 recommendations include but are not limited to: 3059 o Provide injection attack counter measures (e.g. by validating all 3060 inputs and parameters), 3062 o No cleartext storage of credentials, 3064 o Store credentials using an encrypted protection mechanism, and 3065 o Avoid passwords and consider use of asymmetric cryptography based 3066 credentials. 3068 As outlined in Section 5.1.4.2 [RFC6819], adminitrators SHOULD take 3069 counter measures to prevent online attacks on secrets such as: 3071 o Utilize secure password policy in order to increase user password 3072 entrophy to hinder online attacks and password guessing, 3074 o Mitigate attacks on passwords by locking respective accounts have 3075 a number of failed attempts, 3077 o Use "tar pit" techniques by temporarily locking a respective 3078 account and delaying responses for a certain duration. The 3079 duration may increase with the number of failed attempts, and 3081 o Use authentication system that use CAPTCHA's and other factors for 3082 authenticating users further reducing the possibility of automated 3083 attacks. 3085 7.6. Case Insensitive Comparision & International Languages 3087 When comparing unicode strings such as in query filters or testing 3088 for uniqueness of usernames and passwords, strings MUST be 3089 appopriately prepared before comparison. See Section 5. 3091 8. IANA Considerations 3093 8.1. Media Type Registration 3095 To: ietf-types@iana.org 3097 Subject: Registration of media type application/scim+json 3099 Type name: application 3101 Subtype name: scim+json 3103 Required parameters: none 3105 Optional parameters: none 3107 Encoding considerations: 8bit 3109 Security considerations: See Section 7 3111 Interoperability considerations: The "application/scim+json" media 3112 type is intended to identify JSON structure data that conforms to 3113 the SCIM protocol and schema specifications. Older versions of 3114 SCIM are known to informally use "application/json". 3116 Published specification: [[this document]] 3118 Applications that use this media type: It is expected that 3119 applications that use this type may be special purpose 3120 applications intended for inter-domain provisioning. Clients may 3121 also be applications (e.g. mobile applications) that need to use 3122 SCIM for self-registration of user accounts. SCIM services may be 3123 offered by web applications that offer support for standards based 3124 provisioning or may be a dedicated SCIM service provider such as a 3125 "cloud directory". Content may be treated as equivalent to 3126 "application/json" type for the purpose of displaying in web 3127 browsers. 3129 Additional information: 3131 Magic number(s): 3133 File extension(s): .scim .scm 3135 Macintosh file type code(s): 3137 Person & email address to contact for futher information: SCIM 3138 mailing list "" 3140 Intended usage: COMMON* (see restrictions) 3142 Restrictions on usage: For most client types, it is sufficient to 3143 recognize the content as equivalent to "application/json". 3144 Applications intending to use SCIM protocol SHOULD use the 3145 application/scim+json media type. 3147 Author: Phil Hunt 3149 Change controller: IETF 3151 8.2. SCIM Message URI Registry 3153 As per the IANA SCIM Schema Registry in [I-D.ietf-scim-core-schema], 3154 the following registers and extends the SCIM Schema Registry to 3155 define SCIM protocol request/response JSON schema URN identifier 3156 prefix of "urn:ietf:params:scim:api:messages:2.0" which is part of 3157 the URN sub-Namespace for SCIM. There is no specific associated 3158 resource type. 3160 +---------------------------------+-----------------+---------------+ 3161 | Schema URI | Name | Reference | 3162 +---------------------------------+-----------------+---------------+ 3163 | urn:ietf:params:scim:api: | List/Query | See Section | 3164 | messages:2.0:ListResponse | Response | 3.2.2 | 3165 | urn:ietf:params:scim:api: | POST Query | See Section | 3166 | messages:2.0:SearchRequest | Request | 3.2.3 | 3167 | urn:ietf:params:scim:api: | Patch Operation | See Section | 3168 | messages:2.0:PatchOp | | 3.3.2 | 3169 | urn:ietf:params:scim:api: | Bulk Operations | See Section | 3170 | messages:2.0:BulkRequest | Request | 3.5 | 3171 | urn:ietf:params:scim:api: | Bulk Operations | See Section | 3172 | messages:2.0:BulkResponse | Response | 3.5 | 3173 | urn:ietf:params:scim:api: | Error Response | See Section | 3174 | messages:2.0:Error | | 3.10 | 3175 +---------------------------------+-----------------+---------------+ 3177 Table 9: SCIM Schema URIs for Data Resources 3179 9. References 3181 9.1. Normative References 3183 [I-D.ietf-precis-saslprepbis] 3184 Saint-Andre, P. and A. Melnikov, "Preparation, 3185 Enforcement, and Comparison of Internationalized Strings 3186 Representing Usernames and Passwords", draft-ietf-precis- 3187 saslprepbis-13 (work in progress), December 2014. 3189 [I-D.ietf-scim-core-schema] 3190 Hunt, P., Grizzle, K., Wahlstroem, E., and C. Mortimore, 3191 "System for Cross-Domain Identity Management: Core 3192 Schema", draft-ietf-scim-core-schema-16 (work in 3193 progress), February 2015. 3195 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3196 Requirement Levels", BCP 14, RFC 2119, March 1997. 3198 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3199 10646", STD 63, RFC 3629, November 2003. 3201 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3202 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3203 3986, January 2005. 3205 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 3206 Specifications: ABNF", STD 68, RFC 5234, January 2008. 3208 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3209 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3211 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 3212 5789, March 2010. 3214 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 3215 Interchange Format", RFC 7159, March 2014. 3217 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3218 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 3219 2014. 3221 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3222 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 3224 [RFC7233] Fielding, R., Lafon, Y., and J. Reschke, "Hypertext 3225 Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, 3226 June 2014. 3228 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3229 (HTTP/1.1): Authentication", RFC 7235, June 2014. 3231 9.2. Informative References 3233 [I-D.ietf-precis-framework] 3234 Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 3235 Preparation, Enforcement, and Comparison of 3236 Internationalized Strings in Application Protocols", 3237 draft-ietf-precis-framework-22 (work in progress), 3238 February 2015. 3240 [OpenSearch] 3241 Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . 3243 [Order-Operations] 3244 Wikipedia, "Order of Operations: Programming Languages", . 3246 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 3247 6749, October 2012. 3249 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 3250 Framework: Bearer Token Usage", RFC 6750, October 2012. 3252 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 3253 Threat Model and Security Considerations", RFC 6819, 3254 January 2013. 3256 [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation 3257 (JSON) Patch", RFC 6902, April 2013. 3259 [RFC7238] Reschke, J., "The Hypertext Transfer Protocol Status Code 3260 308 (Permanent Redirect)", RFC 7238, June 2014. 3262 Appendix A. Contributors 3264 Samuel Erdtman (samuel@erdtman.se) 3266 Patrick Harding (pharding@pingidentity.com) 3268 Appendix B. Acknowledgments 3270 The editors would like to acknowledge the contribution and work of 3271 the past draft editors: 3273 Trey Drake, UnboundID 3275 Chuck Mortimore, Salesforce 3277 The editor would like to thank the participants in the the SCIM 3278 working group for their support of this specification. 3280 Appendix C. Change Log 3282 [[This section to be removed prior to publication as an RFC]] 3284 Draft 02 - KG - Addition of schema extensibility 3286 Draft 03 - PH - Revisions based on following tickets: 3288 24 - Add filter negation 3290 39 - Clarification on response for DELETE 3292 42 - Make root searches optional 3294 49 - Add "ew" filter 3296 50 - Filters for multi-valued complex attributes 3298 51 - Search by Schema 3300 53 - Standard use of term client (some was consumer) 3302 55 - Redirect support (3xx) 3303 56 - Make manager attribute consistent with other $ref attrs 3305 57 - Update all "/v1" examples to '/v2" 3307 59 - Fix capitalization per IETF editor practices 3309 60 - Changed tags to normal and tags 3311 Draft 04 - PH - Revisions based on the following tickets: 3313 18 - New PATCH command based on JSON Patch (RFC6902) 3315 - Provided ABNF specification for filters (used in PATCH) 3317 - Updated references to RFC4627 to RFC7159 3319 Draft 05 - PH - Revisions based on the following tickets: 3321 03 - Support for excludedAttributes parameter 3323 13 - Change client use of Etags from MUST to MAY (correction) 3325 23 - Clarifications regarding case exact processing. 3327 41 - Add IANA considerations 3329 65 - Removed X-HTTP-Method-Override support 3331 69 - Added clarifications to intro to align with draft-nottingham- 3332 uri-get-off-my-lawn 3334 70 - Remove SCIM_TENANT_ID header 3336 72 - Added text to indicate UTF-8 is default and mandatory 3337 encoding format per BCP18 3339 74 - Added security considerations for using GET with confidential 3340 attribute filters 3342 - corrected error response in JSON PATCH operation 3344 Draft 06 - PH - Revisions based on the following tickets and 3345 editorial changes 3347 41 - Revised content types from application/json to application/ 3348 scim+json, registered API schemas 3350 63 - Revised uri schema prefixes for API json message schemas 3351 66 - Updated references for RFC2616 to HTTPbis 3353 75 - Added security considerations for International Strings and 3354 "PRECIS" support 3356 76 - Clarified handling of PUT (& POST) with regards to mutability 3357 and default values 3359 - Corrected version numbers in sec 3.11 API Versioning to v2 (from 3360 v1) 3362 - Clarified that no filter matches should return success 3363 totalResults=0 3365 Draft 07 - PH - Revisions regarding support of detailed errors 3366 (Tickets 37, 46, 67) 3368 Draft 08 - PH - Revisions as follows 3370 - Added clarification on schemas handling during PATCH operation 3372 - Revised example URN in Attribute Notation section to comply with 3373 IANA namespace rules 3375 - Fixed typo in ABNF, attrExpr should be attrExp 3377 - Added more security considerations for HTTP and sensitive data 3379 - Revised authentication and authorization sections for greater 3380 clarity. 3382 - Replaced the word "search" with "query" for consistency 3384 - Clarified sucessful resource creation response 3386 - Added clarification on primary value handling in PATCH 3387 (consistent with draft 03) 3389 - Revised SCIM Bullk error handling to conform with draft 07 error 3390 handling 3392 Draft 09 - PH - Revisions as follows 3394 - Aligned API with new URN namespace per RFC3553 and IETF90 3395 meeting 3397 - Clarified URN usage within patch (what schema urn applies) 3398 - Made 'path' optional in PATCH for Add and Replace 3400 Draft 10 - PH - Revisions as follows 3402 Restructuring of Bulk into sub-sections 3404 General clarifications 3406 Improved Base URI section 3408 Authorization section clarifications 3410 Draft 11 - PH - Revisions as follows 3412 Made mutability processing rules for CREATE more editorially 3413 obvious 3415 Added clarfications and security considerations for Anonymous 3416 operations 3418 Added clarifications to "/Me" for POST requests 3420 Clarified use of bulkids with multiple requests 3422 Corrected JSON parsing issue by adding "Operations" attribute to 3423 PATCH operation 3425 Draft 12 - PH - Editorial NITs 3427 Fix line lengths in artwork to be 72 chars or less 3429 Remove unused references 3431 Fix normative terms per RFC2119 3433 Updated reference to draft-reschke-http-status-308 to RFC7238 3435 Draft 13 - PH - Added clarification to error response for improperly 3436 formated email/phonenumbers 3438 Draft 14 - PH - Nits and clarifications 3440 Added new Service Provider Discovery section that clarifies use of 3441 ResourceTypes, Schemas, and ServiceProviderConfigs 3443 As Complex attributes cannot support sub-attributes that are 3444 complex, the filter ABNF was corrected to prevent nested 3445 valueFilters (which presumes support for nested Complex 3446 Attributes) 3448 Corrections to ABNF: Added missing space (SP) values to logicExp 3449 ABNF rule. Corrected "not(" to make "not" optional. 3451 Added additional filter example showing full path with schema URI 3452 (to disambiguate duplicate names between schemas) 3454 Missing POST verb added to HTTP errors (table 7) since a POST 3455 endpoint might be undefined or NOT FOUND. 3457 Corrected JSON example in sec 3.3.2.1 (removed extraneous " ) 3459 Corrected filter in Figure 3 so that multiple resoruce types can 3460 be returned per the response example in figure 4. 3462 Clarifications and improvements to examples in PATCH replace 3463 operations 3465 Updated references to saslprep and precis frameworks 3467 Draft 15 - PH - Clarifications on returning "path" handling during 3468 PATCH "replace" operations. Updated references. 3470 Authors' Addresses 3472 Phil Hunt (editor) 3473 Oracle Corporation 3475 Email: phil.hunt@yahoo.com 3477 Kelly Grizzle 3478 SailPoint 3480 Email: kelly.grizzle@sailpoint.com 3482 Morteza Ansari 3483 Cisco 3485 Email: morteza.ansari@cisco.com 3486 Erik Wahlstroem 3487 Technology Nexus 3489 Email: erik.wahlstrom@nexusgroup.com 3491 Chuck Mortimore 3492 Salesforce.com 3494 Email: cmortimore@salesforce.com