idnits 2.17.1 draft-ietf-scim-api-16.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 (March 8, 2015) is 3336 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-14 == Outdated reference: A later version (-22) exists of draft-ietf-scim-core-schema-17 ** 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) -- Obsolete informational reference (is this intentional?): RFC 7238 (Obsoleted by RFC 7538) Summary: 6 errors (**), 0 flaws (~~), 4 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: September 9, 2015 SailPoint 6 M. Ansari 7 Cisco 8 E. Wahlstroem 9 Nexus Technology 10 C. Mortimore 11 Salesforce 12 March 8, 2015 14 System for Cross-Domain Identity Management: Protocol 15 draft-ietf-scim-api-16 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 September 9, 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. Introduction . . . . . . . . . . . . . . . . . . . . . . 5 73 3.2. SCIM Endpoints . . . . . . . . . . . . . . . . . . . . . 6 74 3.3. Creating Resources . . . . . . . . . . . . . . . . . . . 8 75 3.3.1. Resource Types . . . . . . . . . . . . . . . . . . . 10 76 3.4. Retrieving Resources . . . . . . . . . . . . . . . . . . 10 77 3.4.1. Retrieving a known Resource . . . . . . . . . . . . . 10 78 3.4.2. Query Resources . . . . . . . . . . . . . . . . . . . 11 79 3.4.3. Querying Resources Using HTTP POST . . . . . . . . . 22 80 3.5. Modifying Resources . . . . . . . . . . . . . . . . . . . 25 81 3.5.1. Replacing with PUT . . . . . . . . . . . . . . . . . 26 82 3.5.2. Modifying with PATCH . . . . . . . . . . . . . . . . 28 83 3.6. Deleting Resources . . . . . . . . . . . . . . . . . . . 42 84 3.7. Bulk Operations . . . . . . . . . . . . . . . . . . . . . 43 85 3.7.1. Circular Reference Processing . . . . . . . . . . . . 45 86 3.7.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 48 87 3.7.3. Response and Error Handling . . . . . . . . . . . . . 52 88 3.7.4. Maximum Operations . . . . . . . . . . . . . . . . . 58 89 3.8. Data Input/Output Formats . . . . . . . . . . . . . . . . 59 90 3.9. Additional Operation Response Parameters . . . . . . . . 60 91 3.10. Attribute Notation . . . . . . . . . . . . . . . . . . . 61 92 3.11. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 61 93 3.12. HTTP Status and Error Response Handling . . . . . . . . . 62 94 3.13. API Versioning . . . . . . . . . . . . . . . . . . . . . 66 95 3.14. Versioning Resources . . . . . . . . . . . . . . . . . . 66 96 4. Service Provider Configuration Endpoints . . . . . . . . . . 68 97 5. Preparation and Comparison of Internationalized Strings . . . 70 98 6. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 71 99 6.1. Associating Clients to Tenants . . . . . . . . . . . . . 71 100 6.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 72 101 7. Security Considerations . . . . . . . . . . . . . . . . . . . 72 102 7.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 72 103 7.2. Disclosure of Sensitive Information in URIs . . . . . . . 73 104 7.3. Anonymous Requests . . . . . . . . . . . . . . . . . . . 73 105 7.4. HTTP Considerations . . . . . . . . . . . . . . . . . . . 74 106 7.5. Secure Storage and Handling of Sensitive Data . . . . . . 74 107 7.6. Case Insensitive Comparision & International Languages . 75 108 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 75 109 8.1. Media Type Registration . . . . . . . . . . . . . . . . . 75 110 8.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 76 111 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 77 112 9.1. Normative References . . . . . . . . . . . . . . . . . . 77 113 9.2. Informative References . . . . . . . . . . . . . . . . . 78 114 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 79 115 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 79 116 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 79 117 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 83 119 1. Introduction and Overview 121 The SCIM Protocol is an application-level, HTTP protocol for 122 provisioning and managing identity data on the web and in cross- 123 domain environments such as enterprise to cloud, or inter-cloud 124 scenarios. The protocol supports creation, modification, retrieval, 125 and discovery of core identity resources such as Users and Groups, as 126 well as custom resources and resource extensions. 128 1.1. Intended Audience 130 This document is intended as a guide to SCIM protocol usage for both 131 SCIM HTTP service providers and HTTP clients who may provision 132 information to service providers or retrieve information from them. 134 1.2. Notational Conventions 136 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 137 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 138 document are to be interpreted as described in [RFC2119]. These 139 keywords are capitalized when used to unambiguously specify 140 requirements of the protocol or application features and behavior 141 that affect the interoperability and security of implementations. 142 When these words are not capitalized, they are meant in their 143 natural-language sense. 145 For purposes of readability examples are not URL encoded. 146 Implementers MUST percent encode URLs as described in Section 2.1 of 147 [RFC3986]. 149 Throughout this documents all figures MAY contain spaces and extra 150 line-wrapping for readability and space limitations. Similarly, some 151 URI's contained within examples, have been shortened for space and 152 readability reasons. 154 1.3. Definitions 156 Base URI 157 The SCIM HTTP protocol is described in terms of a path relative to 158 a Base URI. The Base URI MUST NOT contain a query string as 159 clients may append additional path information and query 160 parameters as part of forming the request. The base URI most 161 often is a URL which most often consists of the "https" protocol 162 scheme, a domain name and some initial path [RFC3986]. Example: 163 "https://example.com/scim/" 165 For readability, all examples in this document are expressed 166 assuming the SCIM service root and the server root are the same 167 (no path pre-fix). It is expected that SCIM servers may be 168 deployed using any URI path prefix. For example, a SCIM server 169 might be have a prefix of "https://example.com/", or 170 "https://example.com/scim/tenancypath/". Additionally client may 171 also apply a version number to the server root prefix (see 172 Section 3.13 ). 174 2. Authentication and Authorization 176 Because SCIM builds on the HTTP protocol, it does not itself define a 177 scheme for authentication and authorization. SCIM depends on 178 standard HTTP authentication schemes. Implementers SHOULD support 179 existing authentication/authorization schemes. In particular, OAuth2 180 (see [RFC6749], [RFC6750]) is RECOMMENDED. Appropriate security 181 considerations of the selected authentication and authorization 182 schemes SHOULD be taken. Because this protocol uses HTTP response 183 status codes as the primary means of reporting the result of a 184 request, servers are advised to respond to unauthorized or 185 unauthenticated requests using the 401 response code in accordance 186 with Section 3.1 of [RFC7235]. 188 All examples show an OAuth2 bearer token [RFC6750] (though it is not 189 required); e.g., 190 GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 191 Host: example.com 192 Authorization: Bearer h480djs93hd8 194 When processing requests, the service provider SHOULD consider the 195 subject performing the request and whether the action is appropriate 196 given the subject and the resource affected by the request. The 197 subject performing the request is usually determined from the 198 "Authorization" header present in the request. 200 3. SCIM Protocol 202 3.1. Introduction 204 SCIM is a protocol that is based on HTTP protocol [RFC7230]. Along 205 with HTTP headers and URIs, SCIM uses JSON [RFC7159] payloads to 206 convey both SCIM resources, as well as protocol specific payload 207 messages that convey request parameters and response information such 208 as errors. Both resources and messages are passed in the form of 209 JSON based structures in the message body of an HTTP request or 210 response. To identify this content, SCIM uses a media type of 211 "application/scim+json" (see Section 8.1). 213 A SCIM "resource" is a JSON object that may be created, maintained, 214 and retrieved through HTTP request methods as described in this 215 document. Each JSON resource representation contains a "schemas" 216 attribute that contains a list of one or more URIs that indicate 217 included SCIM schemas that are used to indicate the attributes 218 contained within a resource. Specific information about what 219 attributes are defined within a schema MAY be obtained by querying a 220 SCIM service provider's "/Schemas" endpoint for a schema definition 221 (see Section 8.7 [I-D.ietf-scim-core-schema]). Responses from this 222 endpoint describe how a service provider supports a schema and in 223 particular how attribute qualities such as cardinality, case- 224 exactness, mutability, uniqueness, returnability, and whether an 225 attribute is required. While SCIM schemas and associated extension 226 model are defined in [I-D.ietf-scim-core-schema], SCIM clients should 227 expect that some attribute schema MAY change from service provider to 228 service provider, particularly across administrative domains. In 229 cases where SCIM may be used as an open protocol in front of an 230 application service, it is quite reasonable to expect that some 231 service providers MAY only support a sub-set of the schema defined in 232 [I-D.ietf-scim-core-schema]. 234 A SCIM message conveys protocol parameters about a SCIM request or 235 response that are defined by this specification. As with a SCIM 236 resource, a SCIM message is a JSON object that contains a "schemas" 237 attribute with a URI whose namespace prefix that MUST begin with 238 "urn:ietf:params:scim:api:". As SCIM protocol messages are fixed and 239 defined by SCIM specifications and registered extensions, SCIM 240 message schemas using the above prefix URN SHALL NOT be discoverable 241 using the "/Schemas" endpoint. 243 As SCIM is intended for use within cross-domain environments where 244 schema and implementations MAY vary, techniques such as document 245 validation, such as in [XML-Schema], are not recommended. A SCIM 246 service provider interprets a request in the context of its own 247 schema (which may be different from the client's schema) and 248 following the defined processing rules for each request. The 249 following sections in this document define the processing rules for 250 SCIM and provide allowances for schema differences where appropriate. 251 For example, in a SCIM PUT request, "readOnly" attributes are 252 ignored, while "readWrite" attributes are updated. There is no need 253 for a SCIM client to discover which attributes are "readOnly" and 254 does not need to remove them from a PUT request in advance in order 255 to be accepted. Similarly a SCIM client SHOULD NOT expect a service 256 provider to return SCIM resources with exactly the same schema and 257 values as submitted. SCIM responses SHALL reflect resource state as 258 interpreted by the SCIM service provider. 260 3.2. SCIM Endpoints 262 The SCIM protocol specifies well-known endpoints and HTTP methods for 263 managing resources defined in the core schema; i.e., "User" and 264 "Group" resources correspond to "/Users" and "/Groups" respectively. 265 Service providers that support extended resources SHOULD define 266 resource endpoints using the convention of pluralizing the resource 267 name defined in the extended schema by appending an 's'. Given there 268 are cases where resource pluralization is ambiguous; e.g., a resource 269 named "Person" is legitimately "Persons" and "People". Clients 270 SHOULD discover resource endpoints via the "/ResourceTypes" endpoint. 272 GET 273 Retrieves one or more complete or partial resources. 275 POST 276 Depending on the endpoint, creates new resources, create a search 277 request, or may be used to bulk modify resources. 279 PUT 280 Modifies a resource by replacing existing attributes with a 281 specified set of replacement attributes (replace). PUT MUST NOT 282 be used to create new resources. 284 PATCH 285 Modifies a resource with a set of client specified changes 286 (partial update). 288 DELETE 289 Deletes a resource. 291 Resource Endpoint Operations Description 292 -------- ---------------- ---------------------- -------------------- 293 User /Users GET (Section 3.4.1), Retrieve, Add, 294 POST (Section 3.3), Modify Users 295 PUT (Section 3.5.1), 296 PATCH (Section 3.5.2), 297 DELETE (Section 3.6) 298 Group /Groups GET (Section 3.4.1), Retrieve, Add, 299 POST (Section 3.3), Modify Groups 300 PUT (Section 3.5.1), 301 PATCH (Section 3.5.2), 302 DELETE (Section 3.6) 303 Self /Me GET, POST, PUT, PATCH, Alias for operations 304 DELETE (Section 3.11) against a resource 305 mapped to an 306 authenticated 307 Subject (e.g. User). 308 Service /ServiceProvider GET (Section 4) Retrieve service 309 Provider Config provider's 310 Config configuration 311 Resource /ResourceTypes GET (Section 4) Retrieve supported 312 Type resource types 313 Schema /Schemas GET (Section 4) Retrieve one or more 314 supported schemas. 315 Bulk /Bulk POST (Section 3.7) Bulk updates to one 316 or more resources 317 Search [prefix]/.search POST (Section 3.4.3) Search from system 318 root or within a 319 resource endpoint 320 for one or more 321 resource types using 322 POST. 324 Table 1: Defined endpoints 326 All requests to the service provider are made via HTTP Methods as per 327 Section 4.3 [RFC7231] on a URL derived from the Base URL. Responses 328 are returned in the body of the HTTP response, formatted as JSON. 329 Error status codes SHOULD be transmitted via the HTTP status code of 330 the response (if possible), and SHOULD also be specified in the body 331 of the response (see Section 3.12). 333 3.3. Creating Resources 335 To create new resources, clients send HTTP POST requests to the 336 resource endpoint such as: "/Users" or "/Groups". 338 The server SHALL process attributes according to the following 339 mutability rules: 341 o For attributes in the request body, whose mutability is 342 "readOnly", SHALL be ignored. 344 o For attributes whose mutability is "readWrite", that are omitted 345 from the request body, MAY be assumed to be not asserted by the 346 client. The service provider MAY assign a default value to non- 347 asserted attributes in the final resource representation. 349 o Service providers MAY take into account whether a client has 350 access to, or understands, all of the resource's attributes when 351 deciding whether non-asserted attributes should be defaulted. 352 Clients that intend to override server defaulted values for 353 attributes MAY specify "null" for a single-valued attribute or an 354 empty array "[]" for a multi-valued attribute to clear all values. 356 When the service provider successfully creates the new resource, an 357 HTTP response SHALL be returned with HTTP status "201" ("Created"). 358 The response body SHOULD contain the service provider's 359 representation of the newly created resource. The URI of the created 360 resource SHALL included in the HTTP "Location" header and in JSON 361 resource representation under the attribute "meta.location". Since 362 the server is free to alter and/or ignore POSTed content, returning 363 the full representation can be useful to the client, enabling it to 364 correlate the client and server views of the new resource. 366 If the service provider determines creation of the requested resource 367 conflicts with existing resources; e.g., a "User" resource with a 368 duplicate "userName", the service provider MUST return an HTTP Status 369 409, with "scimType" error code of "uniqueness" as per Section 3.12. 371 Below, in the following example, a client sends a POST request 372 containing a "User" to the "/Users" endpoint. 374 POST /Users HTTP/1.1 375 Host: example.com 376 Accept: application/scim+json 377 Content-Type: application/scim+json 378 Authorization: Bearer h480djs93hd8 379 Content-Length: ... 381 { 382 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 383 "userName":"bjensen", 384 "externalId":"bjensen", 385 "name":{ 386 "formatted":"Ms. Barbara J Jensen III", 387 "familyName":"Jensen", 388 "givenName":"Barbara" 389 } 390 } 392 In response to the example request above, the server signals a 393 successful creation with an HTTP status code 201 (Created) and 394 returns a representation of the resource created. 396 HTTP/1.1 201 Created 397 Content-Type: application/scim+json 398 Location: 399 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 400 ETag: W/"e180ee84f0671b1" 402 { 403 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 404 "id":"2819c223-7f76-453a-919d-413861904646", 405 "externalId":"bjensen", 406 "meta":{ 407 "resourceType":"User", 408 "created":"2011-08-01T21:32:44.882Z", 409 "lastModified":"2011-08-01T21:32:44.882Z", 410 "location": 411 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 412 "version":"W\/\"e180ee84f0671b1\"" 413 }, 414 "name":{ 415 "formatted":"Ms. Barbara J Jensen III", 416 "familyName":"Jensen", 417 "givenName":"Barbara" 418 }, 419 "userName":"bjensen" 420 } 422 3.3.1. Resource Types 424 When adding a resource to a specific endpoint, the meta attribute 425 "resourceType" SHALL be set by the HTTP service provider to the 426 corresponding resource type for the endpoint. For example, "/Users" 427 will set "resourceType" to "User", and "/Groups" will set 428 "resourceType" to "Group". 430 3.4. Retrieving Resources 432 Resources are retrieved via opaque, unique URLs or via Query (see 433 Section 3.4.2). The attributes returned are defined in the server's 434 attribute schema (see Section 10 [I-D.ietf-scim-core-schema]) and 435 request parameters (see Section 3.9). By default, resource 436 attributes returned in a response are those whose schema "returned" 437 setting is "always" or "default". 439 3.4.1. Retrieving a known Resource 441 To retrieve a known resource, clients send GET requests to the 442 resource endpoint; e.g., "/Users/{id}" or "/Groups/{id}", or 443 "/Schemas/{id}". 445 If the resource exists the server responds with HTTP Status code 200 446 (OK) and includes the result in the body of the response. 448 The below example retrieves a single User via the "/Users" endpoint. 450 GET /Users/2819c223-7f76-453a-919d-413861904646 451 Host: example.com 452 Accept: application/scim+json 453 Authorization: Bearer h480djs93hd8 455 The server responds with: 457 HTTP/1.1 200 OK 458 Content-Type: application/scim+json 459 Location: 460 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 461 ETag: W/"f250dd84f0671c3" 463 { 464 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 465 "id":"2819c223-7f76-453a-919d-413861904646", 466 "externalId":"bjensen", 467 "meta":{ 468 "resourceType":"User", 469 "created":"2011-08-01T18:29:49.793Z", 470 "lastModified":"2011-08-01T18:29:49.793Z", 471 "location": 472 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 473 "version":"W\/\"f250dd84f0671c3\"" 474 }, 475 "name":{ 476 "formatted":"Ms. Barbara J Jensen III", 477 "familyName":"Jensen", 478 "givenName":"Barbara" 479 }, 480 "userName":"bjensen", 481 "phoneNumbers":[ 482 { 483 "value":"555-555-8377", 484 "type":"work" 485 } 486 ], 487 "emails":[ 488 { 489 "value":"bjensen@example.com", 490 "type":"work" 491 } 492 ] 493 } 495 3.4.2. Query Resources 497 The SCIM protocol defines a standard set of query parameters that can 498 be used to filter, sort, and paginate to return zero or more 499 resources in a query response. Queries MAY be made against a single 500 resource or a resource type endpoint (e.g. "/Users"). SCIM service 501 providers MAY support additional query parameters not specified here 502 and SHOULD ignore any query parameters they do not recognize. 504 Responses MUST be identified using the following URI: 505 "urn:ietf:params:scim:api:messages:2.0:ListResponse". The following 506 attributes are defined for responses: 508 totalResults The total number of results returned by the list or 509 query operation. This may not be equal to the number of elements 510 in the resources attribute of the list response if pagination 511 (Section 3.4.2.4) is requested. REQUIRED. 513 Resources A multi-valued list of complex objects containing the 514 requested resources. This may be a subset of the full set of 515 resources if pagination (Section 3.4.2.4) is requested. REQUIRED 516 if "totalResults" is non-zero. 518 startIndex The 1-based index of the first result in the current set 519 of list results. REQUIRED when partial results returned due to 520 pagination. 522 itemsPerPage The number of resources returned in a list response 523 page. REQUIRED when partial results returned due to pagination. 525 A query that does not return any matches SHALL return success (HTTP 526 Status 200) with "totalResults" set to a value of 0. 528 The query example below requests the userName for all Users: 530 GET /Users?attributes=userName 531 Host: example.com 532 Accept: application/scim+json 533 Authorization: Bearer h480djs93hd8 535 The following is an example response to the query above: 537 HTTP/1.1 200 OK 538 Content-Type: application/scim+json 540 { 541 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 542 "totalResults":2, 543 "Resources":[ 544 { 545 "userName":"bjensen" 546 }, 547 { 548 "userName":"jsmith" 549 } 550 ] 551 } 553 3.4.2.1. Query Endpoints 555 Queries MAY be performed against a SCIM resource object, a resource 556 type endpoint, or a SCIM server root. For example: 558 "/Users/{id}" 560 "/Users" 562 "/Groups" 564 A query against a server root indicates that ALL resources within the 565 server SHALL be included subject to filtering. A filter expression 566 using "meta.resourceType" MAY be used to restrict results to one or 567 more specific resource types (to exclude others). For example: 569 filter=(meta.resourceType eq User) or (meta.resourceType eq Group) 571 If a SCIM service provider determines that too many results would be 572 returned (e.g. because a client queried a resource type endpoint or 573 the server base URI), the server SHALL reject the request by 574 returning an HTTP response with "status" 400 and json attribute 575 "scimType" set to "tooMany" (see Table 8). 577 When processing query operations across endpoints that include more 578 than one SCIM resource type (e.g. a query from the server root 579 endpoint), filters MUST be processed as outlined in Section 3.4.2.2. 580 For filtered attributes that are not part of a particular resource 581 type, the service provider SHALL treat the attribute as if there is 582 no attribute value. For example, a presence or equality filter for 583 an undefined attribute evaluates as FALSE. 585 3.4.2.2. Filtering 587 Filtering is an OPTIONAL parameter for SCIM service providers. 588 Clients MAY discover service provider filter capabilities by looking 589 at the "filter" attribute of the "ServiceProviderConfig" (see 590 Section 8 [I-D.ietf-scim-core-schema]). Clients MAY request a subset 591 of resources by specifying the "filter" query parameter containing a 592 filter expression. When specified only those resources matching the 593 filter expression SHALL be returned. The expression language that is 594 used in the filter parameter supports references to attributes and 595 literals. 597 Attribute names and attribute operators used in filters are case 598 insensitive. For example, the following two expressions will 599 evaluate to the same logical value: 601 filter=userName Eq "john" 603 filter=Username eq "john" 605 The filter parameter MUST contain at least one valid Boolean 606 expression. Each expression MUST contain an attribute name followed 607 by an attribute operator and optional value. Multiple expressions 608 MAY be combined using the two logical operators. Furthermore 609 expressions can be grouped together using "()". 611 The operators supported in the expression are listed in the following 612 table. 614 +----------+-------------+------------------------------------------+ 615 | Operator | Description | Behavior | 616 +----------+-------------+------------------------------------------+ 617 | eq | equal | The attribute and operator values must | 618 | | | be identical for a match. | 619 | ne | not equal | The attribute and operator values are | 620 | | | not identical. | 621 | co | contains | The entire operator value must be a | 622 | | | substring of the attribute value for a | 623 | | | match. | 624 | sw | starts with | The entire operator value must be a | 625 | | | substring of the attribute value, | 626 | | | starting at the beginning of the | 627 | | | attribute value. This criterion is | 628 | | | satisfied if the two strings are | 629 | | | identical. | 630 | ew | ends with | The entire operator value must be a | 631 | | | substring of the attribute value, | 632 | | | matching at the end of the attribute | 633 | | | value. This criterion is satisfied if | 634 | | | the two strings are identical. | 635 | pr | present | If the attribute has a non-empty or non- | 636 | | (has value) | null value, or if it contains a non- | 637 | | | empty node for complex attributes there | 638 | | | is a match. | 639 | gt | greater | If the attribute value is greater than | 640 | | than | operator value, there is a match. The | 641 | | | actual comparison is dependent on the | 642 | | | attribute type. For string attribute | 643 | | | types, this is a lexicographical | 644 | | | comparison and for DateTime types, it is | 645 | | | a chronological comparison. For Integer | 646 | | | attributes it is a comparison by numeric | 647 | | | value. Boolean and Binary attributes | 648 | | | SHALL cause a failed response (HTTP | 649 | | | Status 400) with scimType of | 650 | | | invlaidFiler. | 651 | ge | greater | If the attribute value is greater than | 652 | | than or | or equal to the operator value, there is | 653 | | equal | a match. The actual comparison is | 654 | | | dependent on the attribute type. For | 655 | | | string attribute types, this is a | 656 | | | lexicographical comparison and for | 657 | | | DateTime types, it is a chronological | 658 | | | comparison. For Integer attributes it is | 659 | | | a comparison by numeric value. Boolean | 660 | | | and Binary attributes SHALL cause a | 661 | | | failed response (HTTP Status 400) with | 662 | | | scimType of invlaidFiler. | 663 | lt | less than | If the attribute value is less than | 664 | | | operator value, there is a match. The | 665 | | | actual comparison is dependent on the | 666 | | | attribute type. For string attribute | 667 | | | types, this is a lexicographical | 668 | | | comparison and for DateTime types, it is | 669 | | | a chronological comparison. For Integer | 670 | | | attributes it is a comparison by numeric | 671 | | | value. Boolean and Binary attributes | 672 | | | SHALL cause a failed response (HTTP | 673 | | | Status 400) with scimType of | 674 | | | invlaidFiler. | 675 | le | less than | If the attribute value is less than or | 676 | | or equal | equal to the operator value, there is a | 677 | | | match. The actual comparison is | 678 | | | dependent on the attribute type. For | 679 | | | string attribute types, this is a | 680 | | | lexicographical comparison and for | 681 | | | DateTime types, it is a chronological | 682 | | | comparison. For Integer attributes it is | 683 | | | a comparison by numeric value. Boolean | 684 | | | and Binary attributes SHALL cause a | 685 | | | failed response (HTTP Status 400) with | 686 | | | scimType of invlaidFiler. | 687 +----------+-------------+------------------------------------------+ 689 Table 2: Attribute Operators 691 +----------+-------------+------------------------------------------+ 692 | Operator | Description | Behavior | 693 +----------+-------------+------------------------------------------+ 694 | and | Logical And | The filter is only a match if both | 695 | | | expressions evaluate to true. | 696 | or | Logical or | The filter is a match if either | 697 | | | expression evaluates to true. | 698 | not | Not | The filter is a match if the expression | 699 | | function | evaluates to false. | 700 +----------+-------------+------------------------------------------+ 702 Table 3: Logical Operators 704 +----------+-------------+------------------------------------------+ 705 | Operator | Description | Behavior | 706 +----------+-------------+------------------------------------------+ 707 | ( ) | Precedence | Boolean expressions may be grouped using | 708 | | grouping | parentheses to change the standard order | 709 | | | of operations; i.e., evaluate OR logical | 710 | | | operators before logical AND operators. | 711 | [ ] | Complex | Service providers MAY support complex | 712 | | attribute | filters where expressions MUST be | 713 | | filter | applied to the same value of a parent | 714 | | grouping | attribute specified immediately before | 715 | | | the left square bracket ("["). The | 716 | | | expression within square brackets ("[" | 717 | | | and "]") MUST be a valid filter | 718 | | | expression based upon sub-attributes of | 719 | | | the parent attribute. Nested expressions | 720 | | | MAY be used. See examples below. | 721 +----------+-------------+------------------------------------------+ 723 Table 4: Grouping Operators 725 SCIM filters MUST conform to the following ABNF rules as per 726 [RFC5234] below: 728 FILTER = attrExp / logExp / valuePath / *1"not" "(" FILTER ")" 730 valuePath = attrPath "[" valFilter "]" 731 ; FILTER uses sub-attribs of a parent attrPath 733 valFilter = attrExp / logExp / *1"not" "(" valFilter ")" 735 attrExp = (attrPath SP "pr") / 736 (attrPath SP compareOp SP compValue) 738 logExp = FILTER SP ("and" / "or") SP FILTER 740 compValue = false / null / true / number / string 741 ; rules from JSON (RFC7159) 743 compareOp = "eq" / "ne" / "co" / 744 "sw" / "ew" / 745 "gt" / "lt" / 746 "ge" / "le" 748 attrPath = [URI ":"] ATTRNAME *1subAttr 749 ; SCIM attribute name 750 ; URI is SCIM "schema" URI 752 ATTRNAME = ALPHA *(nameChar) 754 nameChar = "-" / "_" / DIGIT / ALPHA 756 subAttr = "." ATTRNAME 757 ; a sub-attribute of a complex attribute 759 Figure 1: ABNF Specification of SCIM Filters 761 In the above ABNF, the "compValue" (comparison value) rule is built 762 on JSON Data Interchange format ABNF rules as specified in [RFC7159], 763 "DIGIT" and "ALPHA" are defined per Appendix B.1 of [RFC5234] and, 764 "URI" is defined per Appendix A of [RFC3986]. 766 Filters MUST be evaluated using standard order of operations 767 [Order-Operations]. Attribute operators have the highest precedence, 768 followed by the grouping operator (i.e, parentheses), followed by the 769 logical AND operator, followed by the logical OR operator. 771 If the specified attribute in a filter expression is a multi-valued 772 attribute, the resource MUST match if any of the instances of the 773 given attribute match the specified criterion; e.g. if a User has 774 multiple emails values, only one has to match for the entire User to 775 match. For complex attributes, a fully qualified Sub-Attribute MUST 776 be specified using standard attribute notation (Section 3.10). For 777 example, to filter by userName the parameter value is userName and to 778 filter by first name, the parameter value is name.givenName. 780 Providers MAY support additional filter operations if they choose. 781 Providers MUST decline to filter results if the specified filter 782 operation is not recognized and return a HTTP 400 error with an 783 appropriate human readable response. For example, if a client 784 specified an unsupported operator named 'regex' the service provider 785 should specify an error response description identifying the client 786 error; e.g., 'The operator 'regex' is not supported.' 788 String type attributes are case insensitive by default unless the 789 attribute type is defined as case exact. Attribute comparison 790 operators 'eq', 'co', and 'sw' MUST perform caseIgnore matching for 791 all string attributes unless the attribute is defined as case exact. 792 By default all string attributes are case insensitive. 794 Clients MAY query by schema or schema extensions by using a filter 795 expression including the "schemas" attribute. 797 The following are examples of valid filters. Some attributes (e.g. 798 rooms and rooms.number) are hypothetical extensions and are not part 799 of SCIM core schema: 801 filter=userName eq "bjensen" 803 filter=name.familyName co "O'Malley" 805 filter=userName sw "J" 807 filter=urn:ietf:params:scim:schemas:core:2.0:User:userName sw "J" 809 filter=title pr 811 filter=meta.lastModified gt "2011-05-13T04:42:34Z" 813 filter=meta.lastModified ge "2011-05-13T04:42:34Z" 815 filter=meta.lastModified lt "2011-05-13T04:42:34Z" 817 filter=meta.lastModified le "2011-05-13T04:42:34Z" 819 filter=title pr and userType eq "Employee" 821 filter=title pr or userType eq "Intern" 823 filter= 824 schemas eq "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" 826 filter=userType eq "Employee" and (emails co "example.com" or emails 827 co "example.org") 829 filter=userType ne "Employee" and not (emails co "example.com" or 830 emails co "example.org") 832 filter=userType eq "Employee" and (emails.type eq "work") 834 filter=userType eq "Employee" and emails[type eq "work" and 835 value co "@example.com"] 837 filter=emails[type eq "work" and value co "@example.com"] or 838 ims[type eq "xmpp" and value co "@foo.com"] 840 Figure 2: Example Filters 842 3.4.2.3. Sorting 844 Sort is OPTIONAL. Sorting allows clients to specify the order in 845 which resources are returned by specifying a combination of sortBy 846 and sortOrder URL parameters. 848 sortBy: The sortBy parameter specifies the attribute whose value 849 SHALL be used to order the returned responses. If the sortBy 850 attribute corresponds to a singular attribute, resources are 851 sorted according to that attribute's value; if it's a multi-valued 852 attribute, resources are sorted by the value of the primary 853 attribute (see Section 2.2 [I-D.ietf-scim-core-schema]), if any, 854 or else the first value in the list, if any. If the attribute is 855 complex the attribute name must be a path to a sub-attribute in 856 standard attribute notation (Section 3.10) ; e.g., 857 "sortBy=name.givenName". For all attribute types, if there is no 858 data for the specified "sortBy" value they are sorted via the 859 "sortOrder" parameter; i.e., they are ordered last if ascending 860 and first if descending. 862 sortOrder: The order in which the sortBy parameter is applied. 863 Allowed values are "ascending" and "descending". If a value for 864 sortBy is provided and no sortOrder is specified, the sortOrder 865 SHALL default to ascending. String type attributes are case 866 insensitive by default unless the attribute type is defined as a 867 case exact string. "sortOrder" MUST sort according to the 868 attribute type; i.e., for case insensitive attributes, sort the 869 result using case insensitive, unicode alphabetic sort order, with 870 no specific locale implied and for case exact attribute types, 871 sort the result using case sensitive, Unicode alphabetic sort 872 order. 874 3.4.2.4. Pagination 876 Pagination parameters can be used together to "page through" large 877 numbers of resources so as not to overwhelm the client or service 878 provider. Pagination is not session based hence clients SHOULD never 879 assume repeatable results. For example, a request for a list of 10 880 resources beginning with a startIndex of 1 may return different 881 results when repeated as a resource in the original result could be 882 deleted or new ones could be added in-between requests. Pagination 883 parameters and general behavior are derived from the OpenSearch 884 Protocol [OpenSearch]. 886 The following table describes the URL pagination parameters. 888 +------------+----------------------------+-------------------------+ 889 | Parameter | Description | Default | 890 +------------+----------------------------+-------------------------+ 891 | startIndex | The 1-based index of the | 1 | 892 | | first query result. A | | 893 | | value less than 1 SHALL be | | 894 | | interpreted as 1. | | 895 | count | Non-negative Integer. | None. When specified | 896 | | Specifies the desired | the service provider | 897 | | maximum number of query | MUST NOT return more | 898 | | results per page; e.g., | results than specified | 899 | | 10. A negative value SHALL | though MAY return fewer | 900 | | be interpreted as "0". A | results. If | 901 | | value of "0" indicates no | unspecified, the | 902 | | resource results are to be | maximum number of | 903 | | returned except for | results is set by the | 904 | | "totalResults". | service provider. | 905 +------------+----------------------------+-------------------------+ 907 Table 5: Pagination Request parameters 909 The following table describes the query response pagination 910 attributes specified by the service provider. 912 +--------------+----------------------------------------------------+ 913 | Element | Description | 914 +--------------+----------------------------------------------------+ 915 | itemsPerPage | Non-negative Integer. Specifies the number of | 916 | | query results returned in a query response page; | 917 | | e.g., 10. | 918 | totalResults | Non-negative Integer. Specifies the total number | 919 | | of results matching the client query; e.g., 1000. | 920 | startIndex | The 1-based index of the first result in the | 921 | | current set of query results; e.g., 1. | 922 +--------------+----------------------------------------------------+ 924 Table 6: Pagination Response Elements 926 For example, to retrieve the first 10 Users set the startIndex to 1 927 and the count to 10: 929 GET /Users?startIndex=1&count=10 930 Host: example.com 931 Accept: application/scim+json 932 Authorization: Bearer h480djs93hd8 933 The response to the query above returns metadata regarding paging 934 similar to the following example (actual resources removed for 935 brevity): 937 { 938 "totalResults":100, 939 "itemsPerPage":10, 940 "startIndex":1, 941 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 942 "Resources":[{ 943 ... 944 }] 945 } 947 Figure 3: ListResponse format for returning multiple resources 949 Given the example above, to continue paging set the startIndex to 11 950 and re-fetch; i.e., /Users?startIndex=11&count=10 952 3.4.2.5. Attributes 954 The following attributes control which attributes SHALL be returned 955 with a returned resource. SCIM clients MAY use up to one of these 956 two OPTIONAL parameters which MUST be supported by SCIM service 957 providers: 959 attributes A multi-valued list of strings indicating the names of 960 resource attributes to return in the response overriding the set 961 of attributes that would be returned by default. Attribute names 962 MUST be in standard.attribute notation (Section 3.10) form. See 963 additional retrieval query parameters (Section 3.9). 965 excludedAttributes A multi-valued list of strings indicating the 966 names of resource attributes to be removed from the default set of 967 attributes to return. This parameter SHALL have no effect on 968 attributes whose schema "returned" setting is "always" see Server 969 Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in 970 standard attribute notation (Section 3.10) form. See additional 971 retrieval query parameters (Section 3.9). 973 3.4.3. Querying Resources Using HTTP POST 975 Clients MAY execute queries without passing parameters on the URL by 976 using the HTTP POST verb combined with the '/.search' path extension. 977 The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL 978 be used to indicate the HTTP POST verb is intended to be a query 979 operation. 981 To create a new query result set, a SCIM client sends an HTTP POST 982 request to the desired SCIM resource endpoint (ending in '/.search'). 983 The body of the POST request MAY include any of the parameters as 984 defined in Section 3.4.2. 986 Query requests MUST be identified using the following URI: 987 'urn:ietf:params:scim:api:messages:2.0:SearchRequest'. The following 988 attributes are defined for query requests: 990 attributes A multi-valued list of strings indicating the names of 991 resource attributes to return in the response overriding the set 992 of attributes that would be returned by default. Attribute names 993 MUST be in standard attribute notation (Section 3.10) form. See 994 additional retrieval query parameters (Section 3.9). OPTIONAL. 996 excludedAttributes A multi-valued list of strings indicating the 997 names of resource attributes to be removed from the default set of 998 attributes to return. This parameter SHALL have no effect on 999 attributes whose schema "returned" setting is "always" see Server 1000 Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in 1001 standard attribute notation (Section 3.10) form. See additional 1002 retrieval query parameters (Section 3.9). OPTIONAL. 1004 filter The filter string used to request a subset of resources. The 1005 filter string MUST be a valid filter (Section 3.4.2.2) expression. 1006 OPTIONAL. 1008 sortBy A string indicating the attribute whose value SHALL be used 1009 to order the returned responses. The sortBy attribute MUST be in 1010 standard attribute notation (Section 3.10) form. See sorting 1011 (Section 3.4.2.3). OPTIONAL. 1013 sortOrder A string indicating the order in which the sortBy 1014 parameter is applied. Allowed values are "ascending" and 1015 "descending". See sorting (Section 3.4.2.3). OPTIONAL. 1017 startIndex An integer indicating the 1-based index of the first 1018 query result. See pagination (Section 3.4.2.4). OPTIONAL. 1020 count An integer indicating the desired maximum number of query 1021 results per page. See pagination (Section 3.4.2.4). OPTIONAL. 1023 After receiving a HTTP POST request, a response is returned as 1024 specified in Section 3.4.2. 1026 The following example shows an HTTP POST Query request with search 1027 parameters attributes, filter, and count included: 1029 POST /.search 1030 Host: example.com 1031 Accept: application/scim+json 1032 Content-Type: application/scim+json 1033 Authorization: Bearer h480djs93hd8 1034 Content-Length: ... 1036 { 1037 "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], 1038 "attributes": ["displayName", "userName"], 1039 "filter": 1040 "displayName sw \"smith\"", 1041 "startIndex": 1, 1042 "count": 10 1043 } 1045 Figure 4: Example POST Query Request 1047 A query response is shown with the first page of results. For 1048 brevity reasons, only two matches are shown: one User and one Group. 1050 HTTP/1.1 200 OK 1051 Content-Type: application/scim+json 1052 Location: https://example.com/.search 1053 { 1054 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 1055 "totalResults":100, 1056 "itemsPerPage":10, 1057 "startIndex":1, 1058 "Resources":[ 1059 { 1060 "meta":{ 1061 "location": 1062 "https://example.com/Users/2819c223-7f76-413861904646", 1063 "resourceType":"User", 1064 "lastModified": ... 1065 }, 1066 "userName":"jsmith", 1067 "displayName":"Smith, James" 1068 }, 1069 { 1070 "meta":{ 1071 "location": 1072 "https://example.com/Groups/c8596b90-7539-4f20968d1908", 1073 "resourceType":"Group", 1074 "lastModified": ... 1075 }, 1076 "displayName":"Smith Family" 1077 }, 1078 ... 1079 ] 1080 } 1082 Figure 5: Example POST Query Response 1084 3.5. Modifying Resources 1086 Resources can be modified in whole or in part via PUT or PATCH, 1087 respectively. Implementers MUST support PUT as specified in 1088 Section 4.3 [RFC7231]. Resources such as Groups may be very large 1089 hence implementers SHOULD support HTTP PATCH [RFC5789] to enable 1090 partial resource modifications. 1092 3.5.1. Replacing with PUT 1094 HTTP PUT is used to perform a full update of a resource's attributes. 1095 Clients that MAY have previously retrieved the entire resource in 1096 advance and revised it, MAY replace the resource using an HTTP PUT. 1097 Because SCIM resource identifiers are typically assigned by the 1098 service provider, HTTP PUT MUST NOT be used to create new resources. 1100 As the operation intent is to replace all attributes, SCIM clients 1101 MAY send all attributes regardless of each attribute's mutability. 1102 The server will apply attribute by attribute replace according to the 1103 following attribute mutability rules: 1105 readWrite, writeOnly Any values provided SHALL replace the existing 1106 attribute values. 1108 Attributes whose mutability is "readWrite", that are omitted from 1109 the request body, MAY be assumed to be not asserted by the client. 1110 The service provider MAY assume any existing values are to be 1111 cleared or the service provider MAY assign a default value to the 1112 final resource representation. Service providers MAY take into 1113 account whether a client has access to, or understands, all of the 1114 resource's attributes when deciding whether non-asserted 1115 attributes SHALL be removed or defaulted. Clients that would like 1116 to override a server defaults, MAY specify "null" for a single- 1117 valued attribute or an empty array "[]" for a multi-valued 1118 attribute to clear all values. 1120 immutable If value(s) are already set for the attribute, the input 1121 value(s) MUST match or HTTP status 400 SHOULD be returned with 1122 error code "mutability". If the service provider has no existing 1123 values, the new value(s) SHALL be applied. 1125 readOnly Any values provided (e.g. meta.resourceType) SHALL be 1126 ignored. 1128 If an attribute is "required", clients MUST specify the attribute in 1129 the PUT request. 1131 Unless otherwise specified a successful PUT operation returns a 200 1132 OK response code and the entire resource within the response body, 1133 enabling the client to correlate the client's and the service 1134 provider's views of the updated resource. Example: 1136 PUT /Users/2819c223-7f76-453a-919d-413861904646 1137 Host: example.com 1138 Accept: application/scim+json 1139 Content-Type: application/scim+json 1140 Authorization: Bearer h480djs93hd8 1141 If-Match: W/"a330bc54f0671c9" 1143 { 1144 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 1145 "id":"2819c223-7f76-453a-919d-413861904646", 1146 "userName":"bjensen", 1147 "externalId":"bjensen", 1148 "name":{ 1149 "formatted":"Ms. Barbara J Jensen III", 1150 "familyName":"Jensen", 1151 "givenName":"Barbara", 1152 "middleName":"Jane" 1153 }, 1154 "roles":[], 1155 "emails":[ 1156 { 1157 "value":"bjensen@example.com" 1158 }, 1159 { 1160 "value":"babs@jensen.org" 1161 } 1162 ] 1163 } 1164 The service responds with the entire, updated User: 1166 HTTP/1.1 200 OK 1167 Content-Type: application/scim+json 1168 ETag: W/"b431af54f0671a2" 1169 Location: 1170 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646" 1171 { 1172 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 1173 "id":"2819c223-7f76-453a-919d-413861904646", 1174 "userName":"bjensen", 1175 "externalId":"bjensen", 1176 "name":{ 1177 "formatted":"Ms. Barbara J Jensen III", 1178 "familyName":"Jensen", 1179 "givenName":"Barbara", 1180 "middleName":"Jane" 1181 }, 1182 "emails":[ 1183 { 1184 "value":"bjensen@example.com" 1185 }, 1186 { 1187 "value":"babs@jensen.org" 1188 } 1189 ], 1190 "meta": { 1191 "resourceType":"User", 1192 "created":"2011-08-08T04:56:22Z", 1193 "lastModified":"2011-08-08T08:00:12Z", 1194 "location": 1195 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 1196 "version":"W\/\"b431af54f0671a2\"" 1197 } 1198 } 1200 3.5.2. Modifying with PATCH 1202 HTTP PATCH is an OPTIONAL server function that enables clients to 1203 update one or more attributes of a SCIM resource using a sequence of 1204 operations to "add", "remove", or "replace" values. The general form 1205 of the SCIM patch request is based on JavaScript Object Notation 1206 (JSON) Patch [RFC6902]. One difference between SCIM patch and JSON 1207 patch is that SCIM servers do not support array indexing and may not 1208 support all [RFC6902] operation types. 1210 The body of each request MUST contain the following "schemas" 1211 attribute with the URI value of: 1212 "urn:ietf:params:scim:api:messages:2.0:PatchOp". 1214 The body of an HTTP PATCH request MUST contain the attribute 1215 "Operations", whose value is an array of one or more patch 1216 operations. Each patch operation object MUST have exactly one "op" 1217 member, whose value indicates the operation to perform and MAY be one 1218 of "add", "remove", or "replace". The semantics of each operation 1219 are defined in the following sub-sections. 1221 The following is an example representation of a PATCH request showing 1222 the basic JSON structure (non-normative): 1224 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1225 "Operations":[ 1226 { 1227 "op":"add", 1228 "path":"members", 1229 "value":[ 1230 { 1231 "display": "Babs Jensen", 1232 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1233 "value": "2819c223-7f76-453a-919d-413861904646" 1234 } 1235 ] 1236 }, 1237 ... + additional operations if needed ... 1238 ] 1239 } 1241 Figure 6: Example JSON body for SCIM PATCH Request 1243 A "path" attribute value is a String containing an attribute path 1244 describing the target of the operation. The "path" attribute is 1245 OPTIONAL for "add" and "replace" and is REQUIRED for "remove" 1246 operations. See relevant operation sections below for details. 1248 The "path" attribute is described by the following ABNF syntax rule: 1250 PATH = attrPath / valuePath [subAttr] 1252 Figure 7: SCIM Patch PATH Rule 1254 The ABNF rules, "attrPath", "valuePath", and "subAttr" are defined in 1255 Section 3.4.2.2. The "valuePath" rule allows specific values of a 1256 complex, multi-valued attribute to be selected. 1258 Valid examples of "path" values are as follows: 1260 "path":"members" 1262 "path":"name.familyName" 1264 "path":"addresses[type eq \"work\"]" 1266 "path":"members[value eq 1267 \"2819c223-7f76-453a-919d-413861904646\"]" 1269 "path":"members[value eq 1270 \"2819c223-7f76-453a-919d-413861904646\"].displayName" 1272 Figure 8: Example Path Values 1274 Each operation against an attribute MUST be compatible with the 1275 attribute's mutability and schema as defined in the Attribute Types 1276 Section of [I-D.ietf-scim-core-schema]. For example, a client MUST 1277 NOT modify an attribute that has mutability "readOnly" or 1278 "immutable". However, a client MAY "add" a value to an "immutable" 1279 attribute if the attribute had no previous value. An operation that 1280 is not compatibile with an attribute's mutability or schema SHALL 1281 return the appropriate HTTP response status code and a JSON detail 1282 error response as defined in Section 3.12. 1284 The attribute notation rules described in Section 3.10 apply for 1285 describing attribute paths. For all operations, the value of the 1286 "schemas" attribute on the SCIM service provider's representation of 1287 the resource SHALL be assumed by default. If one of the PATCH 1288 operations modifies the "schemas" attribute, subsequent operations 1289 SHALL assume the modified state of the "schemas" attribute. Clients 1290 MAY implicitly modify the "schemas" attribute by adding (or 1291 replacing) an attribute with its fully qualified name including 1292 schema URN. For example, adding the attribute "urn:ietf:params:scim: 1293 schemas:extension:enterprise:2.0:User:employeeNumber", automatically 1294 adds the value 1295 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" to the 1296 resource's "schemas" attribute. 1298 Each patch operation represents a single action to be applied to the 1299 same SCIM resource specified by the request URI. Operations are 1300 applied sequentially in the order they appear in the array. Each 1301 operation in the sequence is applied to the target resource; the 1302 resulting resource becomes the target of the next operation. 1303 Evaluation continues until all operations are successfully applied or 1304 until an error condition is encountered. 1306 For a multi-valued attributes, a patch operation that sets a value's 1307 "primary" attribute to "true", SHALL cause the server to 1308 automatically set "primary" to "false" for any other values in the 1309 array as only one value MAY be primary. 1311 A patch request, regardless of the number of operations, SHALL be 1312 treated as atomic. If a single operation encounters an error 1313 condition, the original SCIM resource MUST be restored, and a failure 1314 status SHALL be returned. 1316 If a request fails, the server SHALL return an HTTP response status 1317 code and a JSON detail error response as defined in Section 3.12. 1319 On successful completion, the server MUST return either a 200 OK 1320 response code and the entire resource (subject to the "attributes" 1321 query parameter - see Additional Retrieval Query Parameters 1322 (Section 3.9) ) within the response body, or a 204 No Content 1323 response code and the appropriate response headers for a successful 1324 patch request. The server MUST return a 200 OK if the "attributes" 1325 parameter is specified on the request. 1327 3.5.2.1. Add Operation 1329 The "add" operation is used to add a new attribute value to an 1330 existing resource. 1332 The operation MUST contain a "value" member whose content specifies 1333 the value to be added. The value MAY be a quoted value OR it may be 1334 a JSON object containing the sub-attributes of the complex attribute 1335 specified in the operation's "path". 1337 The result of the add operation depends upon what the target location 1338 indicated by "path" references: 1340 o If omitted, the target location is assumed to be the resource 1341 itself. The "value" parameter contains a set of attributes to be 1342 added to the resource. 1344 o If the target location does not exist, the attribute and value is 1345 added. 1347 o If the target location specifies a complex attribute, a set of 1348 sub-attributes SHALL be specified in the "value" parameter. 1350 o If the target location specifies a multi-valued attribute, a new 1351 value is added to the attribute. 1353 o if the target location specifies a single-valued attribute, the 1354 existing value is replaced. 1356 o If the target location specifies an attribute that does not exist 1357 (has no value), the attribute is added with the new value. 1359 o If the target location exists, the value is replaced. 1361 o If the target location already contains the value specified, no 1362 changes SHOULD be made to the resource and a success response 1363 SHOULD be returned. Unless other operations change the resource, 1364 this operation SHALL NOT change the modify timestamp of the 1365 resource. 1367 The following example shows how to add a member to a group. Some 1368 text removed for readability ("..."): 1370 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1371 Host: example.com 1372 Accept: application/scim+json 1373 Content-Type: application/scim+json 1374 Authorization: Bearer h480djs93hd8 1375 If-Match: W/"a330bc54f0671c9" 1376 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1377 "Operations":[ 1378 { 1379 "op":"add", 1380 "path":"members", 1381 "value":[ 1382 { 1383 "display": "Babs Jensen", 1384 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1385 "value": "2819c223-7f76-453a-919d-413861904646" 1386 } 1387 ] 1388 } 1389 ] 1390 } 1392 If the user was already a member of this group, no changes should be 1393 made to the resource and a success response should be returned. The 1394 server responds with either the entire updated Group or no response 1395 body: 1397 HTTP/1.1 204 No Content 1398 Authorization: Bearer h480djs93hd8 1399 ETag: W/"b431af54f0671a2" 1400 Location: 1401 "https://example.com/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" 1403 The following example shows how to add one or more attributes to a 1404 User resource without using a "path" attribute. 1406 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1407 Host: example.com 1408 Accept: application/scim+json 1409 Content-Type: application/scim+json 1410 Authorization: Bearer h480djs93hd8 1411 If-Match: W/"a330bc54f0671c9" 1413 { 1414 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1415 "Operations":[{ 1416 "op":"add", 1417 "value":{ 1418 "emails":[ 1419 { 1420 "value":"babs@jensen.org", 1421 "type":"home" 1422 } 1423 ], 1424 "nickname":"Babs" 1425 }] 1426 } 1428 In the above example, an additional value is added to the multi- 1429 valued attribute "emails". The second attribute, "nickname" is added 1430 to the User resource. If the resource already had an existing 1431 "nickname", the value is replaced per the processing rules above for 1432 single-valued attributes. 1434 3.5.2.2. Remove Operation 1436 The "remove" operation removes the value at the target location 1437 specified by the required attribute "path". The operation performs 1438 the following functions depending on the target location specified by 1439 "path" : 1441 o If "path" is unspecified, the operation fails with HTTP status 1442 "400" and "scimType" of "noTarget". 1444 o If the target location is a single-value attribute, the attribute 1445 and its associated value is removed and the attribute SHALL be 1446 considered unassigned. 1448 o If the target location is a multi-valued attribute and no filter 1449 is specified, the attribute and all values are removed and the 1450 attribute SHALL be considered unassigned. 1452 o If the target location is a multi-valued attribute and a complex 1453 filter is specified comparing a "value", the values matched by the 1454 filter are removed. If after removal of the selected values, no 1455 other values remain, the multi-valued attribute SHALL be 1456 considered unassigned. 1458 o If the target location is a complex-multi-valued attribute and a 1459 complex filter is specified based on the attribute's sub- 1460 attributes, the matching records are removed. Sub-attributes 1461 whose values have been removed SHALL be considered unassigned. If 1462 the complex-multi-valued attribute has no remaining records, the 1463 attribute SHALL be considered unassigned. 1465 If an attribute is removed or becomes unassigned and is defined as a 1466 required attribute or a read-only attribute, the server SHALL return 1467 an HTTP response status code and a JSON detail error response as 1468 defined in Section 3.12 with a "scimType" error of "mutability". 1470 The following example shows how to remove a member from a group. As 1471 with the previous example, the "display" sub-attribute is optional. 1472 If the user was not a member of this group, no changes should be made 1473 to the resource and a success response should be returned. 1475 Note that server responses have been omitted for the rest of the 1476 PATCH examples. 1478 Remove a single member from a group. Some text removed for 1479 readability ("..."): 1481 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1482 Host: example.com 1483 Accept: application/scim+json 1484 Content-Type: application/scim+json 1485 Authorization: Bearer h480djs93hd8 1486 If-Match: W/"a330bc54f0671c9" 1488 { 1489 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1490 "Operations":[{ 1491 "op":"remove", 1492 "path":"members[value eq \"2819c223-7f76-...413861904646\"]" 1493 }] 1494 } 1496 Remove all members of a group: 1498 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1499 Host: example.com 1500 Accept: application/scim+json 1501 Content-Type: application/scim+json 1502 Authorization: Bearer h480djs93hd8 1503 If-Match: W/"a330bc54f0671c9" 1505 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1506 "Operations":[{ 1507 "op":"remove","path":"members" 1508 }] 1509 } 1511 Removal of a value from a complex-multi-valued attribute (request 1512 headers removed for brevity): 1514 { 1515 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1516 "Operations": [{ 1517 "op":"remove", 1518 "path":"emails[type eq \"work\" and value ew \"example.com\"]" 1519 }] 1520 } 1521 Example request to remove and add a member. Some text removed for 1522 readability ("..."): 1524 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1525 Host: example.com 1526 Accept: application/scim+json 1527 Content-Type: application/scim+json 1528 Authorization: Bearer h480djs93hd8 1529 If-Match: W/"a330bc54f0671c9" 1530 { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1531 "Operations": [ 1532 { 1533 "op":"remove", 1534 "path":"members[value eq\"2819c223...919d-413861904646\"]" 1535 }, 1536 { 1537 "op":"add", 1538 "path":"members", 1539 "value": [ 1540 { 1541 "display": "James Smith", 1542 "$ref":"https://example.com/v2/Users/08e1d05d...473d93df9210", 1543 "value": "08e1d05d...473d93df9210" 1544 } 1545 ] 1546 } 1547 ] 1548 } 1549 The following example shows how to replace all the members of a group 1550 with a different members list. Some text removed for readabilty 1551 ("..."): 1553 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1554 Host: example.com 1555 Accept: application/scim+json 1556 Content-Type: application/scim+json 1557 Authorization: Bearer h480djs93hd8 1558 If-Match: W/"a330bc54f0671c9" 1559 { 1560 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1561 "Operations": [ 1562 { 1563 "op":"remove","path":"members" 1564 }, 1565 { 1566 "op":"add", 1567 "path":"members", 1568 "value":[ 1569 { 1570 "display": "Babs Jensen", 1571 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1572 "value": "2819c223-7f76-453a-919d-413861904646" 1573 }, 1574 { 1575 "display": "James Smith", 1576 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1577 "value": "08e1d05d-121c-4561-8b96-473d93df9210" 1578 }] 1579 } 1580 ] 1581 } 1583 3.5.2.3. Replace Operation 1585 The "replace" operation replaces the value at the target location 1586 specified by the "path". The operation performs the following 1587 functions depending on the target location specified by "path" : 1589 o If the "path" parameter is omitted, the target is assumed to be 1590 the resource itself. In this case, the "value" attribute SHALL 1591 contain a list of one or more attributes that are to be replaced. 1593 o If the target location is a single-value attribute, the attributes 1594 value is replaced. 1596 o If the target location is a multi-valued attribute and no filter 1597 is specified, the attribute and all values are replaced. 1599 o If the target location path specifies an attribute that does not 1600 exist, the service provider SHALL treat the operation as an "add". 1602 o If the target location specifies a complex attribute, a set of 1603 sub-attributes SHALL be specified in the "value" parameter which 1604 replaces any existing values or adds where an attribute did not 1605 previously exist. Sub-attributes that are not specified in the 1606 "value" parameter are left unchanged. 1608 o If the target location is a multi-valued attribute and a value 1609 selction ("valuePath") filter is specified that matches one or 1610 more values of the mulit-valued attribute, then all matching 1611 record values SHALL be replaced. 1613 o If the target location is a complex-multi-valued attribute with a 1614 value selection filter ("valuePath") and a specific sub-attribute 1615 (e.g. "addresses[type eq "work"].streetAddress" ), the matching 1616 sub-attribute of all matching records is replaced. 1618 o If the target location is a mulit-valued attribute for which a 1619 value selection filter ("valuePath") has been supplied and no 1620 record match was made, the service provider SHALL fail by 1621 returning HTTP status "400", and a "scimType" of "noTarget". 1623 The following example shows how to replace all the members of a group 1624 with a different members list in a single replace operation. Some 1625 text removed for readability ("..."): 1627 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1628 Host: example.com 1629 Accept: application/scim+json 1630 Content-Type: application/scim+json 1631 Authorization: Bearer h480djs93hd8 1632 If-Match: W/"a330bc54f0671c9" 1634 { 1635 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1636 "Operations": [{ 1637 "op":"replace", 1638 "path":"members", 1639 "value":[ 1640 { 1641 "display": "Babs Jensen", 1642 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1643 "value": "2819c223...413861904646" 1644 }, 1645 { 1646 "display": "James Smith", 1647 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1648 "value": "08e1d05d...473d93df9210" 1649 } 1650 ] 1651 }] 1652 } 1653 The following example shows how to change a User's entire "work" 1654 address using a "valuePath" filter. Note that by setting "primary" 1655 to "true", the service provider will reset primary to "false" for any 1656 other existing values of "addresses". 1658 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1659 Host: example.com 1660 Accept: application/scim+json 1661 Content-Type: application/scim+json 1662 Authorization: Bearer h480djs93hd8 1663 If-Match: W/"a330bc54f0671c9" 1665 { 1666 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1667 "Operations": [{ 1668 "op":"replace", 1669 "path":"addresses[type eq \"work\"]", 1670 "value": 1671 { 1672 "type": "work", 1673 "streetAddress": "911 Universal City Plaza", 1674 "locality": "Hollywood", 1675 "region": "CA", 1676 "postalCode": "91608", 1677 "country": "US", 1678 "formatted": "911 Universal City Plaza\nHollywood, CA 91608 US", 1679 "primary": true 1680 } 1681 }] 1682 } 1683 The following example shows how to change a specific sub-attribute 1684 "streetAddress" of complex attribute "emails" selected by "valuePath" 1685 filter: 1687 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1688 Host: example.com 1689 Accept: application/scim+json 1690 Content-Type: application/scim+json 1691 Authorization: Bearer h480djs93hd8 1692 If-Match: W/"a330bc54f0671c9" 1694 { 1695 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1696 "Operations": [{ 1697 "op":"replace", 1698 "path":"addresses[type eq \"work\"].streetAddress", 1699 "value":"1010 Broadway Ave" 1700 }] 1701 } 1702 The following example shows how to replace all values of one or more 1703 specific attributes of a User resource. Note that other attributes 1704 are unaffected. 1706 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1707 Host: example.com 1708 Accept: application/scim+json 1709 Content-Type: application/scim+json 1710 Authorization: Bearer h480djs93hd8 1711 If-Match: W/"a330bc54f0671c9" 1713 { 1714 "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1715 "Operations": [{ 1716 "op":"replace", 1717 "value":"{ 1718 "emails":[ 1719 { 1720 "value":"bjensen@example.com", 1721 "type":"work", 1722 "primary":true 1723 }, 1724 { 1725 "value":"babs@jensen.org", 1726 "type":"home" 1727 } 1728 ], 1729 "nickname":"Babs" 1730 }] 1731 } 1733 3.6. Deleting Resources 1735 Clients request resource removal via DELETE. Service providers MAY 1736 choose not to permanently delete the resource, but MUST return a 404 1737 error code for all operations associated with the previously deleted 1738 Id. Service providers MUST also omit the resource from future query 1739 results. In addition the service provider SHOULD NOT consider the 1740 deleted resource in conflict calculation. For example if a User 1741 resource is deleted, a CREATE request for a User resource with the 1742 same userName as the previously deleted resource should not fail with 1743 a 409 error due to userName conflict. 1745 DELETE /Users/2819c223-7f76-453a-919d-413861904646 1746 Host: example.com 1747 Authorization: Bearer h480djs93hd8 1748 If-Match: W/"c310cd84f0281b7" 1750 In response to a successful delete, the server SHALL respond with 1751 successful HTTP status 204 (No Content). A non-normative example 1752 response: 1754 HTTP/1.1 204 No Content 1756 Example: client attempt to retrieve the previously deleted User 1758 GET /Users/2819c223-7f76-453a-919d-413861904646 1759 Host: example.com 1760 Authorization: Bearer h480djs93hd8 1762 Server Response: 1764 HTTP/1.1 404 NOT FOUND 1766 { 1767 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 1768 "Errors":[ 1769 { 1770 "description": 1771 "Resource 2819c223-7f76-453a-919d-413861904646 not found", 1772 "code":"404" 1773 } 1774 ] 1775 } 1777 3.7. Bulk Operations 1779 The SCIM bulk operation is an optional server feature that enables 1780 clients to send a potentially large collection of resource operations 1781 in a single request. The body of a a bulk operation contains a set 1782 of HTTP resource operations using one of the API supported HTTP 1783 methods; i.e., POST, PUT, PATCH or DELETE. 1785 Bulk requests are identified using the following URI: 1786 "urn:ietf:params:scim:api:messages:2.0:BulkRequest". Bulk responses 1787 are identified using the following URI: 1788 "urn:ietf:params:scim:api:messages:2.0:BulkResponse". Bulk requests 1789 and bulk responses share many attributes. Unless otherwise 1790 specified, each attribute below is present in both bulk requests and 1791 bulk responses. 1793 The following Singular Attribute is defined in addition to the common 1794 attributes defined in SCIM core schema. 1796 failOnErrors 1797 An Integer specifying the number of errors that the service 1798 provider will accept before the operation is terminated and an 1799 error response is returned. OPTIONAL in a request. Not valid in 1800 a response. 1802 The following Complex Multi-valued Attribute is defined in addition 1803 to the common attributes defined in core schema. 1805 Operations 1806 Defines operations within a bulk job. Each operation corresponds 1807 to a single HTTP request against a resource endpoint. REQUIRED. 1808 Operations has the following sub-attributes: 1810 method The HTTP method of the current operation. Possible values 1811 are POST, PUT, PATCH or DELETE. REQUIRED. 1813 bulkId The transient identifier of a newly created resource, 1814 unique within a bulk request and created by the client. The 1815 bulkId serves as a surrogate resource id enabling clients to 1816 uniquely identify newly created resources in the Response and 1817 cross reference new resources in and across operations within a 1818 bulk request. REQUIRED when method is POST. 1820 version The current resource version. Version is MAY be used if 1821 the service provider supports ETags and the method is PUT, 1822 PATCH, or DELETE. 1824 path The resource's relative path. If the method is POST the 1825 value must specify a resource type endpoint; e.g., /Users or 1826 /Groups whereas all other method values must specify the path 1827 to a specific resource; e.g., /Users/2819c223-7f76-453a-919d- 1828 413861904646. REQUIRED in a request. 1830 data The resource data as it would appear for a single POST, PUT 1831 or PATCH resource operation. REQUIRED in a request when method 1832 is POST, PUT and PATCH. 1834 location The resource endpoint URL. REQUIRED in a response, 1835 except in the event of a POST failure. 1837 response The HTTP response body to the specified request 1838 operation. When indicating a response with an HTTP status 1839 other than a 200 series response, the response body MUST be 1840 included. For normal completion, the server MAY elect to omit 1841 the response body. 1843 status The HTTP response status code to the requested operation. 1844 When indicating an error, the "response" attribute MUST contain 1845 the detailed error response as per Section 3.12. 1847 If a bulk job is processed successfully the HTTP response code 200 OK 1848 MUST be returned, otherwise an appropriate HTTP error code MUST be 1849 returned. 1851 The service provider MUST continue performing as many changes as 1852 possible and disregard partial failures. The client MAY override 1853 this behavior by specifying a value for the "failOnErrors" attribute. 1854 The failOnErrors attribute defines the number of errors that the 1855 service provider should accept before failing the remaining 1856 operations returning the response. 1858 To be able to reference a newly created resource the attribute bulkId 1859 MUST be specified when creating new resources. The "bulkId" is 1860 defined by the client as a surrogate identifier in a POST operation 1861 (see Section 3.7.2). The service provider MUST return the same 1862 "bulkId" together with the newly created resource. The "bulkId" can 1863 then be used by the client to map the service provider id with the 1864 "bulkId" of the created resource. 1866 A SCIM service provider MAY elect to optimize a sequence operations 1867 received (e.g. to improve processing performance). When doing so, 1868 the service provider MUST ensure the clients intent is preserved and 1869 the same stateful result is achieved as for non-optimized processing. 1870 For example, before a "User" can be added to a "Group", they must 1871 first be created. Processing these requests out of order, might 1872 result in a failure to add the new "User" to the "Group". 1874 3.7.1. Circular Reference Processing 1876 The service provider MUST try to resolve circular cross references 1877 between resources in a single bulk job but MAY stop after a failed 1878 attempt and instead return the status code 409 Conflict. The 1879 following example exhibits the potential conflict. 1881 POST /v2/Bulk 1882 Host: example.com 1883 Accept: application/scim+json 1884 Content-Type: application/scim+json 1885 Authorization: Bearer h480djs93hd8 1886 Content-Length: ... 1888 { 1889 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 1890 "Operations": [ 1891 { 1892 "method": "POST", 1893 "path": "/Groups", 1894 "bulkId": "qwerty", 1895 "data": { 1896 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1897 "displayName": "Group A", 1898 "members": [ 1899 { 1900 "type": "Group", 1901 "value": "bulkId:ytrewq" 1902 } 1903 ] 1904 } 1905 }, 1906 { 1907 "method": "POST", 1908 "path": "/Groups", 1909 "bulkId": "ytrewq", 1910 "data": { 1911 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1912 "displayName": "Group B", 1913 "members": [ 1914 { 1915 "type": "Group", 1916 "value": "bulkId:qwerty" 1917 } 1918 ] 1919 } 1920 } 1921 ] 1922 } 1924 If the service provider resolved the above circular references the 1925 following is returned from a subsequent GET request. 1927 GET /v2/Groups?filter=displayName sw 'Group' 1928 Host: example.com 1929 Accept: application/scim+json 1930 Authorization: Bearer h480djs93hd8 1932 HTTP/1.1 200 OK 1933 Content-Type: application/scim+json 1935 { 1936 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 1937 "totalResults": 2, 1938 "Resources": [ 1939 { 1940 "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1941 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1942 "displayName": "Group A", 1943 "meta": { 1944 "resourceType": "Group", 1945 "created": "2011-08-01T18:29:49.793Z", 1946 "lastModified": "2011-08-01T18:29:51.135Z", 1947 "location": 1948 "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1949 "version": "W\/\"mvwNGaxB5SDq074p\"" 1950 }, 1951 "members": [ 1952 { 1953 "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1954 "$ref": 1955 "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1956 "type": "Group" 1957 } 1958 ] 1959 }, 1960 { 1961 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 1962 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 1963 "displayName": "Group B", 1964 "meta": { 1965 "resourceType": "Group", 1966 "created": "2011-08-01T18:29:50.873Z", 1967 "lastModified": "2011-08-01T18:29:50.873Z", 1968 "location": 1969 "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 1970 "version": "W\/\"wGB85s2QJMjiNnuI\"" 1971 }, 1972 "members": [ 1973 { 1974 "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1975 "$ref": 1976 "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1977 "type": "Group" 1978 } 1979 ] 1980 } 1981 ] 1982 } 1984 3.7.2. BulkdId Temporary Identifiers 1986 A SCIM client can, within one bulk operation, create a new "User", a 1987 new "Group" and add the newly created "User" to the newly created 1988 "Group". In order to add the new "User" to the "Group" the client 1989 must use the surrogate id attribute, "bulkId", to reference the User. 1990 The "bulkId" attribute value must be pre-pended with the literal 1991 "bulkId:"; e.g., if the bulkId is 'qwerty', the value is 1992 "bulkId:qwerty". The service provider MUST replace the string 1993 "bulkId:qwerty" with the permanent resource id once created. 1995 To create multiple distinct requests, each with their own "bulkId", 1996 the SCIM client specifies different "bulkId" values for each separate 1997 request. 1999 The following example creates a User with the "userName" 'Alice' and 2000 a "Group" with the "displayName" 'Tour Guides' with Alice as a 2001 member. Notice that each operation has its own "bulkId" value. 2002 However, the second operation (whose "bulkId" is "ytrewq") refers to 2003 the "bulkId" of "qwerty" in order to add Alice to new 'Tour Guides' 2004 group. 2006 POST /v2/Bulk 2007 Host: example.com 2008 Accept: application/scim+json 2009 Content-Type: application/scim+json 2010 Authorization: Bearer h480djs93hd8 2011 Content-Length: ... 2013 { 2014 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 2015 "Operations": [ 2016 { 2017 "method": "POST", 2018 "path": "/Users", 2019 "bulkId": "qwerty", 2020 "data": { 2021 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 2022 "userName": "Alice" 2023 } 2024 }, 2025 { 2026 "method": "POST", 2027 "path": "/Groups", 2028 "bulkId": "ytrewq", 2029 "data": { 2030 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 2031 "displayName": "Tour Guides", 2032 "members": [ 2033 { 2034 "type": "User", 2035 "value": "bulkId:qwerty" 2036 } 2037 ] 2038 } 2039 } 2040 ] 2041 } 2042 The service provider returns the following response: 2044 HTTP/1.1 200 OK 2045 Content-Type: application/json 2047 { 2048 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2049 "Operations": [ 2050 { 2051 "location": 2052 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2053 "method": "POST", 2054 "bulkId": "qwerty", 2055 "version": "W\/\"4weymrEsh5O6cAEK\"", 2056 "status": { 2057 "code": "201" 2058 } 2059 }, 2060 { 2061 "location": 2062 "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 2063 "method": "POST", 2064 "bulkId": "ytrewq", 2065 "version": "W\/\"lha5bbazU3fNvfe5\"", 2066 "status": { 2067 "code": "201" 2068 } 2069 } 2070 ] 2071 } 2073 In the above example, the Alice User resource has an "id" of 2074 "92b725cd-9465-4e7d-8c16-01f8e146b87a" and the Tour Guides Group has 2075 an "id" of "e9e30dba-f08f-4109-8486-d5c6a331660a". 2077 A subsequent GET request for the 'Tour Guides' Group (with an "id" 2078 of"e9e30dba-f08f-4109-8486-d5c6a331660a") returns the following with 2079 Alice's "id" as the value for the member in the Group 'Tour Guides': 2081 HTTP/1.1 200 OK 2082 Content-Type: application/scim+json 2083 Location: 2084 https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 2085 ETag: W/"lha5bbazU3fNvfe5" 2087 { 2088 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 2089 "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", 2090 "displayName": "Tour Guides", 2091 "meta": { 2092 "resourceType": "Group", 2093 "created": "2011-08-01T18:29:49.793Z", 2094 "lastModified": "2011-08-01T20:31:02.315Z", 2095 "location": 2096 "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 2097 "version": "W\/\"lha5bbazU3fNvfe5\"" 2098 }, 2099 "members": [ 2100 { 2101 "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", 2102 "$ref": 2103 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2104 "type": "User" 2105 } 2106 ] 2107 } 2109 Extensions that include references to other resources MUST be handled 2110 in the same way by the service provider. The following example uses 2111 the bulkId attribute within the enterprise extension managerId 2112 attribute. 2114 POST /v2/Bulk 2115 Host: example.com 2116 Accept: application/scim+json 2117 Content-Type: application/scim+json 2118 Authorization: Bearer h480djs93hd8 2119 Content-Length: ... 2121 { 2122 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 2123 "Operations": [ 2124 { 2125 "method": "POST", 2126 "path": "/Users", 2127 "bulkId": "qwerty", 2128 "data": { 2129 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 2130 "userName": "Alice" 2131 } 2132 }, 2133 { 2134 "method": "POST", 2135 "path": "/Users", 2136 "bulkId": "ytrewq", 2137 "data": { 2138 "schemas": [ 2139 "urn:ietf:params:scim:schemas:core:2.0:User", 2140 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" 2141 ], 2142 "userName": "Bob", 2143 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { 2144 "employeeNumber": "11250", 2145 "manager": { 2146 "managerId": "batchId:qwerty", 2147 "displayName": "Alice" 2148 } 2149 } 2150 } 2151 } 2152 ] 2153 } 2155 3.7.3. Response and Error Handling 2157 The service provider response MUST include the result of all 2158 processed operations. A "location" attribute that includes the 2159 resource's endpoint MUST be returned for all operations excluding 2160 failed POSTs. The status attribute includes information about the 2161 success or failure of one operation within the bulk job. The 2162 attribute status MUST include the code attribute that holds the HTTP 2163 response code that would have been returned if a single HTTP request 2164 would have been used. If an error occurred the status MUST also 2165 include the description attribute containing a human readable 2166 explanation of the error. 2168 "status": "201" 2170 The following is an example of a status in a failed operation. 2172 "status": "400", 2173 "response":{ 2174 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2175 "scimType":"invalidSyntax" 2176 "detail": 2177 "Request is unparseable, syntactically incorrect, or violates schema.", 2178 "status":"400" 2179 } 2181 The following example shows how to add, update, and remove a user. 2182 The "failOnErrors" attribute is set to '1' indicating the service 2183 provider should return on the first error. The POST operation's 2184 bulkId value is set to 'qwerty' enabling the client to match the new 2185 User with the returned resource id '92b725cd-9465-4e7d- 2186 8c16-01f8e146b87a'. 2188 POST /v2/Bulk 2189 Host: example.com 2190 Accept: application/scim+json 2191 Content-Type: application/scim+json 2192 Authorization: Bearer h480djs93hd8 2193 Content-Length: ... 2195 { 2196 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 2197 "failOnErrors":1, 2198 "Operations":[ 2199 { 2200 "method":"POST", 2201 "path":"/Users", 2202 "bulkId":"qwerty", 2203 "data":{ 2204 "schemas": ["urn:ietf:params:scim:api:messages:2.0:User"], 2205 "userName":"Alice" 2206 } 2207 }, 2208 { 2209 "method":"PUT", 2210 "path":"/Users/b7c14771-226c-4d05-8860-134711653041", 2211 "version":"W\/\"3694e05e9dff591\"", 2212 "data":{ 2213 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 2214 "id":"b7c14771-226c-4d05-8860-134711653041", 2215 "userName":"Bob" 2216 } 2217 }, 2218 { 2219 "method": "PATCH", 2220 "path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2221 "version": "W/\"edac3253e2c0ef2\"", 2222 "data": {[ 2223 { 2224 "op": "remove", 2225 "path": "nickName" 2226 }, 2227 { 2228 "op": "add", 2229 "path": "userName", 2230 "value": "Dave" 2231 } 2232 ]} 2233 }, 2234 { 2235 "method":"DELETE", 2236 "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2237 "version":"W\/\"0ee8add0a938e1a\"" 2238 } 2239 ] 2240 } 2242 The service provider returns the following response. 2244 HTTP/1.1 200 OK 2245 Content-Type: application/scim+json 2247 { 2248 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2249 "Operations": [ 2250 { 2251 "location": 2252 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2253 "method": "POST", 2254 "bulkId": "qwerty", 2255 "version": "W\/\"oY4m4wn58tkVjJxK\"", 2256 "status": "201" 2257 }, 2258 { 2259 "location": 2260 "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 2261 "method": "PUT", 2262 "version": "W\/\"huJj29dMNgu3WXPD\"", 2263 "status": "200" 2264 }, 2265 { 2266 "location": 2267 "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2268 "method": "PATCH", 2269 "version": "W\/\"huJj29dMNgu3WXPD\"", 2270 "status": "200" 2271 }, 2272 { 2273 "location": 2274 "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2275 "method": "DELETE", 2276 "status": "204" 2277 } 2278 ] 2279 } 2281 The following response is returned if an error occurred when 2282 attempting to create the User 'Alice'. The service provider stops 2283 processing the bulk operation and immediately returns a response to 2284 the client. The response contains the error and any successful 2285 results prior to the error. 2287 HTTP/1.1 200 OK 2288 Content-Type: application/scim+json 2290 { 2291 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2292 "Operations": [ 2293 { 2294 "method": "POST", 2295 "bulkId": "qwerty", 2296 "status": "400", 2297 "response":{ 2298 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2299 "scimType":"invalidSyntax" 2300 "detail": 2301 "Request is unparseable, syntactically incorrect, or violates schema.", 2302 "status":"400" 2303 } 2304 } 2305 ] 2306 } 2308 If the "failOnErrors" attribute is not specified or the service 2309 provider has not reached the error limit defined by the client the 2310 service provider will continue to process all operations. The 2311 following is an example in which all operations failed. 2313 HTTP/1.1 200 OK 2314 Content-Type: application/scim+json 2316 { 2317 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2318 "Operations": [ 2319 { 2320 "method": "POST", 2321 "bulkId": "qwerty", 2322 "status": "400", 2323 "response":{ 2324 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2325 "scimType":"invalidSyntax" 2326 "detail": 2327 "Request is unparseable, syntactically incorrect, or violates schema.", 2328 "status":"400" 2329 } 2330 }, 2331 { 2332 "location": 2333 "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 2334 "method": "PUT", 2335 "status": "412", 2336 "response":{ 2337 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2338 "detail":"Failed to update. Resource changed on the server.", 2339 "status":"412" 2340 } 2341 }, 2342 { 2343 "location": 2344 "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2345 "method": "PATCH", 2346 "status": "412", 2347 "response":{ 2348 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2349 "detail":"Failed to update. Resource changed on the server.", 2350 "status":"412" 2351 } 2352 }, 2353 { 2354 "location": 2355 "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2356 "method": "DELETE", 2357 "status": "404", 2358 "response":{ 2359 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2360 "detail":"Resource does not exist.", 2361 "status":"404" 2362 } 2363 } 2364 ] 2365 } 2366 HTTP/1.1 200 OK 2367 Content-Type: application/scim+json 2369 { 2370 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2371 "Operations": [ 2372 { 2373 "location": 2374 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2375 "method": "POST", 2376 "bulkId": "qwerty", 2377 "version": "W\/\"4weymrEsh5O6cAEK\"", 2378 "status": "201" 2379 }, 2380 { 2381 "location": 2382 "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 2383 "method": "POST", 2384 "bulkId": "ytrewq", 2385 "version": "W\/\"lha5bbazU3fNvfe5\"", 2386 "status": "201" 2387 } 2388 ] 2389 } 2391 3.7.4. Maximum Operations 2393 The service provider MUST define the maximum number of operations and 2394 maximum payload size a client may send in a single request. These 2395 limits MAY be retrieved from the Service Provider Configuration (see 2396 'bulk' in Section 8 of [I-D.ietf-scim-core-schema]). If either 2397 limits are exceeded the service provider MUST return the HTTP 2398 response code 413 Request Entity Too Large. The returned response 2399 MUST specify the limit exceeded in the body of the error response. 2401 The following example the client sent a request exceeding the service 2402 provider's max payload size of 1 megabyte: 2404 POST /v2/Bulk 2405 Host: example.com 2406 Accept: application/scim+json 2407 Content-Type: application/scim+json 2408 Authorization: Bearer h480djs93hd8 2409 Content-Length: 4294967296 2411 ... 2413 In response to the over-sized request, the server responds with the 2414 following error: 2416 HTTP/1.1 413 Request Entity Too Large 2417 Content-Type: application/scim+json 2419 { 2420 "schemas":["urn:ietf:params:scim:api:messages:2.0:Error"], 2421 "status": "413", 2422 "detail": 2423 "The size of the bulk operation exceeds the maxPayloadSize (1048576)." 2424 } 2426 3.8. Data Input/Output Formats 2428 Servers MUST accept requests and respond with JSON structured 2429 responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default 2430 encoding format. 2432 Clients using other encodings MUST specify the format in which the 2433 data is submitted via HTTP header "Content-Type" as specified in 2434 Section 3.1.1.5 [RFC7231] and MAY specify the desired response data 2435 format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g., 2436 "Accept: application/scim+json" or via URI suffix; e.g., 2438 GET /Users/2819c223-7f76-453a-919d-413861904646.scim 2439 Host: example.com 2441 Service providers MUST support the accept header "Accept: 2442 application/scim+json" and SHOULD support header "Accept: 2443 application/json" both of which specify JSON documents conforming to 2444 [RFC7159]. The format defaults to "application/scim+json" if no 2445 format is specified. 2447 Singular attributes are encoded as string name-value-pairs in JSON; 2448 e.g., 2450 "attribute": "value" 2452 Multi-valued attributes in JSON are encoded as arrays; e.g., 2454 "attributes": [ "value1", "value2" ] 2456 Elements with nested elements are represented as objects in JSON; 2457 e.g, 2459 "attribute": { "subattribute1": "value1", "subattribute2": "value2" } 2461 3.9. Additional Operation Response Parameters 2463 For any SCIM operation where a resource representation is returned 2464 (e.g. HTTP GET), the attributes returned are defined as the minimum 2465 attribute set plus default attributes set. The minimum set are those 2466 attributes whose schema have "returned" set to "always". The default 2467 attribute set are those attributes whose schema have "returned" set 2468 to "default". 2470 Clients MAY request a partial resource representation on any 2471 operation that returns a resource within the response by specifying 2472 either of the mutually exclusive URL query parameters "attributes" OR 2473 "excludedAtributes" as follows: 2475 attributes When specified the default list of attributes SHALL be 2476 overridden and each resource returned MUST contain the 2477 minimum set of resource attributes and any attributes or sub- 2478 attributes explicitly requested by the "attributes" 2479 parameter. The query parameter attributes value is a comma 2480 separated list of resource attribute names in standard 2481 attribute notation (Section 3.10) form (e.g. userName, name, 2482 emails). 2484 excludedAttributes When specified, each resource returned MUST 2485 contain the minimal set of resource attributes. 2486 Additionally, the default set of attributes minus those 2487 attributes listed in "excludedAttributes" are also returned. 2488 The query parameter attributes value is a comma separated 2489 list of resource attribute names in standard attribute 2490 notation (Section 3.10) form (e.g. userName, name, emails). 2492 . 2494 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName 2495 Host: example.com 2496 Accept: application/scim+json 2497 Authorization: Bearer h480djs93hd8 2499 Giving the response 2500 HTTP/1.1 200 OK 2501 Content-Type: application/scim+json 2502 Location: 2503 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2504 ETag: W/"a330bc54f0671c9" 2506 { 2507 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2508 "id":"2819c223-7f76-453a-919d-413861904646", 2509 "userName":"bjensen", 2510 "meta":{ 2511 "resourceType": "User", 2512 "created":"2011-08-01T18:29:49.793Z", 2513 "lastModified":"2011-08-01T18:29:49.793Z", 2514 "location": 2515 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2516 "version":"W\/\"a330bc54f0671c9\"" 2517 } 2518 } 2520 3.10. Attribute Notation 2522 All operations share a common scheme for referencing simple and 2523 complex attributes. In general, attributes are identified by 2524 prefixing the attribute name with its schema URN separated by a ':' 2525 character; e.g., the core User resource attribute 'userName' is 2526 identified as "urn:ietf:params:scim:schemas:core:2.0:User:userName". 2527 Clients MAY omit core schema attribute URN prefixes though MUST fully 2528 qualify extended attributes with the associated resource URN; e.g., 2529 the attribute 'age' defined in 2530 "urn:ietf:params:scim:schemas:exampleCo:2.0:hr" is fully encoded as 2531 "urn:ietf:params:scim:schemas:exampleCo:2.0:hr:age". A Complex 2532 attributes' Sub-Attributes are referenced via nested, dot ('.') 2533 notation; i.e., {urn}:{Attribute name}.{Sub-Attribute name}. For 2534 example, the fully qualified path for a User's givenName is 2535 "urn:ietf:params:scim:schemas:core:2.0:User:name.givenName" All 2536 facets (URN, attribute and Sub-Attribute name) of the fully encoded 2537 Attribute name are case insensitive. 2539 3.11. "/Me" Authenticated Subject Alias 2541 A client MAY use a URL of the form "/Me" as a URI alias for 2542 the User or other resource associated with the currently 2543 authenticated subject for any SCIM operation. A service provider MAY 2544 respond in ONE of 3 ways: 2546 o A service provider that does NOT support this feature SHOULD 2547 respond with status 403 (FORBIDDEN). 2549 o A service provider MAY choose to redirect the client using HTTP 2550 status 308 to the resource associated with the authenticated 2551 subject. The client MAY then repeat the request at the indicated 2552 location. 2554 o A service provider MAY process the SCIM request directly. In any 2555 response, the HTTP "Location" header MUST be the permanent 2556 location of the aliased resource associated with the authenticated 2557 subject. 2559 When using the SCIM Create Resource command (HTTP POST) with the 2560 "/Me" alias, the desired resourceType being created is at the 2561 discretion of the service provider based on the authenticated subject 2562 (if not anonymous) making the request and any request body attributes 2563 (e.g. "schemas"). See Section 7.3 for information on security 2564 considerations related to this operation. 2566 3.12. HTTP Status and Error Response Handling 2568 The SCIM Protocol uses the HTTP status response status codes defined 2569 in Section 6 [RFC7231] to indicate operation success or failure. In 2570 addition to returning a HTTP response code implementers MUST return 2571 the errors in the body of the response in the client requested format 2572 containing the error response and, per the HTTP specification, human- 2573 readable explanations. Error responses are identified using the 2574 following "schema" URI: 2575 "urn:ietf:params:scim:api:messages:2.0:Error". The following 2576 attributes are defined for a SCIM error response using a JSON body: 2578 status 2579 The HTTP status code (see Section 6 [RFC7231]). REQUIRED 2581 scimType 2582 A SCIM detailed error keyword. See Table 8. OPTIONAL 2584 detail 2585 A detailed, human readable message. OPTIONAL 2587 Implementers SHOULD handle the identified HTTP status codes as 2588 described below. 2590 +--------------+---------------+------------------------------------+ 2591 | Status | Applicability | Suggested Explanation | 2592 +--------------+---------------+------------------------------------+ 2593 | 307 | GET, POST, | The client is directed to repeat | 2594 | TEMPORARY | PUT, PATCH, | the same HTTP request at the | 2595 | REDIRECT | DELETE | location identified. The client | 2596 | | | SHOULD NOT use the location | 2597 | | | provided in the response as a | 2598 | | | permanent reference to the | 2599 | | | resource and SHOULD continue to | 2600 | | | use the original request URI | 2601 | | | [RFC7231]. | 2602 | 308 | GET, POST, | The client is directed to repeat | 2603 | PERMANENT | PUT, PATCH, | the same HTTP request at the | 2604 | REDIRECT | DELETE | location identified. The client | 2605 | | | SHOULD use the location provided | 2606 | | | in the response as the permanent | 2607 | | | reference to the resource | 2608 | | | [RFC7238]. | 2609 | 400 BAD | GET, POST, | Request is unparseable, | 2610 | REQUEST | PUT, PATCH, | syntactically incorrect, or | 2611 | | DELETE | violates schema | 2612 | 401 | GET, POST, | Authorization failure | 2613 | UNAUTHORIZED | PUT, PATCH, | | 2614 | | DELETE | | 2615 | 403 | GET, POST, | Server does not support requested | 2616 | FORBIDDEN | PUT, PATCH, | operation | 2617 | | DELETE | | 2618 | 404 NOT | GET, POST, | Specified resource (e.g., User) or | 2619 | FOUND | PUT, PATCH, | end-point, does not exist | 2620 | | DELETE | | 2621 | 409 CONFLICT | POST, PUT, | The specified version number does | 2622 | | PATCH, DELETE | not match the resource's latest | 2623 | | | version number or a service | 2624 | | | provider refused to create a new, | 2625 | | | duplicate resource | 2626 | 412 | PUT, PATCH,D | Failed to update as resource {id} | 2627 | PRECONDITION | ELETE | changed on the server last | 2628 | FAILED | | retrieved | 2629 | 413 REQUEST | POST | {"maxOperations": | 2630 | ENTITY TOO | | 1000,"maxPayload": 1048576} | 2631 | LARGE | | | 2632 | 500 INTERNAL | GET, POST, | An internal error. Implementers | 2633 | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive | 2634 | | DELETE | debugging advice | 2635 | 501 NOT | GET, POST, | Service Provider does not support | 2636 | IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH | 2637 | | DELETE | | 2638 +--------------+---------------+------------------------------------+ 2640 Table 7: SCIM HTTP Status Code Usage 2642 For HTTP Status 400 (Bad Request) responses, the following detail 2643 error types are defined: 2645 +--------------+------------------------------+---------------------+ 2646 | scimType | Description | Applicability | 2647 +--------------+------------------------------+---------------------+ 2648 | invalidFilte | The specified filter syntax | GET(Section 3.4.2), | 2649 | r | was invalid (does not comply | POST (Search - | 2650 | | with Figure 1) or the | Section 3.4.3), | 2651 | | specified attribute and | PATCH (Path Filter | 2652 | | filter comparison | - Section 3.5.2) | 2653 | | combination is not | | 2654 | | supported. | | 2655 | tooMany | The specified filter yields | GET(Section 3.4.2), | 2656 | | many more results than the | POST (Search - | 2657 | | server is willing calculate | Section 3.4.3) | 2658 | | or process. For example, a | | 2659 | | filter such as "(userName | | 2660 | | pr)" by itself would return | | 2661 | | all entries with a | | 2662 | | "userName" and MAY not be | | 2663 | | acceptable to the service | | 2664 | | provider. | | 2665 | uniqueness | One or more of attribute | POST (Create - | 2666 | | values is already in use or | Section 3.3), PUT | 2667 | | is reserved. | (Section 3.5.1), | 2668 | | | PATCH (Section | 2669 | | | 3.5.2) | 2670 | mutability | The attempted modification | PUT (Section | 2671 | | is not compatible with the | 3.5.1), PATCH | 2672 | | target attributes mutability | (Section 3.5.2) | 2673 | | or current state (e.g. | | 2674 | | modification of an immutable | | 2675 | | attribute with an existing | | 2676 | | value). | | 2677 | invalidSynta | The request body message | POST (Search - | 2678 | x | structure was invalid or did | Section 3.4.2, | 2679 | | not conform to the request | Create - Section | 2680 | | schema. | 3.3, Bulk - Section | 2681 | | | 3.7), PUT (Section | 2682 | | | 3.5.1) | 2683 | invalidPath | The path attribute was | PATCH (Section | 2684 | | invalid or malformed (see | 3.5.2) | 2685 | | Figure 7). | | 2686 | noTarget | The specified "path" did not | PATCH (Section | 2687 | | yield an attribute or | 3.5.2) | 2688 | | attribute value that could | | 2689 | | be operated on. This occurs | | 2690 | | when the specified "path" | | 2691 | | value contains a filter that | | 2692 | | yields no match. | | 2693 | invalidValue | A required value was | GET (Section | 2694 | | missing, or the value | 3.4.2), POST | 2695 | | specified was not compatible | (Create - Section | 2696 | | with the operation or | 3.3, Query - | 2697 | | attribute type (see Section | Section 3.4.2), PUT | 2698 | | 2.1 [I-D.ietf-scim-core-sche | (Section 3.5.1), | 2699 | | ma]), or schema (see Section | PATCH (Section | 2700 | | 4 [I-D.ietf-scim-core-schema | 3.5.2) | 2701 | | ]). | | 2702 | invalidVers | The specified SCIM protocol | GET (Section | 2703 | | version is not supported | 3.4.2), POST (ALL), | 2704 | | (see Section 3.13). | PUT (Section | 2705 | | | 3.5.1), PATCH | 2706 | | | (Section 3.5.2), | 2707 | | | DELETE (Section | 2708 | | | 3.6) | 2709 +--------------+------------------------------+---------------------+ 2711 Table 8: Table of SCIM Detail Error Keyword Values 2713 Note that in the table above (Table 8), the applicability table 2714 applies to the normal HTTP method but MAY apply within a SCIM Bulk 2715 operation (via HTTP POST). 2717 Error example in response to a non-existent GET request. 2719 HTTP/1.1 404 NOT FOUND 2721 { 2722 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2723 "detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 2724 "status":"404 2725 } 2727 Error example in response to a PUT request. 2729 HTTP/1.1 400 BAD REQUEST 2731 { 2732 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2733 "scimType":"mutability" 2734 "detail":"Attribute 'id' is readOnly", 2735 "status":"400" 2736 } 2738 [[Editor's note: while the detail error codes seem to have consensus, 2739 there is a question about whether the error codes should be 2740 extensible so that individual service providers may define site 2741 specific codes. Should all scimTypes be URIs, so that scimTypes can 2742 be registered via IANA? Should there be a separate field defined for 2743 this purpose? Or, should custom signalling (for non-protocol/schema 2744 errors, be out of scope?]] 2746 3.13. API Versioning 2748 The Base URL MAY be appended with a version identifier as a separate 2749 segment in the URL path. At this time of this specification, the 2750 identifier is 'v2'. If specified, the version identifier MUST appear 2751 in the URL path immediately preceding the resource endpoint and 2752 conform to the following scheme: the character 'v' followed by the 2753 desired SCIM version number; e.g., a version 'v2' User request is 2754 specified as /v2/Users. When specified service providers MUST 2755 perform the operation using the desired version or reject the 2756 request. When omitted service providers SHOULD perform the operation 2757 using the most recent SCIM protocol version supported by the service 2758 provider. 2760 3.14. Versioning Resources 2762 The SCIM protocol supports resource versioning via standard HTTP 2763 ETags Section 2.3 [RFC7233]. Service providers MAY support weak 2764 ETags as the preferred mechanism for performing conditional 2765 retrievals and ensuring clients do not inadvertently overwrite each 2766 others changes, respectively. When supported SCIM ETags MUST be 2767 specified as an HTTP header and SHOULD be specified within the 2768 'version' attribute contained in the resource's 'meta' attribute. 2770 Example: 2772 POST /Users HTTP/1.1 2773 Host: example.com 2774 Content-Type: application/scim+json 2775 Authorization: Bearer h480djs93hd8 2776 Content-Length: ... 2778 { 2779 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2780 "userName":"bjensen", 2781 "externalId":"bjensen", 2782 "name":{ 2783 "formatted":"Ms. Barbara J Jensen III", 2784 "familyName":"Jensen", 2785 "givenName":"Barbara" 2786 } 2787 } 2789 The server responds with an ETag in the response header and meta 2790 structure. 2792 HTTP/1.1 201 Created 2793 Content-Type: application/scim+json 2794 Location: 2795 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2796 ETag: W/"e180ee84f0671b1" 2798 { 2799 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2800 "id":"2819c223-7f76-453a-919d-413861904646", 2801 "meta":{ 2802 "resourceType":"User", 2803 "created":"2011-08-01T21:32:44.882Z", 2804 "lastModified":"2011-08-01T21:32:44.882Z", 2805 "location": 2806 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2807 "version":"W\/\"e180ee84f0671b1\"" 2808 }, 2809 "name":{ 2810 "formatted":"Ms. Barbara J Jensen III", 2811 "familyName":"Jensen", 2812 "givenName":"Barbara" 2813 }, 2814 "userName":"bjensen" 2815 } 2817 With the returned ETag, clients MAY choose to retrieve the resource 2818 only if the resource has been modified. 2820 Conditional retrieval example using If-None-Match Section 3.2 2821 [RFC7233] header: 2823 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName 2824 Host: example.com 2825 Accept: application/scim+json 2826 Authorization: Bearer h480djs93hd8 2827 If-None-Match: W/"e180ee84f0671b1" 2829 If the resource has not changed the service provider simply returns 2830 an empty body with a 304 "Not Modified" response code. 2832 If the service providers supports versioning of resources the client 2833 MAY supply an If-Match Section 3.1 [RFC7233] header for PUT and PATCH 2834 operations to ensure that the requested operation succeeds only if 2835 the supplied ETag matches the latest service provider resource; e.g., 2836 If-Match: W/"e180ee84f0671b1" 2838 4. Service Provider Configuration Endpoints 2840 SCIM 2 defines 3 endpoints to facilitate discovery of SCIM service 2841 provider features and schema that MAY be retrieved using HTTP GET: 2843 /ServiceProviderConfig 2844 An HTTP GET to this endpoint will return a JSON structure that 2845 describes the SCIM specification features available on a service 2846 provider. This endpoint SHALL return responses with a JSON object 2847 using a "schemas" attribute of 2848 "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig". 2849 The attributes returned in the JSON object are defined in 2850 Section 5 [I-D.ietf-scim-core-schema]. An example representation 2851 of SCIM Service Provider configuration may be found in Section 8.5 2852 [I-D.ietf-scim-core-schema]. 2854 /Schemas 2855 An HTTP GET to this endpoint is used to retrieve information about 2856 resource schemas supported by a SCIM Service Provider. An HTTP 2857 GET to the endpoint "/Schemas" SHALL return all supported schemas 2858 in ListResponse format (see Figure 3). Individual schema 2859 definitions can be returned by appending the schema URI to the 2860 schemas endpoint. For example: 2862 /Schemas/urn:ietf:params:scim:schemas:core:2.0:User 2864 The contents of each schema returned is described in Section 7 2865 [I-D.ietf-scim-core-schema]. An example representation of SCIM 2866 schemas may be found in Section 8.7 [I-D.ietf-scim-core-schema]. 2868 /ResourceTypes 2869 An HTTP GET to this endpoint is used to discover the types of 2870 resources available on a SCIM Service Provider (e.g. Users and 2871 Groups). Each resource type defines the endpoints, the core 2872 schema URI that defines the resource, and any supported schema 2873 extensions. The attributes defining a resource type can be found 2874 in Section 6 [I-D.ietf-scim-core-schema], and an example 2875 representation can be found in Section 8.6 2876 [I-D.ietf-scim-core-schema]. 2878 In cases where a request is for a specific "ResourceType" or 2879 "Schema", the single JSON object is returned in the same way a single 2880 User or Group is retrieved as per Section 3.4.1. When returning 2881 multiple ResourceTypes or Schemas, the message form described by 2882 "urn:ietf:params:scim:api:messages:2.0:ListResponse" (ListResponse) 2883 form SHALL be used as shown in Figure 3 and Figure 9 below. Query 2884 parameters described in section 3.2 such as, sorting, attributes, and 2885 paging SHALL be ignored. If a "filter" is provided, the service 2886 provider SHOULD respond with HTTP Status 403 (FORBIDDEN) to ensure 2887 clients cannot incorrectly assume any matching conditions specified 2888 in a filter are true. 2890 The following is a non-normative example of an HTTP GET to the 2891 /ResourceTypes endpoint: 2893 { 2894 "totalResults":2, 2895 "itemsPerPage":10, 2896 "startIndex":1, 2897 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 2898 "Resources":[{ 2899 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"], 2900 "id":"User", 2901 "name":"User", 2902 "endpoint": "/Users", 2903 "description": "User Account", 2904 "schema": "urn:ietf:params:scim:schemas:core:2.0:User", 2905 "schemaExtensions": [{ 2906 "schema": 2907 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", 2908 "required": true 2909 }], 2910 "meta": { 2911 "location":"https://example.com/v2/ResourceTypes/User", 2912 "resourceType": "ResourceType" 2913 } 2914 }, 2915 { 2916 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"], 2917 "id":"Group", 2918 "name":"Group", 2919 "endpoint": "/Groups", 2920 "description": "Group", 2921 "schema": "urn:ietf:params:scim:schemas:core:2.0:Group", 2922 "meta": { 2923 "location":"https://example.com/v2/ResourceTypes/Group", 2924 "resourceType": "ResourceType" 2925 } 2926 }] 2927 } 2929 Figure 9: Example Resource Type JSON Representation 2931 5. Preparation and Comparison of Internationalized Strings 2933 To increase the likelihood that the input and comparison of unicode 2934 usernames and passwords will work in ways that make sense for typical 2935 users throughout the world there are special string preparation and 2936 comparison methods (PRECIS) that MUST be followed for usernames and 2937 passwords. Before comparing or evaluating uniqueness of a "userName" 2938 or "password" attribute, service providers MUST use the "PRECIS" 2939 profile described in Sections 4 and 5 respectively of 2940 [I-D.ietf-precis-saslprepbis] and is based on the "PRECIS" framework 2941 specification [I-D.ietf-precis-framework]. 2943 6. Multi-Tenancy 2945 A single service provider may expose the SCIM protocol to multiple 2946 clients. Depending on the nature of the service, the clients may 2947 have authority to access and alter resources initially created by 2948 other clients. Alternatively, clients may expect to access disjoint 2949 sets of resources, and may expect that their resources are 2950 inaccessible by other clients. These scenarios are called "multi- 2951 tenancy", where each client is understood to be or represent a 2952 "tenant" of the service provider. Clients may also be multi- 2953 tenanted. 2955 The following common cases may occur: 2957 1. All clients share all resources (no tenancy) 2959 2. Each single client creates and accesses a private subset of 2960 resources (1 client:1 Tenant) 2962 3. Sets of clients share sets of resources (M clients:1 Tenant) 2964 4. One client to Multiple Tenants (1 client:M Tenants) 2966 Service providers may implement any subset of the above cases. 2968 Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a 2969 scheme for multi-tenancy. 2971 The SCIM protocol does not prescribe the mechanisms whereby clients 2972 and service providers interact for: 2974 o Registering or provisioning Tenants 2976 o Associating a subset of clients with a subset of the Tenants 2978 o Indicating which tenant is associated with the data in a request 2979 or response, or indicating which Tenant is the subject of a query 2981 6.1. Associating Clients to Tenants 2983 The service provider MAY use the authentication mechanism (Section 2) 2984 to determine the identity of the client, and thus infer the 2985 associated Tenant. 2987 For implementations where a client is associated with more than one 2988 Tenant, the service provider MAY use one of the following methods for 2989 explicit specification of the Tenant. 2991 If any of these methods of allowing the client to explicitly specify 2992 the Tenant are employed, the service provider should ensure that 2993 access controls are in place to prevent or allow cross-tenant use 2994 cases. 2996 The service provider should consider precedence in cases where a 2997 client may explicitly specify a Tenant while being implicitly 2998 associated with a different Tenant. 3000 In all of these methods, the {tenant_id} is a unique identifier for 3001 the Tenant as defined by the service provider. 3003 o A URL prefix: "https://www.example.com/Tenants/{tenant_id}/v2/ 3004 Users" 3006 o A sub-domain: "https://{tenant_id}.example.com/v2/Groups" 3008 o The service provider may recognize a {tenant_id} provided by the 3009 client in an HTTP Header as the indicator of the desired target 3010 Tenant. 3012 6.2. SCIM Identifiers with Multiple Tenants 3014 Considerations for a Multi-Tenant Implementation: 3016 The service provider may choose to implement SCIM ids which are 3017 unique across all resources for all Tenants, but this is not 3018 required. 3020 The externalId, defined by the client, is required to be unique ONLY 3021 within the resources associated with the associated Tenant. 3023 7. Security Considerations 3025 7.1. TLS Support 3027 The SCIM Protocol layers on top of Hypertext Transfer Protocol and 3028 thus subject to the security considerations of HTTP Section 9 3029 [RFC7230] and its related specifications. 3031 SCIM resources (e.g., Users and Groups) can contain sensitive 3032 information. Therefore, SCIM clients and service providers MUST 3033 implement TLS. Which version(s) ought to be implemented will vary 3034 over time, and depend on the widespread deployment and known security 3035 vulnerabilities at the time of implementation. At the time of this 3036 writing, TLS version 1.2 [RFC5246] is the most recent version, but 3037 has very limited actual deployment, and might not be readily 3038 available in implementation toolkits. TLS version 1.0 [RFC5246] is 3039 the most widely deployed version, and will give the broadest 3040 interoperability. 3042 7.2. Disclosure of Sensitive Information in URIs 3044 As mentioned in ,Section 9.4 [RFC7231], SCIM clients requesting 3045 information using query filters using HTTP GET SHOULD give 3046 consideration to the information content of the filters and whether 3047 their exposure in a URI would represent a breach of security or 3048 confidentiality through leakage in a web browsers or server logs. 3049 This is particularly true for information that is legally considered 3050 "personally identifiable information" or is otherwise restricted by 3051 privacy laws. In these situations to ensure maximum security and 3052 confidentiality, clients SHOULD query using HTTP POST (see 3053 Section 3.4.3 ). 3055 Servers that receive HTTP GET requests using filters that contain 3056 restricted or confidential information SHOULD respond with HTTP 3057 status 403 indicating the operation is FORBIDDEN. A detailed error, 3058 "confidential_restricted" may be returned indicating the request must 3059 be submitted using POST. A non-normative example: 3061 HTTP/1.1 403 FORBIDDEN 3063 { 3064 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 3065 "Errors":[ 3066 { 3067 "description": 3068 "Query filter involving 'name' is restricted or confidential", 3069 "error":"confidential_restricted" 3070 } 3071 ] 3072 } 3074 7.3. Anonymous Requests 3076 If a SCIM service provider accepts anonymous requests such as SCIM 3077 resource creation requests (via HTTP POST), appropriate security 3078 measures should be put in place to prevent or limit exposure to 3079 attacks. The following counter-measures MAY be used: 3081 o Try to authenticate web UI components that forumulate the SCIM 3082 creation request. While the end-user MAY be anonymous, the web 3083 user interface component often has its own way to authenticate to 3084 the SCIM service provider (e.g. has an OAuth Client Credential 3085 [RFC6749]) and the web user interface component may implement its 3086 own measures (e.g. such as CAPTCHA) to ensure a ligitimate request 3087 is being made. 3089 o Limit the number of requests any particular client MAY make in a 3090 period of time. 3092 o For User resources, default newly created resource with an 3093 "active" setting of "false" and use a secondary confirmation 3094 process (e.g. email confirmation) to ensure the resource created 3095 is real. 3097 7.4. HTTP Considerations 3099 As an HTTP based protocol, implementers of SCIM SHOULD consider all 3100 security considerations of the HTTP/1.1 as enumerated in Section 1 3101 [RFC7230] 3103 As stated in Section 2.7.1 [RFC7230], a SCIM client MUST NOT generate 3104 the userinfo (i.e. username and password) component (and its "@" 3105 delimiter) when an "http" URI reference is generated with a message 3106 as they are now disallowed in HTTP. 3108 7.5. Secure Storage and Handling of Sensitive Data 3110 An attacker may obtain valid username/password combinations from the 3111 SCIM service provider's underlying database by gaining access to the 3112 database and/or launching injection attacks. This could lead to 3113 unintended disclosure of username/password combinations. The impact 3114 may extend beyond the domain of the SCIM service provider if the data 3115 was provisioned from other domains. 3117 Administrators should undertake industry best practices to protect 3118 the storage of credentials and in particular SHOULD follow 3119 recommendations outlines in Section 5.1.4.1 [RFC6819]. These 3120 recommendations include but are not limited to: 3122 o Provide injection attack counter measures (e.g. by validating all 3123 inputs and parameters), 3125 o No cleartext storage of credentials, 3127 o Store credentials using an encrypted protection mechanism, and 3128 o Avoid passwords and consider use of asymmetric cryptography based 3129 credentials. 3131 As outlined in Section 5.1.4.2 [RFC6819], adminitrators SHOULD take 3132 counter measures to prevent online attacks on secrets such as: 3134 o Utilize secure password policy in order to increase user password 3135 entrophy to hinder online attacks and password guessing, 3137 o Mitigate attacks on passwords by locking respective accounts have 3138 a number of failed attempts, 3140 o Use "tar pit" techniques by temporarily locking a respective 3141 account and delaying responses for a certain duration. The 3142 duration may increase with the number of failed attempts, and 3144 o Use authentication system that use CAPTCHA's and other factors for 3145 authenticating users further reducing the possibility of automated 3146 attacks. 3148 7.6. Case Insensitive Comparision & International Languages 3150 When comparing unicode strings such as in query filters or testing 3151 for uniqueness of usernames and passwords, strings MUST be 3152 appopriately prepared before comparison. See Section 5. 3154 8. IANA Considerations 3156 8.1. Media Type Registration 3158 To: ietf-types@iana.org 3160 Subject: Registration of media type application/scim+json 3162 Type name: application 3164 Subtype name: scim+json 3166 Required parameters: none 3168 Optional parameters: none 3170 Encoding considerations: 8bit 3172 Security considerations: See Section 7 3174 Interoperability considerations: The "application/scim+json" media 3175 type is intended to identify JSON structure data that conforms to 3176 the SCIM protocol and schema specifications. Older versions of 3177 SCIM are known to informally use "application/json". 3179 Published specification: [[this document]] 3181 Applications that use this media type: It is expected that 3182 applications that use this type may be special purpose 3183 applications intended for inter-domain provisioning. Clients may 3184 also be applications (e.g. mobile applications) that need to use 3185 SCIM for self-registration of user accounts. SCIM services may be 3186 offered by web applications that offer support for standards based 3187 provisioning or may be a dedicated SCIM service provider such as a 3188 "cloud directory". Content may be treated as equivalent to 3189 "application/json" type for the purpose of displaying in web 3190 browsers. 3192 Additional information: 3194 Magic number(s): 3196 File extension(s): .scim .scm 3198 Macintosh file type code(s): 3200 Person & email address to contact for futher information: SCIM 3201 mailing list "" 3203 Intended usage: COMMON* (see restrictions) 3205 Restrictions on usage: For most client types, it is sufficient to 3206 recognize the content as equivalent to "application/json". 3207 Applications intending to use SCIM protocol SHOULD use the 3208 application/scim+json media type. 3210 Author: Phil Hunt 3212 Change controller: IETF 3214 8.2. SCIM Message URI Registry 3216 As per the IANA SCIM Schema Registry in [I-D.ietf-scim-core-schema], 3217 the following registers and extends the SCIM Schema Registry to 3218 define SCIM protocol request/response JSON schema URN identifier 3219 prefix of "urn:ietf:params:scim:api:messages:2.0" which is part of 3220 the URN sub-Namespace for SCIM. There is no specific associated 3221 resource type. 3223 +---------------------------------+-----------------+---------------+ 3224 | Schema URI | Name | Reference | 3225 +---------------------------------+-----------------+---------------+ 3226 | urn:ietf:params:scim:api: | List/Query | See Section | 3227 | messages:2.0:ListResponse | Response | 3.4.2 | 3228 | urn:ietf:params:scim:api: | POST Query | See Section | 3229 | messages:2.0:SearchRequest | Request | 3.4.3 | 3230 | urn:ietf:params:scim:api: | Patch Operation | See Section | 3231 | messages:2.0:PatchOp | | 3.5.2 | 3232 | urn:ietf:params:scim:api: | Bulk Operations | See Section | 3233 | messages:2.0:BulkRequest | Request | 3.7 | 3234 | urn:ietf:params:scim:api: | Bulk Operations | See Section | 3235 | messages:2.0:BulkResponse | Response | 3.7 | 3236 | urn:ietf:params:scim:api: | Error Response | See Section | 3237 | messages:2.0:Error | | 3.12 | 3238 +---------------------------------+-----------------+---------------+ 3240 Table 9: SCIM Schema URIs for Data Resources 3242 9. References 3244 9.1. Normative References 3246 [I-D.ietf-precis-saslprepbis] 3247 Saint-Andre, P. and A. Melnikov, "Preparation, 3248 Enforcement, and Comparison of Internationalized Strings 3249 Representing Usernames and Passwords", draft-ietf-precis- 3250 saslprepbis-14 (work in progress), March 2015. 3252 [I-D.ietf-scim-core-schema] 3253 Hunt, P., Grizzle, K., Wahlstroem, E., and C. Mortimore, 3254 "System for Cross-Domain Identity Management: Core 3255 Schema", draft-ietf-scim-core-schema-17 (work in 3256 progress), March 2015. 3258 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3259 Requirement Levels", BCP 14, RFC 2119, March 1997. 3261 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3262 10646", STD 63, RFC 3629, November 2003. 3264 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3265 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3266 3986, January 2005. 3268 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 3269 Specifications: ABNF", STD 68, RFC 5234, January 2008. 3271 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3272 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3274 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 3275 5789, March 2010. 3277 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 3278 Interchange Format", RFC 7159, March 2014. 3280 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3281 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 3282 2014. 3284 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3285 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 3287 [RFC7233] Fielding, R., Lafon, Y., and J. Reschke, "Hypertext 3288 Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, 3289 June 2014. 3291 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3292 (HTTP/1.1): Authentication", RFC 7235, June 2014. 3294 9.2. Informative References 3296 [I-D.ietf-precis-framework] 3297 Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 3298 Preparation, Enforcement, and Comparison of 3299 Internationalized Strings in Application Protocols", 3300 draft-ietf-precis-framework-23 (work in progress), 3301 February 2015. 3303 [OpenSearch] 3304 Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . 3306 [Order-Operations] 3307 Wikipedia, "Order of Operations: Programming Languages", . 3309 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 3310 6749, October 2012. 3312 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 3313 Framework: Bearer Token Usage", RFC 6750, October 2012. 3315 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 3316 Threat Model and Security Considerations", RFC 6819, 3317 January 2013. 3319 [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation 3320 (JSON) Patch", RFC 6902, April 2013. 3322 [RFC7238] Reschke, J., "The Hypertext Transfer Protocol Status Code 3323 308 (Permanent Redirect)", RFC 7238, June 2014. 3325 [XML-Schema] 3326 Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes 3327 Second Edition", October 2004. 3329 Appendix A. Contributors 3331 Samuel Erdtman (samuel@erdtman.se) 3333 Patrick Harding (pharding@pingidentity.com) 3335 Appendix B. Acknowledgments 3337 The editors would like to acknowledge the contribution and work of 3338 the past draft editors: 3340 Trey Drake, UnboundID 3342 Chuck Mortimore, Salesforce 3344 The editor would like to thank the participants in the the SCIM 3345 working group for their support of this specification. 3347 Appendix C. Change Log 3349 [[This section to be removed prior to publication as an RFC]] 3351 Draft 02 - KG - Addition of schema extensibility 3353 Draft 03 - PH - Revisions based on following tickets: 3355 24 - Add filter negation 3357 39 - Clarification on response for DELETE 3359 42 - Make root searches optional 3361 49 - Add "ew" filter 3363 50 - Filters for multi-valued complex attributes 3365 51 - Search by Schema 3366 53 - Standard use of term client (some was consumer) 3368 55 - Redirect support (3xx) 3370 56 - Make manager attribute consistent with other $ref attrs 3372 57 - Update all "/v1" examples to '/v2" 3374 59 - Fix capitalization per IETF editor practices 3376 60 - Changed tags to normal and tags 3378 Draft 04 - PH - Revisions based on the following tickets: 3380 18 - New PATCH command based on JSON Patch (RFC6902) 3382 - Provided ABNF specification for filters (used in PATCH) 3384 - Updated references to RFC4627 to RFC7159 3386 Draft 05 - PH - Revisions based on the following tickets: 3388 03 - Support for excludedAttributes parameter 3390 13 - Change client use of Etags from MUST to MAY (correction) 3392 23 - Clarifications regarding case exact processing. 3394 41 - Add IANA considerations 3396 65 - Removed X-HTTP-Method-Override support 3398 69 - Added clarifications to intro to align with draft-nottingham- 3399 uri-get-off-my-lawn 3401 70 - Remove SCIM_TENANT_ID header 3403 72 - Added text to indicate UTF-8 is default and mandatory 3404 encoding format per BCP18 3406 74 - Added security considerations for using GET with confidential 3407 attribute filters 3409 - corrected error response in JSON PATCH operation 3411 Draft 06 - PH - Revisions based on the following tickets and 3412 editorial changes 3413 41 - Revised content types from application/json to application/ 3414 scim+json, registered API schemas 3416 63 - Revised uri schema prefixes for API json message schemas 3418 66 - Updated references for RFC2616 to HTTPbis 3420 75 - Added security considerations for International Strings and 3421 "PRECIS" support 3423 76 - Clarified handling of PUT (& POST) with regards to mutability 3424 and default values 3426 - Corrected version numbers in sec 3.11 API Versioning to v2 (from 3427 v1) 3429 - Clarified that no filter matches should return success 3430 totalResults=0 3432 Draft 07 - PH - Revisions regarding support of detailed errors 3433 (Tickets 37, 46, 67) 3435 Draft 08 - PH - Revisions as follows 3437 - Added clarification on schemas handling during PATCH operation 3439 - Revised example URN in Attribute Notation section to comply with 3440 IANA namespace rules 3442 - Fixed typo in ABNF, attrExpr should be attrExp 3444 - Added more security considerations for HTTP and sensitive data 3446 - Revised authentication and authorization sections for greater 3447 clarity. 3449 - Replaced the word "search" with "query" for consistency 3451 - Clarified sucessful resource creation response 3453 - Added clarification on primary value handling in PATCH 3454 (consistent with draft 03) 3456 - Revised SCIM Bullk error handling to conform with draft 07 error 3457 handling 3459 Draft 09 - PH - Revisions as follows 3460 - Aligned API with new URN namespace per RFC3553 and IETF90 3461 meeting 3463 - Clarified URN usage within patch (what schema urn applies) 3465 - Made 'path' optional in PATCH for Add and Replace 3467 Draft 10 - PH - Revisions as follows 3469 Restructuring of Bulk into sub-sections 3471 General clarifications 3473 Improved Base URI section 3475 Authorization section clarifications 3477 Draft 11 - PH - Revisions as follows 3479 Made mutability processing rules for CREATE more editorially 3480 obvious 3482 Added clarfications and security considerations for Anonymous 3483 operations 3485 Added clarifications to "/Me" for POST requests 3487 Clarified use of bulkids with multiple requests 3489 Corrected JSON parsing issue by adding "Operations" attribute to 3490 PATCH operation 3492 Draft 12 - PH - Editorial NITs 3494 Fix line lengths in artwork to be 72 chars or less 3496 Remove unused references 3498 Fix normative terms per RFC2119 3500 Updated reference to draft-reschke-http-status-308 to RFC7238 3502 Draft 13 - PH - Added clarification to error response for improperly 3503 formated email/phonenumbers 3505 Draft 14 - PH - Nits and clarifications 3506 Added new Service Provider Discovery section that clarifies use of 3507 ResourceTypes, Schemas, and ServiceProviderConfigs 3509 As Complex attributes cannot support sub-attributes that are 3510 complex, the filter ABNF was corrected to prevent nested 3511 valueFilters (which presumes support for nested Complex 3512 Attributes) 3514 Corrections to ABNF: Added missing space (SP) values to logicExp 3515 ABNF rule. Corrected "not(" to make "not" optional. 3517 Added additional filter example showing full path with schema URI 3518 (to disambiguate duplicate names between schemas) 3520 Missing POST verb added to HTTP errors (table 7) since a POST 3521 endpoint might be undefined or NOT FOUND. 3523 Corrected JSON example in sec 3.3.2.1 (removed extraneous " ) 3525 Corrected filter in Figure 3 so that multiple resoruce types can 3526 be returned per the response example in figure 4. 3528 Clarifications and improvements to examples in PATCH replace 3529 operations 3531 Updated references to saslprep and precis frameworks 3533 Draft 15 - PH - Clarifications on returning "path" handling during 3534 PATCH "replace" operations. Updated references. 3536 Draft 16 - PH - Clarification of SCIM protocol definitions of 3537 resources vs messages and general process rules regarding schema 3538 including validation. 3540 Authors' Addresses 3542 Phil Hunt (editor) 3543 Oracle Corporation 3545 Email: phil.hunt@yahoo.com 3547 Kelly Grizzle 3548 SailPoint 3550 Email: kelly.grizzle@sailpoint.com 3551 Morteza Ansari 3552 Cisco 3554 Email: morteza.ansari@cisco.com 3556 Erik Wahlstroem 3557 Technology Nexus 3559 Email: erik.wahlstrom@nexusgroup.com 3561 Chuck Mortimore 3562 Salesforce.com 3564 Email: cmortimore@salesforce.com