idnits 2.17.1 draft-ietf-scim-api-06.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 36 instances of too long lines in the document, the longest one being 28 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: +------------+-------------------+----------------------------------+ | Parameter | Description | Default | +------------+-------------------+----------------------------------+ | startIndex | The 1-based index | 1 | | | of the first | | | | search result. | | | count | Non-negative | None. When specified the service | | | Integer. | provider MUST not return more | | | Specifies the | results than specified though | | | desired maximum | MAY return fewer results. If | | | number of search | unspecified, the maximum number | | | results per page; | of results is set by the service | | | e.g., 10. | provider. | +------------+-------------------+----------------------------------+ == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: Each operation against an attribute MUST be compatible with the attribute's mutability and schema as defined in the Attribute Types Section of [I-D.ietf-scim-core-schema]. For example, a client MAY NOT modify an attribute that has mutability "readOnly" or "immutable". However, a client MAY "add" a value to an "immutable" attribute if the attribute had no previous value. An operation that is not compatibile with an attribute's mutability or schema SHALL return an error as indicated below. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Clients request resource removal via DELETE. Service providers MAY choose not to permanently delete the resource, but MUST return a 404 error code for all operations associated with the previously deleted Id. Service providers MUST also omit the resource from future query results. In addition the service provider MUST not consider the deleted resource in conflict calculation. For example if a User resource is deleted, a CREATE request for a User resource with the same userName as the previously deleted resource should not fail with a 409 error due to userName conflict. -- The document date (June 23, 2014) is 3588 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC2616' is defined on line 2643, but no explicit reference was found in the text == Unused Reference: 'RFC3454' is defined on line 2647, but no explicit reference was found in the text == Unused Reference: 'RFC2277' is defined on line 2706, but no explicit reference was found in the text == Outdated reference: A later version (-18) exists of draft-ietf-precis-saslprepbis-07 == Outdated reference: A later version (-22) exists of draft-ietf-scim-core-schema-05 ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 3454 (Obsoleted by RFC 7564) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7233 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) == Outdated reference: A later version (-23) exists of draft-ietf-precis-framework-17 Summary: 10 errors (**), 0 flaws (~~), 10 warnings (==), 1 comment (--). 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: December 25, 2014 SailPoint 6 M. Ansari 7 Cisco 8 E. Wahlstroem 9 Technology Nexus 10 C. Mortimore 11 Salesforce 12 June 23, 2014 14 System for Cross-Domain Identity Management:Protocol 15 draft-ietf-scim-api-06 17 Abstract 19 The System for Cross-Domain Identity Management (SCIM) specification 20 is designed to make managing user identity in cloud based 21 applications and services easier. The specification suite seeks to 22 build upon experience with existing schemas and deployments, placing 23 specific emphasis on simplicity of development and integration, while 24 applying existing authentication, authorization, and privacy models. 25 It's intent is to reduce the cost and complexity of user management 26 operations by providing a common user schema and extension model, as 27 well as binding documents to provide patterns for exchanging this 28 schema using standard protocols. In essence, make it fast, cheap, 29 and easy to move users in to, out of, and around the cloud. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on December 25, 2014. 48 Copyright Notice 50 Copyright (c) 2014 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 66 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3 67 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3 68 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 69 2. Authentication and Authorization . . . . . . . . . . . . . . 4 70 3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 71 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 7 72 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 9 73 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 9 74 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 9 75 3.2.2. List/Query Resources . . . . . . . . . . . . . . . . 10 76 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 20 77 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 22 78 3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 23 79 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 25 80 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 35 81 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 35 82 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 50 83 3.7. Additional Operation Response Parameters . . . . . . . . 51 84 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 52 85 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 53 86 3.10. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 53 87 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 55 88 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 55 89 4. Preparation and Comparison of Internationalized Strings . . . 57 90 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 57 91 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 58 92 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 59 93 6. Security Considerations . . . . . . . . . . . . . . . . . . . 59 94 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 59 95 6.2. Request URI Information Leakage . . . . . . . . . . . . . 59 96 6.3. Case Insensitive Comparision & International Languages . 60 97 6.4. Universal Identifiers . . . . . . . . . . . . . . . . . . 60 98 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 99 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 60 100 7.2. SCIM API Message Schema Registry . . . . . . . . . . . . 61 101 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 62 102 8.1. Normative References . . . . . . . . . . . . . . . . . . 62 103 8.2. Informative References . . . . . . . . . . . . . . . . . 64 104 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 64 105 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 64 106 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 64 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 66 109 1. Introduction and Overview 111 The SCIM Protocol is an application-level, HTTP protocol for 112 provisioning and managing identity data on the web. The protocol 113 supports creation, modification, retrieval, and discovery of core 114 identity resources; i.e., Users and Groups, as well as custom 115 resource extensions. 117 1.1. Intended Audience 119 This document is intended as a guide to SCIM API usage for both 120 identity service providers and clients. 122 1.2. Notational Conventions 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 126 document are to be interpreted as described in [RFC2119]. These 127 keywords are capitalized when used to unambiguously specify 128 requirements of the protocol or application features and behavior 129 that affect the interoperability and security of implementations. 130 When these words are not capitalized, they are meant in their 131 natural-language sense. 133 For purposes of readability examples are not URL encoded. 134 Implementers MUST percent encode URLs as described in Section 2.1 135 [RFC3986]. 137 1.3. Definitions 139 Base URL: The SCIM HTTP API is always relative to a Base URL. The 140 Base URL MUST NOT contain a query string as clients may append 141 additional path information and query parameters as part of 142 forming the request. Example: "https://example.com/scim/" 143 For readability, all examples in this document are expressed 144 assuming the SCIM service root and the server root are the same. 145 It is expected that SCIM servers may be deployed using any URI 146 prefix. For example, a SCIM server might be have a prefix of 147 "https://example.com/", or "https://example.com/scim/ 148 tenancypath/". Additionally client may also apply a version 149 number to the server root prefix (see Section 3.11 ). 151 2. Authentication and Authorization 153 The SCIM protocol does not define a scheme for authentication and 154 authorization therefore implementers are free to choose mechanisms 155 appropriate to their use cases. The choice of authentication 156 mechanism will impact interoperability. It is RECOMMENDED that 157 clients be implemented in such a way that new authentication schemes 158 can be deployed. Implementers SHOULD support existing 159 authentication/authorization schemes. In particular, OAuth2 160 [RFC6750] is RECOMMENDED. Appropriate security considerations of the 161 selected authentication and authorization schemes SHOULD be taken. 162 Because this protocol uses HTTP response status codes as the primary 163 means of reporting the result of a request, servers are advised to 164 respond to unauthorized or unauthenticated requests using the 401 165 response code in accordance with Section 3.1 of [RFC7235]. 167 All examples assume OAuth2 bearer token [RFC6750] ; e.g., 169 GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 170 Host: example.com 171 Authorization: Bearer h480djs93hd8 173 The context of the request (i.e. the user for whom data is being 174 requested) MUST be inferred by service providers. 176 3. API 178 The SCIM protocol specifies well known endpoints and HTTP methods for 179 managing resources defined in the core schema; i.e., "User" and 180 "Group" resources correspond to "/Users" and "/Groups" respectively. 181 Service providers that support extended resources SHOULD define 182 resource endpoints using the established convention; pluralize the 183 resource name defined in the extended schema by appending an 's'. 184 Given there are cases where resource pluralization is ambiguous; 185 e.g., a resource named "Person" is legitimately "Persons" and 186 "People" clients SHOULD discover resource endpoints via the 187 "/ResourceTypes" endpoint. 189 GET Retrieves a complete or partial resource. 191 POST Create new resources, create a Search request, or bulk modify 192 resources. 194 PUT Modifies a resource by replacing existing attributes with a 195 specified set of replacement attributes (replace). PUT SHOULD NOT 196 be used to create new resources. 198 PATCH Modifies a resource with a set of client specified changes 199 (partial update). 201 DELETE Deletes a resource. 203 +------------+--------------------+---------------+-----------------+ 204 | Resource | Endpoint | Operations | Description | 205 +------------+--------------------+---------------+-----------------+ 206 | User | /Users | GET (Section | Retrieve/Add/Mo | 207 | | | 3.2.1), POST | dify Users | 208 | | | (Section | | 209 | | | 3.1), PUT | | 210 | | | (Section | | 211 | | | 3.3.1), PATCH | | 212 | | | (Section | | 213 | | | 3.3.2), | | 214 | | | DELETE | | 215 | | | (Section 3.4) | | 216 | Group | /Groups | GET (Section | Retrieve/Add/Mo | 217 | | | 3.2.1), POST | dify Groups | 218 | | | (Section | | 219 | | | 3.1), PUT | | 220 | | | (Section | | 221 | | | 3.3.1), PATCH | | 222 | | | (Section | | 223 | | | 3.3.2), | | 224 | | | DELETE | | 225 | | | (Section 3.4) | | 226 | Service | /ServiceProviderCo | GET (Section | Retrieve the | 227 | Provider C | nfigs | 3.2.1) | service | 228 | onfigurati | | | provider's | 229 | on | | | configuration | 230 | Resource | /ResourceTypes | GET (Section | Retrieve the | 231 | Type | | 3.2.1) | supported | 232 | | | | resource types | 233 | Schema | /Schemas | GET (Section | Retrieve a | 234 | | | 3.2.1) | resource's | 235 | | | | schema | 236 | Bulk | /Bulk | POST (Section | Bulk modify | 237 | | | 3.5) | resources | 238 | Search | [prefix]/.search | POST (Section | Perform a | 239 | | | 3.2.3) | search at | 240 | | | | system root or | 241 | | | | within a | 242 | | | | resource | 243 | | | | endpoint for | 244 | | | | one or more | 245 | | | | resource types | 246 | | | | using POST. | 247 +------------+--------------------+---------------+-----------------+ 249 Table 1: Defined endpoints 251 All requests to the service provider are made via HTTP Methods as per 252 Section 4.3 [RFC7231] on a URL derived from the Base URL. Responses 253 are returned in the body of the HTTP response, formatted as JSON. 254 Response and error codes SHOULD be transmitted via the HTTP status 255 code of the response (if possible), and SHOULD also be specified in 256 the body of the response. 258 3.1. Creating Resources 260 To create new resources, clients send POST requests to the resource 261 container endpoint such as: "/Users" or "/Groups". 263 Attributes whose mutability is "readOnly", that are included in the 264 request body SHALL be ignored. 266 Attributes whose mutability is "readWrite", that are omitted from the 267 request body, MAY be assumed to be not asserted by the client. The 268 service provider MAY assign a default value to non-asserted 269 attributes in the final resource representation. Service providers 270 MAY take into account whether a client has access to, or understands, 271 all of the resource's attributes when deciding whether non-asserted 272 attributes SHALL be defaulted. Clients that would like to override a 273 server defaults, MAY specify "null" for a single-valued attribute or 274 an empty array "[]" for a multi-valued attribute to clear all values. 276 Successful resource creation is indicated with a 201 ("Created") 277 response code. Upon successful creation, the response body MUST 278 contain the newly created resource. Since the server is free to 279 alter and/or ignore POSTed content, returning the full representation 280 can be useful to the client, enabling it to correlate the client and 281 server views of the new resource. When a resource is created, its 282 URI must be returned in the response Location header. 284 If the service provider determines creation of the requested resource 285 conflicts with existing resources; e.g., a "User" resource with a 286 duplicate "userName", the service provider MUST return a 409 error 287 and SHOULD indicate the conflicting attribute(s) in the body of the 288 response. 290 Below, the client sends a POST request containing a user 291 POST /Users HTTP/1.1 292 Host: example.com 293 Accept: application/scim+json 294 Content-Type: application/scim+json 295 Authorization: Bearer h480djs93hd8 296 Content-Length: ... 298 { 299 "schemas":["urn:scim:schemas:core:2.0:User"], 300 "userName":"bjensen", 301 "externalId":"bjensen", 302 "name":{ 303 "formatted":"Ms. Barbara J Jensen III", 304 "familyName":"Jensen", 305 "givenName":"Barbara" 306 } 307 } 309 The server signals a successful creation with a status code of 201. 310 The response includes a Location header indicating the User URI, and 311 a representation of that user in the body of the response. 313 HTTP/1.1 201 Created 314 Content-Type: application/scim+json 315 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 316 ETag: W/"e180ee84f0671b1" 318 { 319 "schemas":["urn:scim:schemas:core:2.0:User"], 320 "id":"2819c223-7f76-453a-919d-413861904646", 321 "externalId":"bjensen", 322 "meta":{ 323 "resourceType":"User", 324 "created":"2011-08-01T21:32:44.882Z", 325 "lastModified":"2011-08-01T21:32:44.882Z", 326 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 327 "version":"W\/\"e180ee84f0671b1\"" 328 }, 329 "name":{ 330 "formatted":"Ms. Barbara J Jensen III", 331 "familyName":"Jensen", 332 "givenName":"Barbara" 333 }, 334 "userName":"bjensen" 335 } 336 3.1.1. Resource Types 338 When adding a resource to a specific endpoint, the meta attribute 339 "resourceType" SHALL be set by the service provider to the 340 corresponding resource Type for the endpoint. For example, "/Users" 341 will set "resourceType" to "User", and "/Groups" will set 342 "resourceType" to "Group". 344 3.2. Retrieving Resources 346 "User" and "Group" resources are retrieved via opaque, unique URLs or 347 via Query. Service providers MAY choose to respond with a sub-set of 348 resource attributes, though MUST minimally return the resource id and 349 meta attributes. 351 3.2.1. Retrieving a known Resource 353 To retrieve a known resource, clients send GET requests to the 354 resource endpoint; e.g., "/Users/{id}" or "/Groups/{id}". 356 If the resource exists the server responds with a status code of 200 357 and includes the result in the body of the response. 359 The below example retrieves a single User via the "/Users" endpoint. 361 GET /Users/2819c223-7f76-453a-919d-413861904646 362 Host: example.com 363 Accept: application/scim+json 364 Authorization: Bearer h480djs93hd8 366 The server responds with: 368 HTTP/1.1 200 OK 369 Content-Type: application/scim+json 370 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 371 ETag: W/"f250dd84f0671c3" 373 { 374 "schemas":["urn:scim:schemas:core:2.0:User"], 375 "id":"2819c223-7f76-453a-919d-413861904646", 376 "externalId":"bjensen", 377 "meta":{ 378 "resourceType":"User", 379 "created":"2011-08-01T18:29:49.793Z", 380 "lastModified":"2011-08-01T18:29:49.793Z", 381 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 382 "version":"W\/\"f250dd84f0671c3\"" 383 }, 384 "name":{ 385 "formatted":"Ms. Barbara J Jensen III", 386 "familyName":"Jensen", 387 "givenName":"Barbara" 388 }, 389 "userName":"bjensen", 390 "phoneNumbers":[ 391 { 392 "value":"555-555-8377", 393 "type":"work" 394 } 395 ], 396 "emails":[ 397 { 398 "value":"bjensen@example.com", 399 "type":"work" 400 } 401 ] 402 } 404 3.2.2. List/Query Resources 406 SCIM defines a standard set of operations that can be used to filter, 407 sort, and paginate response results. The operations are specified by 408 adding query parameters to the resource's endpoint. Service 409 providers MAY support additional query parameters not specified here, 410 and Providers SHOULD ignore any query parameters they don't 411 recognize. 413 List and query responses MUST be identified using the following URI: 414 "urn:scim:api:messages:2.0:ListResponse". The following attributes 415 are defined for list and query responses: 417 totalResults The total number of results returned by the list or 418 query operation. This may not be equal to the number of elements 419 in the resources attribute of the list response if pagination 420 (Section 3.2.2.4) is requested. REQUIRED. 422 Resources A multi-valued list of complex objects containing the 423 requested resources. This may be a subset of the full set of 424 resources if pagination (Section 3.2.2.4) is requested. REQUIRED 425 if "totalResults" is non-zero. 427 startIndex The 1-based index of the first result in the current set 428 of list results. REQUIRED if pagination (Section 3.2.2.4) is 429 requested. 431 itemsPerPage The number of resources returned in a list response 432 page. REQUIRED if pagination (Section 3.2.2.4) is requested. 434 A query that does not return any matches SHALL return success with 435 "totalResults" set to a value of 0. 437 The query example below requests the userName for all Users: 439 GET /Users?attributes=userName 440 Host: example.com 441 Accept: application/scim+json 442 Authorization: Bearer h480djs93hd8 444 The following is an example response to the query above: 446 HTTP/1.1 200 OK 447 Content-Type: application/scim+json 449 { 450 "schemas":["urn:scim:api:messages:2.0:ListResponse"], 451 "totalResults":2, 452 "Resources":[ 453 { 454 "userName":"bjensen" 455 }, 456 { 457 "userName":"jsmith" 458 } 459 ] 460 } 462 3.2.2.1. Query Endpoints 464 Queries MAY be performed against a SCIM resource object or a resource 465 type endpoint. For example: 467 "/Users/{userid}" 469 "/Users" 471 "/Groups" 473 A server MAY support searches against the server root (e.g. "/"). A 474 search against a server root indicates that ALL resources within the 475 server SHALL be included subject to filtering. A filter expression 476 using "meta.resourceType" MAY be used to restrict results to one or 477 more specific resource types (e.g. "User" ). 479 When processing search operations across endpoints that include more 480 than one SCIM resource type (e.g. a search from the server root 481 endpoint), filters MUST be processed in the same fashion as outlined 482 in Section 3.2.2.2. For filtered attributes that are not part of a 483 particular resource type, the service provider SHALL treat the 484 attribute as if there is no attribute value. For example, a presence 485 or equality filter for an undefined attribute evaluates as FALSE. 487 3.2.2.2. Filtering 489 Filtering is OPTIONAL. Clients may request a subset of resources by 490 specifying the 'filter' URL query parameter containing a filter 491 expression. When specified only those resources matching the filter 492 expression SHALL be returned. The expression language that is used 493 in the filter parameter supports references to attributes and 494 literals. 496 The attribute name and attribute operator are case insensitive. For 497 example, the following two expressions will evaluate to the same 498 logical value: 500 filter=userName Eq "john" 502 filter=Username eq "john" 504 The filter parameter MUST contain at least one valid Boolean 505 expression. Each expression MUST contain an attribute name followed 506 by an attribute operator and optional value. Multiple expressions 507 MAY be combined using the two logical operators. Furthermore 508 expressions can be grouped together using "()". 510 The operators supported in the expression are listed in the following 511 table. 513 +----------+-------------+------------------------------------------+ 514 | Operator | Description | Behavior | 515 +----------+-------------+------------------------------------------+ 516 | eq | equal | The attribute and operator values must | 517 | | | be identical for a match. | 518 | ne | not equal | The attribute and operator values are | 519 | | | not identical. | 520 | co | contains | The entire operator value must be a | 521 | | | substring of the attribute value for a | 522 | | | match. | 523 | sw | starts with | The entire operator value must be a | 524 | | | substring of the attribute value, | 525 | | | starting at the beginning of the | 526 | | | attribute value. This criterion is | 527 | | | satisfied if the two strings are | 528 | | | identical. | 529 | ew | ends with | The entire operator value must be a | 530 | | | substring of the attribute value, | 531 | | | matching at the end of the attribute | 532 | | | value. This criterion is satisfied if | 533 | | | the two strings are identical. | 534 | pr | present | If the attribute has a non-empty value, | 535 | | (has value) | or if it contains a non-empty node for | 536 | | | complex attributes there is a match. | 537 | gt | greater | If the attribute value is greater than | 538 | | than | operator value, there is a match. The | 539 | | | actual comparison is dependent on the | 540 | | | attribute type. For string attribute | 541 | | | types, this is a lexicographical | 542 | | | comparison and for DateTime types, it is | 543 | | | a chronological comparison. | 544 | ge | greater | If the attribute value is greater than | 545 | | than or | or equal to the operator value, there is | 546 | | equal | a match. The actual comparison is | 547 | | | dependent on the attribute type. For | 548 | | | string attribute types, this is a | 549 | | | lexicographical comparison and for | 550 | | | DateTime types, it is a chronological | 551 | | | comparison. | 552 | lt | less than | If the attribute value is less than | 553 | | | operator value, there is a match. The | 554 | | | actual comparison is dependent on the | 555 | | | attribute type. For string attribute | 556 | | | types, this is a lexicographical | 557 | | | comparison and for DateTime types, it is | 558 | | | a chronological comparison. | 559 | le | less than | If the attribute value is less than or | 560 | | or equal | equal to the operator value, there is a | 561 | | | match. The actual comparison is | 562 | | | dependent on the attribute type. For | 563 | | | string attribute types, this is a | 564 | | | lexicographical comparison and for | 565 | | | DateTime types, it is a chronological | 566 | | | comparison. | 567 +----------+-------------+------------------------------------------+ 569 Table 2: Attribute Operators 571 +----------+-------------+------------------------------------------+ 572 | Operator | Description | Behavior | 573 +----------+-------------+------------------------------------------+ 574 | and | Logical And | The filter is only a match if both | 575 | | | expressions evaluate to true. | 576 | or | Logical or | The filter is a match if either | 577 | | | expression evaluates to true. | 578 | not | Not | The filter is a match if the expression | 579 | | function | evaluates to false. | 580 +----------+-------------+------------------------------------------+ 582 Table 3: Logical Operators 584 +----------+-------------+------------------------------------------+ 585 | Operator | Description | Behavior | 586 +----------+-------------+------------------------------------------+ 587 | ( ) | Precedence | Boolean expressions may be grouped using | 588 | | grouping | parentheses to change the standard order | 589 | | | of operations; i.e., evaluate OR logical | 590 | | | operators before logical AND operators. | 591 | [ ] | Complex | Service providers MAY support complex | 592 | | attribute | filters where expressions MUST be | 593 | | filter | applied to the same value of a parent | 594 | | grouping | attribute specified immediately before | 595 | | | the left square bracket ("["). The | 596 | | | expression within square brackets ("[" | 597 | | | and "]") MUST be a valid filter | 598 | | | expression based upon sub-attributes of | 599 | | | the parent attribute. Nested expressions | 600 | | | MAY be used. See examples below. | 601 +----------+-------------+------------------------------------------+ 603 Table 4: Grouping Operators 605 SCIM filters MUST conform to the following ABNF rules as per 606 [RFC5234] below: 608 FILTER = attrExp / logExp / valuePath / *1"not" "(" FILTER ")" 610 valuePath = attrPath "[" FILTER "]" 611 ; FILTER uses sub-attribs of a parent attrPath 613 ATTRNAME = ALPHA *(nameChar) 615 nameChar = "-" / "_" / DIGIT / ALPHA 617 attrPath = [URI ":"] ATTRNAME *1subAttr 618 ; SCIM attribute name 619 ; URI is SCIM "schema" URI 621 subAttr = "." ATTRNAME 622 ; a sub-attribute of a complex attribute 624 attrExpr = (attrPath SP "pr") / 625 (attrPath SP compareOp SP compValue) 627 compValue = false / null / true / number / string 628 ; rules from JSON (RFC7159) 630 compareOp = "eq" / "ne" / "co" / 631 "sw" / "ew" / 632 "gt" / "lt" / 633 "ge" / "le" 635 logExp = FILTER ("and" / "or") FILTER 637 Figure 1: ABNF Specification of SCIM Filters 639 In the above ABNF, the "compValue" (comparison value) rule is built 640 on JSON Data Interchange format ABNF rules as specified in [RFC7159], 641 "DIGIT" and "ALPHA" are defined per Appendix B.1 of [RFC5234] and, 642 "URI" is defined per Appendix A of [RFC3986]. 644 Filters MUST be evaluated using standard order of operations 645 [Order-Operations]. Attribute operators have the highest precedence, 646 followed by the grouping operator (i.e, parentheses), followed by the 647 logical AND operator, followed by the logical OR operator. 649 If the specified attribute in a filter expression is a multi-valued 650 attribute, the resource MUST match if any of the instances of the 651 given attribute match the specified criterion; e.g. if a User has 652 multiple emails values, only one has to match for the entire User to 653 match. For complex attributes, a fully qualified Sub-Attribute MUST 654 be specified using standard attribute notation (Section 3.8). For 655 example, to filter by userName the parameter value is userName and to 656 filter by first name, the parameter value is name.givenName. 658 Providers MAY support additional filter operations if they choose. 659 Providers MUST decline to filter results if the specified filter 660 operation is not recognized and return a HTTP 400 error with an 661 appropriate human readable response. For example, if a client 662 specified an unsupported operator named 'regex' the service provider 663 should specify an error response description identifying the client 664 error; e.g., 'The operator 'regex' is not supported.' 666 String type attributes are case insensitive by default unless the 667 attribute type is defined as case exact. Attribute comparison 668 operators 'eq', 'co', and 'sw' MUST perform caseIgnore matching for 669 all string attributes unless the attribute is defined as case exact. 670 By default all string attributes are case insensitive. 672 Clients MAY search by schema or schema extensions by using a filter 673 expression including the "schemas" attribute. 675 The following are examples of valid filters. Some attributes (e.g. 676 rooms and rooms.number) are hypothetical extensions and are not part 677 of SCIM core schema: 679 filter=userName eq "bjensen" 681 filter=name.familyName co "O'Malley" 683 filter=userName sw "J" 685 filter=title pr 687 filter=meta.lastModified gt "2011-05-13T04:42:34Z" 689 filter=meta.lastModified ge "2011-05-13T04:42:34Z" 691 filter=meta.lastModified lt "2011-05-13T04:42:34Z" 693 filter=meta.lastModified le "2011-05-13T04:42:34Z" 695 filter=title pr and userType eq "Employee" 697 filter=title pr or userType eq "Intern" 699 filter=schemas eq "urn:scim:schemas:extension:enterprise:2.0:User" 701 filter=userType eq "Employee" and (emails co "example.com" or emails 702 co "example.org") 704 filter=userType ne "Employee" and not (emails co "example.com" or 705 emails co "example.org") 707 filter=userType eq "Employee" and (emails.type eq "work") 709 filter=userType eq "Employee" and emails[type eq "work" and 710 value co "@example.com"] 712 filter=emails[type eq "work" and value co "@example.com"] or 713 ims[type eq "xmpp" and value co "@foo.com"] 715 filter=addresses[state eq "CA" and rooms[type eq "bedroom" and 716 number gt 2]] 718 Example Filters 720 3.2.2.3. Sorting 722 Sort is OPTIONAL. Sorting allows clients to specify the order in 723 which resources are returned by specifying a combination of sortBy 724 and sortOrder URL parameters. 726 sortBy: The sortBy parameter specifies the attribute whose value 727 SHALL be used to order the returned responses. If the sortBy 728 attribute corresponds to a singular attribute, resources are 729 sorted according to that attribute's value; if it's a multi-valued 730 attribute, resources are sorted by the value of the primary 731 attribute, if any, or else the first value in the list, if any. 732 If the attribute is complex the attribute name must be a path to a 733 sub-attribute in standard attribute notation (Section 3.8) ; e.g., 734 "sortBy=name.givenName". For all attribute types, if there is no 735 data for the specified "sortBy" value they are sorted via the 736 "sortOrder" parameter; i.e., they are ordered last if ascending 737 and first if descending. 739 sortOrder: The order in which the sortBy parameter is applied. 740 Allowed values are "ascending" and "descending". If a value for 741 sortBy is provided and no sortOrder is specified, the sortOrder 742 SHALL default to ascending. String type attributes are case 743 insensitive by default unless the attribute type is defined as a 744 case exact string. "sortOrder" MUST sort according to the 745 attribute type; i.e., for caee insensitive attributes, sort the 746 result using case insensitive, unicode alphabetic sort order, with 747 no specific locale implied and for case exact attribute types, 748 sort the result using case sensitive, Unicode alphabetic sort 749 order. 751 3.2.2.4. Pagination 753 Pagination parameters can be used together to "page through" large 754 numbers of resources so as not to overwhelm the client or service 755 provider. Pagination is not session based hence clients SHOULD never 756 assume repeatable results. For example, a request for a list of 10 757 resources beginning with a startIndex of 1 may return different 758 results when repeated as a resource in the original result could be 759 deleted or new ones could be added in-between requests. Pagination 760 parameters and general behavior are derived from the OpenSearch 761 Protocol [OpenSearch]. 763 The following table describes the URL pagination parameters. 765 +------------+-------------------+----------------------------------+ 766 | Parameter | Description | Default | 767 +------------+-------------------+----------------------------------+ 768 | startIndex | The 1-based index | 1 | 769 | | of the first | | 770 | | search result. | | 771 | count | Non-negative | None. When specified the service | 772 | | Integer. | provider MUST not return more | 773 | | Specifies the | results than specified though | 774 | | desired maximum | MAY return fewer results. If | 775 | | number of search | unspecified, the maximum number | 776 | | results per page; | of results is set by the service | 777 | | e.g., 10. | provider. | 778 +------------+-------------------+----------------------------------+ 780 Table 5: Pagination Request parameters 782 The following table describes the query response pagination 783 attributes specified by the service provider. 785 +--------------+----------------------------------------------------+ 786 | Element | Description | 787 +--------------+----------------------------------------------------+ 788 | itemsPerPage | Non-negative Integer. Specifies the number of | 789 | | search results returned in a query response page; | 790 | | e.g., 10. | 791 | totalResults | Non-negative Integer. Specifies the total number | 792 | | of results matching the client query; e.g., 1000. | 793 | startIndex | The 1-based index of the first result in the | 794 | | current set of search results; e.g., 1. | 795 +--------------+----------------------------------------------------+ 797 Table 6: Pagination Response Elements 799 For example, to retrieve the first 10 Users set the startIndex to 1 800 and the count to 10: 802 GET /Users?startIndex=1&count=10 803 Host: example.com 804 Accept: application/scim+json 805 Authorization: Bearer h480djs93hd8 806 The response to the query above returns metadata regarding paging 807 similar to the following example (actual resources removed for 808 brevity): 810 { 811 "totalResults":100, 812 "itemsPerPage":10, 813 "startIndex":1, 814 "schemas":["urn:scim:api:messages:2.0"], 815 "Resources":[{ 816 ... 817 }] 818 } 820 Given the example above, to continue paging set the startIndex to 11 821 and re-fetch; i.e., /Users?startIndex=11&count=10 823 3.2.3. Querying Resources Using HTTP POST 825 Clients MAY execute queries without passing parameters on the URL by 826 using the HTTP POST verb combined with the '/.search' path extension. 827 The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL 828 be used to indicate the HTTP POST verb is intended to be a query 829 operation. 831 To create a new search result set, a SCIM client sends an HTTP POST 832 request to the desired SCIM resource endpoint (ending in '/.search'). 833 The body of the POST request MAY include any of the parameters as 834 defined in Section 3.2.2. 836 Search requests MUST be identified using the following URI: 837 'urn:scim:api:messages:2.0:SearchRequest'. The following attributes 838 are defined for search requests: 840 attributes A multi-valued list of strings indicating the names of 841 resource attributes to return in the response overriding the set 842 of attributes that would be returned by default. Attribute names 843 MUST be in standard attribute notation (Section 3.8) form. See 844 additional retrieval query parameters (Section 3.7). OPTIONAL. 846 excludedAttributes A multi-valued list of strings indicating the 847 names of resource attributes to be removed from the default set of 848 attributes to return. This parameter SHALL have no effect on 849 attributes whose schema "returned" setting is "always" see Server 850 Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in 851 standard attribute notation (Section 3.8) form. See additional 852 retrieval query parameters (Section 3.7). OPTIONAL. 854 filter The filter string used to request a subset of resources. The 855 filter string MUST be a valid filter (Section 3.2.2.2) expression. 856 OPTIONAL. 858 sortBy A string indicating the attribute whose value SHALL be used 859 to order the returned responses. The sortBy attribute MUST be in 860 standard attribute notation (Section 3.8) form. See sorting 861 (Section 3.2.2.3). OPTIONAL. 863 sortOrder A string indicating the order in which the sortBy 864 parameter is applied. Allowed values are "ascending" and 865 "descending". See sorting (Section 3.2.2.3). OPTIONAL. 867 startIndex An integer indicating the 1-based index of the first 868 search result. See pagination (Section 3.2.2.4). OPTIONAL. 870 count An integer indicating the desired maximum number of search 871 results per page. See pagination (Section 3.2.2.4). OPTIONAL. 873 After receiving a HTTP POST request, a response is returned as 874 specified in Section 3.2.2. 876 The following example shows an HTTP POST Search request with search 877 parameters attributes, filter, and count included: 879 POST /.search 880 Host: example.com 881 Accept: application/scim+json 882 Content-Type: application/scim+json 883 Authorization: Bearer h480djs93hd8 884 Content-Length: ... 886 { 887 "schemas": ["urn:scim:api:messages:2.0:SearchRequest"], 888 "attributes": ["displayName", "userName"], 889 "filter": "displayName sw \"smith\"", 890 "startIndex": 1, 891 "count": 10 892 } 894 Figure 2: Example POST Search Request 896 A search response is shown with the first page of results. For 897 brevity reasons, only two matches are shown: one User and one Group. 899 HTTP/1.1 200 OK 900 Content-Type: application/scim+json 901 Location: https://example.com/.search 902 { 903 "schemas": ["urn:scim:api:messages:2.0:ListResponse"], 904 "totalResults":100, 905 "itemsPerPage":10, 906 "startIndex":1, 907 "Resources":[ 908 { 909 "meta":{ 910 "location": 911 "https://example.com/Users/2819c223-7f76-413861904646", 912 "resourceType":"User", 913 "lastModified": ... 914 }, 915 "userName":"jsmith", 916 "displayName":"Smith, James" 917 }, 918 { 919 "meta":{ 920 "location": 921 "https://example.com/Groups/c8596b90-7539-4f20968d1908", 922 "resourceType":"Group", 923 "lastModified": ... 924 }, 925 "displayName":"Smith Family" 926 }, 927 ... 928 ] 929 } 931 Figure 3: Example POST Search Response 933 3.3. Modifying Resources 935 Resources can be modified in whole or in part via PUT or PATCH, 936 respectively. Implementers MUST support PUT as specified in 937 Section 4.3 [RFC7231]. Resources such as Groups may be very large 938 hence implementers SHOULD support PATCH [RFC5789] to enable partial 939 resource modifications. 941 3.3.1. Replacing with PUT 943 HTTP PUT is used to perform a full update of a resource's attributes. 944 Clients that MAY have previously retrieved the entire resource in 945 advance and revised it, MAY replace the resource using an HTTP PUT. 946 Because SCIM resource identifiers are typically assigned by the 947 service provider, HTTP PUT SHOULD NOT be used to create new 948 resources. 950 As the operation intent is to replace all attributes, SCIM clients 951 MAY send all attributes regardless of each attribute's mutability. 952 The server will apply attribute by attribute replace according to the 953 following attribute mutability rules: 955 readWrite, writeOnly Any values provided SHALL replace the existing 956 attribute values. 958 immutable If value(s) are already set for the attribute, the input 959 value(s) MUST match or HTTP status 400 SHOULD be returned with 960 error code "mutability". If the service provider has no existing 961 values, the new value(s) SHALL be applied. 963 readOnly Any values provided (e.g. meta.resourceType) SHALL be 964 ignored. 966 If an attribute is "required", clients MUST specify the attribute in 967 the PUT request. 969 Attributes whose mutability is "readWrite", that are omitted from the 970 request body, MAY be assumed to be not asserted by the client. The 971 service provider MAY assume any existing values are to be cleared or 972 the service provider MAY assign a default value to the final resource 973 representation. Service providers MAY take into account whether a 974 client has access to, or understands, all of the resource's 975 attributes when deciding whether non-asserted attributes SHALL be 976 removed or defaulted. Clients that would like to override a server 977 defaults, MAY specify "null" for a single-valued attribute or an 978 empty array "[]" for a multi-valued attribute to clear all values. 980 Unless otherwise specified a successful PUT operation returns a 200 981 OK response code and the entire resource within the response body, 982 enabling the client to correlate the client's and Provider's views of 983 the updated resource. Example: 985 PUT /Users/2819c223-7f76-453a-919d-413861904646 986 Host: example.com 987 Accept: application/scim+json 988 Content-Type: application/scim+json 989 Authorization: Bearer h480djs93hd8 990 If-Match: W/"a330bc54f0671c9" 992 { 993 "schemas":["urn:scim:api:messages:2.0:User"], 994 "id":"2819c223-7f76-453a-919d-413861904646", 995 "userName":"bjensen", 996 "externalId":"bjensen", 997 "name":{ 998 "formatted":"Ms. Barbara J Jensen III", 999 "familyName":"Jensen", 1000 "givenName":"Barbara", 1001 "middleName":"Jane" 1002 }, 1003 "roles":[], 1004 "emails":[ 1005 { 1006 "value":"bjensen@example.com" 1007 }, 1008 { 1009 "value":"babs@jensen.org" 1010 } 1011 ] 1012 } 1013 The service responds with the entire, updated User: 1015 HTTP/1.1 200 OK 1016 Content-Type: application/scim+json 1017 ETag: W/"b431af54f0671a2" 1018 Location:"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646" 1019 { 1020 "schemas":["urn:scim:api:messages:2.0:User"], 1021 "id":"2819c223-7f76-453a-919d-413861904646", 1022 "userName":"bjensen", 1023 "externalId":"bjensen", 1024 "name":{ 1025 "formatted":"Ms. Barbara J Jensen III", 1026 "familyName":"Jensen", 1027 "givenName":"Barbara", 1028 "middleName":"Jane" 1029 }, 1030 "emails":[ 1031 { 1032 "value":"bjensen@example.com" 1033 }, 1034 { 1035 "value":"babs@jensen.org" 1036 } 1037 ], 1038 "meta": { 1039 "resourceType":"User", 1040 "created":"2011-08-08T04:56:22Z", 1041 "lastModified":"2011-08-08T08:00:12Z", 1042 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 1043 "version":"W\/\"b431af54f0671a2\"" 1044 } 1045 } 1047 3.3.2. Modifying with PATCH 1049 HTTP PATCH is an OPTIONAL server function that enables clients to 1050 update one or more attributes of a SCIM resource using a sequence of 1051 operations to "add", "remove", or "replace" values. The general form 1052 of the SCIM patch request is based on JavaScript Object Notation 1053 (JSON) Patch [RFC6902]. One difference between SCIM patch and JSON 1054 patch is that SCIM servers do not support array indexing and may not 1055 support all [RFC6902] operation types. 1057 The body of an HTTP PATCH request MUST contain one or more patch 1058 operation objects. A patch operation object MUST have exactly one 1059 "op" member, whose value indicates the operation to perform and MAY 1060 be one of "add", "remove", or "replace". The semantics of each 1061 operation are defined below. 1063 Each operation object MUST contain the following "schemas" URI: 1064 "urn:scim:api:messages:2.0:PatchOp" 1066 Operation objects MUST have exactly one "path" member which is a 1067 "String" containing an attribute path as specified by the following 1068 ABNF syntax rule: 1070 PATH = attrPath / valuePath [subAttr] 1072 Figure 4: SCIM Patch PATH Rule 1074 The rules, "attrPath", "valuePath", and "subAttr" are defined in 1075 Section 3.2.2.2. The "valuePath" rule allows specific values of a 1076 complex, multi-valued attribute to be selected. 1078 Valid examples of "path" values are as follows: 1080 "path":"members" 1082 "path":"name.familyName" 1084 "path":"addresses[type eq \"work\"]" 1086 "path":"members[value eq 1087 \"2819c223-7f76-453a-919d-413861904646\"]" 1089 "path":"members[value eq 1090 \"2819c223-7f76-453a-919d-413861904646\"].displayName" 1092 Each operation against an attribute MUST be compatible with the 1093 attribute's mutability and schema as defined in the Attribute Types 1094 Section of [I-D.ietf-scim-core-schema]. For example, a client MAY 1095 NOT modify an attribute that has mutability "readOnly" or 1096 "immutable". However, a client MAY "add" a value to an "immutable" 1097 attribute if the attribute had no previous value. An operation that 1098 is not compatibile with an attribute's mutability or schema SHALL 1099 return an error as indicated below. 1101 Each patch operation represents a single action to be applied to the 1102 same SCIM resource specified by the request URI. Operations are 1103 applied sequentially in the order they appear in the array. Each 1104 operation in the sequence is applied to the target resource; the 1105 resulting resource becomes the target of the next operation. 1106 Evaluation continues until all operations are successfully applied or 1107 until an error condition is encountered. 1109 A patch request, regardless of the number of operations, SHALL be 1110 treated as atomic. If a single operation encounters an error 1111 condition, the original SCIM resource MUST be restored, and a failure 1112 status SHALL be returned. 1114 If a request fails. the server SHALL return an HTTP response status 1115 code of 400 and a JSON detail error response containing an "error" 1116 object that SHOULD be one of the following string values: 1118 malformed_operation 1119 The JSON operation elements could not successfully be parsed. 1120 This may be due to an invalid or missing operation attribute, or 1121 it could be due to a missing attribute required by a specific 1122 operation. 1124 mutability 1125 The operation requested is not compatible with the mutability of 1126 the selected attribute. 1128 invalid_path 1129 The path attribute was invalid or malformed. 1131 no_target 1132 The "path" specified did not return a target against which the 1133 operation could be performed. 1135 invalid_value 1136 The operation "value" was missing or was not compatable with the 1137 targeted attribute's type 1139 The following is a non-normative example of an error response to a 1140 patch request. 1142 HTTP/1.1 400 Bad Request 1143 Content-Type: application/scim+json;charset=UTF-8 1144 Cache-Control: no-store 1145 Pragma: no-cache 1147 { 1148 "schemas": ["urn:scim:api:messages:2.0:Error"], 1149 "Errors":[ 1150 { 1151 "error":"mutability", 1152 "error_description":"Attribute 'id' is readOnly." 1153 } 1154 ] 1155 } 1156 On successful completion, the server MUST return either a 200 OK 1157 response code and the entire resource (subject to the "attributes" 1158 query parameter - see Additional Retrieval Query Parameters 1159 (Section 3.7) ) within the response body, or a 204 No Content 1160 response code and the appropriate response headers for a successful 1161 patch request. The server MUST return a 200 OK if the "attributes" 1162 parameter is specified on the request. 1164 3.3.2.1. Add Operation 1166 The "add" operation performs one of the following functions, 1167 depending upon what the target location indicated by "path" 1168 references: 1170 o If the target location does not exist, the attribute and value is 1171 added. 1173 o If the target location specifies a multi-valued attribute, a new 1174 value is added to the attribute. 1176 o if the target location specifies a single-valued attribute, the 1177 existing value is replaced. 1179 o If the target location specifies an attribute that does not exist 1180 (has no value), the attribute is added with the new value. 1182 o If the target location exists, the value is replaced. 1184 o If the target location already contains the value specified, no 1185 changes SHOULD be made to the resource and a success response 1186 SHOULD be returned. Unless other operations change the resource, 1187 this operation SHALL NOT change the modify timestamp of the 1188 resource. 1190 The operation MUST contain a "value" member whose content specifies 1191 the value to be added. The value MAY be a quoted value OR it may be 1192 a JSON object containing the sub-attributes of the complex attribute 1193 specified in the operation's "path". 1195 The following example shows how to add a member to a group. Some 1196 text removed for readability ("..."): 1198 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1199 Host: example.com 1200 Accept: application/scim+json 1201 Content-Type: application/scim+json 1202 Authorization: Bearer h480djs93hd8 1203 If-Match: W/"a330bc54f0671c9" 1205 { 1206 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1207 "op":"add", 1208 "path":"members", 1209 "value":[ 1210 { 1211 "display": "Babs Jensen", 1212 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1213 "value": "2819c223-7f76-453a-919d-413861904646" 1214 } 1215 ] 1216 } 1218 The "display" Sub-Attribute in this request is optional since the 1219 value attribute uniquely identifies the user to be added. If the 1220 user was already a member of this group, no changes should be made to 1221 the resource and a success response should be returned. The server 1222 responds with either the entire updated Group or no response body: 1224 HTTP/1.1 204 No Content 1225 Authorization: Bearer h480djs93hd8 1226 ETag: W/"b431af54f0671a2" 1227 Location: "https://example.com/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" 1229 3.3.2.2. Remove Operation 1231 The "remove" operation removes the value at the target location 1232 specified by the "path". The operation performs the following 1233 functions depending on the target location specified by "path" : 1235 o If the target location is a single-value attribute, the attribute 1236 and its associated value is removed. 1238 o If the target location is a multi-valued attribute and no filter 1239 is specified, the attribute and all values are removed. 1241 o If the target location is a multi-valued attribute and a complex 1242 filter is specified comparing a "value", the values matched by the 1243 filter are removed. 1245 o If the target location is a complex-multi-valued attribute and a 1246 complex filter is specified based on the attribute's sub- 1247 attributes, the matching records are removed. 1249 The following example shows how to remove a member from a group. As 1250 with the previous example, the "display" Sub-Attribute is optional. 1251 If the user was not a member of this group, no changes should be made 1252 to the resource and a success response should be returned. 1254 Note that server responses have been omitted for the rest of the 1255 PATCH examples. 1257 Remove a single member from a group. Some text removed for 1258 readability ("..."): 1260 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1261 Host: example.com 1262 Accept: application/scim+json 1263 Content-Type: application/scim+json 1264 Authorization: Bearer h480djs93hd8 1265 If-Match: W/"a330bc54f0671c9" 1267 { 1268 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1269 "op":"remove", 1270 "path":"members[value eq \"2819c223-7f76-...413861904646\"]" 1271 } 1273 Remove all members of a group: 1275 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1276 Host: example.com 1277 Accept: application/scim+json 1278 Content-Type: application/scim+json 1279 Authorization: Bearer h480djs93hd8 1280 If-Match: W/"a330bc54f0671c9" 1282 { "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1283 "op":"remove","path":"members"} 1285 Removal of a value from a complex-multi-valued attribute (request 1286 headers removed for brevity): 1288 { 1289 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1290 "op":"remove", 1291 "path":"emails[type eq \"work\" and value ew \"example.com\"]" 1292 } 1294 Example request to remove and add a member. Some text removed for 1295 readability ("..."): 1297 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1298 Host: example.com 1299 Accept: application/scim+json 1300 Content-Type: application/scim+json 1301 Authorization: Bearer h480djs93hd8 1302 If-Match: W/"a330bc54f0671c9" 1304 [ 1305 { 1306 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1307 "op":"remove", 1308 "path":"members[value eq\"2819c223...919d-413861904646\"]" 1309 }, 1310 { 1311 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1312 "op":"add", 1313 "path":"members", 1314 "value": [ 1315 { 1316 "display": "James Smith", 1317 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1318 "value": "08e1d05d...473d93df9210" 1319 } 1320 ] 1321 } 1322 ] 1323 The following example shows how to replace all the members of a group 1324 with a different members list. Some text removed for readabilty 1325 ("..."): 1327 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1328 Host: example.com 1329 Accept: application/scim+json 1330 Content-Type: application/scim+json 1331 Authorization: Bearer h480djs93hd8 1332 If-Match: W/"a330bc54f0671c9" 1334 [ 1335 { "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1336 "op":"remove","path":"members"}, 1337 { 1338 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1339 "op":"add", 1340 "path":"members", 1341 "value":[ 1342 { 1343 "display": "Babs Jensen", 1344 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1345 "value": "2819c223-7f76-453a-919d-413861904646" 1346 }, 1347 { 1348 "display": "James Smith", 1349 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1350 "value": "08e1d05d-121c-4561-8b96-473d93df9210" 1351 }] 1352 } 1353 ] 1355 3.3.2.3. Replace Operation 1357 The "replace" operation replaces the value at the target location 1358 specified by the "path". The operation performs the following 1359 functions depending on the target location specified by "path" : 1361 o If the target location is a single-value attribute, the attributes 1362 value is replaced. 1364 o If the target location is a multi-valued attribute and no filter 1365 is specified, the attribute and all values are replaced. 1367 o If the target location is a multi-valued attribute and a complex 1368 filter is specified comparing a "value", the values matched by the 1369 filter are replaced. 1371 o If the target location is a complex-multi-valued attribute and a 1372 complex filter is specified based on the attribute's sub- 1373 attributes, the matching records are replaced. 1375 o If the target location is a complex-multi-valued attribute with a 1376 complex filter and a specific sub-attribute (e.g. "addresses[type 1377 eq "work"].streetAddress" ), the matching sub-attribute of the 1378 matching record is replaced. 1380 The following example shows how to replace all the members of a group 1381 with a different members list in a single replace operation. Some 1382 text removed for readability ("..."): 1384 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1385 Host: example.com 1386 Accept: application/scim+json 1387 Content-Type: application/scim+json 1388 Authorization: Bearer h480djs93hd8 1389 If-Match: W/"a330bc54f0671c9" 1391 { 1392 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1393 "op":"replace", 1394 "path":"members", 1395 "value":[ 1396 { 1397 "display": "Babs Jensen", 1398 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1399 "value": "2819c223...413861904646" 1400 }, 1401 { 1402 "display": "James Smith", 1403 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1404 "value": "08e1d05d...473d93df9210" 1405 } 1406 ] 1407 } 1408 The following example shows how to change a User's entire "work" 1409 address. 1411 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1412 Host: example.com 1413 Accept: application/scim+json 1414 Content-Type: application/scim+json 1415 Authorization: Bearer h480djs93hd8 1416 If-Match: W/"a330bc54f0671c9" 1418 { 1419 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1420 "op":"replace", 1421 "path":"addresses[type eq \"work\"]", 1422 "value": 1423 { 1424 "type": "work", 1425 "streetAddress": "911 Universal City Plaza", 1426 "locality": "Hollywood", 1427 "region": "CA", 1428 "postalCode": "91608", 1429 "country": "US", 1430 "formatted": "911 Universal City Plaza\nHollywood, CA 91608 US", 1431 "primary": true 1432 } 1433 } 1435 The following example shows how to change a User's address. Since 1436 address does not have a value Sub-Attribute, the existing address 1437 must be removed and the modified address added. 1439 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1440 Host: example.com 1441 Accept: application/scim+json 1442 Content-Type: application/scim+json 1443 Authorization: Bearer h480djs93hd8 1444 If-Match: W/"a330bc54f0671c9" 1446 { 1447 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1448 "op":"replace", 1449 "path":"addresses[type eq \"work\"].streetAddress", 1450 "value":"911 Universal City Plaza" 1451 } 1453 3.4. Deleting Resources 1455 Clients request resource removal via DELETE. Service providers MAY 1456 choose not to permanently delete the resource, but MUST return a 404 1457 error code for all operations associated with the previously deleted 1458 Id. Service providers MUST also omit the resource from future query 1459 results. In addition the service provider MUST not consider the 1460 deleted resource in conflict calculation. For example if a User 1461 resource is deleted, a CREATE request for a User resource with the 1462 same userName as the previously deleted resource should not fail with 1463 a 409 error due to userName conflict. 1465 DELETE /Users/2819c223-7f76-453a-919d-413861904646 1466 Host: example.com 1467 Authorization: Bearer h480djs93hd8 1468 If-Match: W/"c310cd84f0281b7" 1470 In response to a successful delete, the server SHALL respond with 1471 successful HTTP status 204 (No Content). A non-normative example 1472 response: 1474 HTTP/1.1 204 No Content 1476 Example: client attempt to retrieve the previously deleted User 1478 GET /Users/2819c223-7f76-453a-919d-413861904646 1479 Host: example.com 1480 Authorization: Bearer h480djs93hd8 1482 Server Response: 1484 HTTP/1.1 404 NOT FOUND 1486 { 1487 "schemas": ["urn:scim:api:messages:2.0:Error"], 1488 "Errors":[ 1489 { 1490 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 1491 "code":"404" 1492 } 1493 ] 1494 } 1496 3.5. Bulk 1498 The SCIM bulk operation is an optional server feature that enables 1499 clients to send a potentially large collection of resource operations 1500 in a single request. The body of a a bulk operation contains a set 1501 of HTTP resource operations using one of the API supported HTTP 1502 methods; i.e., POST, PUT, PATCH or DELETE. 1504 Bulk requests are identified using the following URI: 1505 'urn:scim:api:messages:2.0:BulkRequest'. Bulk responses are 1506 identified using the following URI: 1507 'urn:scim:api:messages:2.0:BulkResponse'. Bulk requests and bulk 1508 responses share many attributes. Unless otherwise specified, each 1509 attribute below is present in both bulk requests and bulk responses. 1511 The following Singular Attribute is defined in addition to the common 1512 attributes defined in SCIM core schema. 1514 failOnErrors An Integer specifying the number of errors that the 1515 service provider will accept before the operation is terminated 1516 and an error response is returned. OPTIONAL in a request. Not 1517 valid in a response. 1519 The following Complex Multi-valued Attribute is defined in addition 1520 to the common attributes defined in core schema. 1522 Operations Defines operations within a bulk job. Each operation 1523 corresponds to a single HTTP request against a resource endpoint. 1524 REQUIRED. 1526 method The HTTP method of the current operation. Possible values 1527 are POST, PUT, PATCH or DELETE. REQUIRED. 1529 bulkId The transient identifier of a newly created resource, 1530 unique within a bulk request and created by the client. The 1531 bulkId serves as a surrogate resource id enabling clients to 1532 uniquely identify newly created resources in the Response and 1533 cross reference new resources in and across operations within a 1534 bulk request. REQUIRED when method is POST. 1536 version The current resource version. Version is REQUIRED if the 1537 service provider supports ETags and the method is PUT, DELETE, 1538 or PATCH. 1540 path The resource's relative path. If the method is POST the 1541 value must specify a resource type endpoint; e.g., /Users or 1542 /Groups whereas all other method values must specify the path 1543 to a specific resource; e.g., /Users/2819c223-7f76-453a-919d- 1544 413861904646. REQUIRED in a request. 1546 data The resource data as it would appear for a single POST, PUT 1547 or PATCH resource operation. REQUIRED in a request when method 1548 is POST, PUT and PATCH. 1550 location The resource endpoint URL. REQUIRED in a response, 1551 except in the event of a POST failure. 1553 status A complex type that contains information about the success 1554 or failure of one operation within the bulk job. REQUIRED in a 1555 response. 1557 code The HTTP response code that would have been returned if a 1558 a single HTTP request would have been used. REQUIRED. 1560 description A human readable error message. REQUIRED when an 1561 error occurred. 1563 If a bulk job is processed successfully the HTTP response code 200 OK 1564 MUST be returned, otherwise an appropriate HTTP error code MUST be 1565 returned. 1567 The service provider MUST continue performing as many changes as 1568 possible and disregard partial failures. The client MAY override 1569 this behavior by specifying a value for failOnErrors attribute. The 1570 failOnErrors attribute defines the number of errors that the service 1571 provider should accept before failing the remaining operations 1572 returning the response. 1574 To be able to reference a newly created resource the attribute bulkId 1575 MUST be specified when creating new resources. The bulkId is defined 1576 by the client as a surrogate identifier in a POST operation. The 1577 service provider MUST return the same bulkId together with the newly 1578 created resource. The bulkId can then be used by the client to map 1579 the service provider id with the bulkId of the created resource. 1581 There can be more then one operation per resource in each bulk job. 1582 The Service client MUST take notice of the unordered structure of 1583 JSON and the service provider can process operations in any order. 1584 For example, if the Service client sends two PUT operations in one 1585 request, the outcome is non-deterministic. 1587 The service provider response MUST include the result of all 1588 processed operations. A location attribute that includes the 1589 resource's end point MUST be returned for all operations excluding 1590 failed POSTs. The status attribute includes information about the 1591 success or failure of one operation within the bulk job. The 1592 attribute status MUST include the code attribute that holds the HTTP 1593 response code that would have been returned if a single HTTP request 1594 would have been used. If an error occurred the status MUST also 1595 include the description attribute containing a human readable 1596 explanation of the error. 1598 "status": { 1599 "code": "201" 1600 } 1602 The following is an example of a status in a failed operation. 1604 "status": { 1605 "code": "400", 1606 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1607 } 1609 The following example shows how to add, update, and remove a user. 1610 The failOnErrors attribute is set to '1' indicating the service 1611 provider should return on the first error. The POST operation's 1612 bulkId value is set to 'qwerty' enabling the client to match the new 1613 User with the returned resource id '92b725cd-9465-4e7d- 1614 8c16-01f8e146b87a'. 1616 POST /v2/Bulk 1617 Host: example.com 1618 Accept: application/scim+json 1619 Content-Type: application/scim+json 1620 Authorization: Bearer h480djs93hd8 1621 Content-Length: ... 1623 { 1624 "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], 1625 "failOnErrors":1, 1626 "Operations":[ 1627 { 1628 "method":"POST", 1629 "path":"/Users", 1630 "bulkId":"qwerty", 1631 "data":{ 1632 "schemas": ["urn:scim:api:messages:2.0:User"], 1633 "userName":"Alice" 1634 } 1635 }, 1636 { 1637 "method":"PUT", 1638 "path":"/Users/b7c14771-226c-4d05-8860-134711653041", 1639 "version":"W\/\"3694e05e9dff591\"", 1640 "data":{ 1641 "schemas": ["urn:scim:api:messages:2.0:User"], 1642 "id":"b7c14771-226c-4d05-8860-134711653041", 1643 "userName":"Bob" 1645 } 1646 }, 1647 { 1648 "method": "PATCH", 1649 "path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1650 "version": "W/\"edac3253e2c0ef2\"", 1651 "data": {[ 1652 { 1653 "op": "remove", 1654 "path": "nickName" 1655 }, 1656 { 1657 "op": "add", 1658 "path": "userName", 1659 "value": "Dave" 1660 } 1661 ]} 1662 }, 1663 { 1664 "method":"DELETE", 1665 "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1666 "version":"W\/\"0ee8add0a938e1a\"" 1667 } 1668 ] 1669 } 1671 The service provider returns the following response. 1673 HTTP/1.1 200 OK 1674 Content-Type: application/scim+json 1676 { 1677 "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], 1678 "Operations": [ 1679 { 1680 "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1681 "method": "POST", 1682 "bulkId": "qwerty", 1683 "version": "W\/\"oY4m4wn58tkVjJxK\"", 1684 "status": { 1685 "code": "201" 1686 } 1687 }, 1688 { 1689 "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 1690 "method": "PUT", 1691 "version": "W\/\"huJj29dMNgu3WXPD\"", 1692 "status": { 1693 "code": "200" 1694 } 1695 }, 1696 { 1697 "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1698 "method": "PATCH", 1699 "version": "W\/\"huJj29dMNgu3WXPD\"", 1700 "status": { 1701 "code": "200" 1702 } 1703 }, 1704 { 1705 "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1706 "method": "DELETE", 1707 "status": { 1708 "code": "204" 1709 } 1710 } 1711 ] 1712 } 1714 The following response is returned if an error occurred when 1715 attempting to create the User 'Alice'. The service provider stops 1716 processing the bulk operation and immediately returns a response to 1717 the client. The response contains the error and any successful 1718 results prior to the error. 1720 HTTP/1.1 200 OK 1721 Content-Type: application/scim+json 1723 { 1724 "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], 1725 "Operations": [ 1726 { 1727 "method": "POST", 1728 "bulkId": "qwerty", 1729 "status": { 1730 "code": "400", 1731 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1732 } 1733 } 1734 ] 1735 } 1737 If the failOnErrors attribute is not specified or the service 1738 provider has not reached the error limit defined by the client the 1739 service provider will continue to process all operations. The 1740 following is an example in which all operations failed. 1742 HTTP/1.1 200 OK 1743 Content-Type: application/scim+json 1745 { 1746 "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], 1747 "Operations": [ 1748 { 1749 "method": "POST", 1750 "bulkId": "qwerty", 1751 "status": { 1752 "code": "400", 1753 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1754 } 1755 }, 1756 { 1757 "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 1758 "method": "PUT", 1759 "status": { 1760 "code": "412", 1761 "description": "Failed to update as user changed on the server since you last retrieved it." 1762 } 1763 }, 1764 { 1765 "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1766 "method": "PATCH", 1767 "status": { 1768 "code": "412", 1769 "description": "Failed to update as user changed on the server since you last retrieved it." 1770 } 1771 }, 1772 { 1773 "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1774 "method": "DELETE", 1775 "status": { 1776 "code": "404", 1777 "description": "Specified resource; e.g., User, does not exist." 1778 } 1779 } 1780 ] 1781 } 1783 The client can, within one bulk operation, create a new User, a new 1784 Group and add the newly created User to the newly created Group. In 1785 order to add the new User to the Group the client must use the 1786 surrogate id attribute, bulkId, to reference the User. The bulkId 1787 attribute value must be pre-pended with the literal "bulkId:"; e.g., 1788 if the bulkId is 'qwerty' the value is "bulkId:qwerty". The service 1789 provider MUST replace the string "bulkId:qwerty" with the permanent 1790 resource id once created. 1792 The following example creates a User with the userName 'Alice' and a 1793 Group with the displayName 'Tour Guides' with Alice as a member. 1795 POST /v2/Bulk 1796 Host: example.com 1797 Accept: application/scim+json 1798 Content-Type: application/scim+json 1799 Authorization: Bearer h480djs93hd8 1800 Content-Length: ... 1802 { 1803 "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], 1804 "Operations": [ 1805 { 1806 "method": "POST", 1807 "path": "/Users", 1808 "bulkId": "qwerty", 1809 "data": { 1810 "schemas": ["urn:scim:schemas:core:2.0:User"], 1811 "userName": "Alice" 1812 } 1813 }, 1814 { 1815 "method": "POST", 1816 "path": "/Groups", 1817 "bulkId": "ytrewq", 1818 "data": { 1819 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1820 "displayName": "Tour Guides", 1821 "members": [ 1822 { 1823 "type": "user", 1824 "value": "bulkId:qwerty" 1825 } 1826 ] 1827 } 1828 } 1829 ] 1830 } 1832 The service provider returns the following response. 1834 HTTP/1.1 200 OK 1835 Content-Type: application/scim+json 1837 { 1838 "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], 1839 "Operations": [ 1840 { 1841 "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1842 "method": "POST", 1843 "bulkId": "qwerty", 1844 "version": "W\/\"4weymrEsh5O6cAEK\"", 1845 "status": { 1846 "code": "201" 1847 } 1848 }, 1849 { 1850 "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1851 "method": "POST", 1852 "bulkId": "ytrewq", 1853 "version": "W\/\"lha5bbazU3fNvfe5\"", 1854 "status": { 1855 "code": "201" 1856 } 1857 } 1858 ] 1859 } 1861 A subsequent request for the 'Tour Guides' Group ('e9e30dba-f08f- 1862 4109-8486-d5c6a331660a') returns the following: 1864 GET /v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1865 Host: example.com 1866 Accept: application/scim+json 1867 Authorization: Bearer h480djs93hd8 1869 HTTP/1.1 200 OK 1870 Content-Type: application/scim+json 1871 Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1872 ETag: W/"lha5bbazU3fNvfe5" 1874 { 1875 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1876 "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", 1877 "displayName": "Tour Guides", 1878 "meta": { 1879 "resourceType": "Group", 1880 "created": "2011-08-01T18:29:49.793Z", 1881 "lastModified": "2011-08-01T20:31:02.315Z", 1882 "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1883 "version": "W\/\"lha5bbazU3fNvfe5\"" 1884 }, 1885 "members": [ 1886 { 1887 "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", 1888 "$ref": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1889 "type": "User" 1890 } 1891 ] 1892 } 1894 Extensions that include references to other resources MUST be handled 1895 in the same way by the service provider. The following example uses 1896 the bulkId attribute within the enterprise extension managerId 1897 attribute. 1899 POST /v2/Bulk 1900 Host: example.com 1901 Accept: application/scim+json 1902 Content-Type: application/scim+json 1903 Authorization: Bearer h480djs93hd8 1904 Content-Length: ... 1906 { 1907 "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], 1908 "Operations": [ 1909 { 1910 "method": "POST", 1911 "path": "/Users", 1912 "bulkId": "qwerty", 1913 "data": { 1914 "schemas": ["urn:scim:schemas:core:2.0:User"], 1915 "userName": "Alice" 1916 } 1917 }, 1918 { 1919 "method": "POST", 1920 "path": "/Users", 1921 "bulkId": "ytrewq", 1922 "data": { 1923 "schemas": [ 1924 "urn:scim:schemas:core:2.0:User", 1925 "urn:scim:schemas:extension:enterprise:2.0:User" 1926 ], 1927 "userName": "Bob", 1928 "urn:scim:schemas:extension:enterprise:2.0:User": { 1929 "employeeNumber": "11250", 1930 "manager": { 1931 "managerId": "batchId:qwerty", 1932 "displayName": "Alice" 1933 } 1934 } 1935 } 1936 } 1937 ] 1938 } 1940 The service provider MUST try to resolve circular cross references 1941 between resources in a single bulk job but MAY stop after a failed 1942 attempt and instead return the status code 409 Conflict. The 1943 following example exhibits the potential conflict. 1945 POST /v2/Bulk 1946 Host: example.com 1947 Accept: application/scim+json 1948 Content-Type: application/scim+json 1949 Authorization: Bearer h480djs93hd8 1950 Content-Length: ... 1952 { 1953 "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], 1954 "Operations": [ 1955 { 1956 "method": "POST", 1957 "path": "/Groups", 1958 "bulkId": "qwerty", 1959 "data": { 1960 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1961 "displayName": "Group A", 1962 "members": [ 1963 { 1964 "type": "group", 1965 "value": "bulkId:ytrewq" 1966 } 1967 ] 1968 } 1969 }, 1970 { 1971 "method": "POST", 1972 "path": "/Groups", 1973 "bulkId": "ytrewq", 1974 "data": { 1975 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1976 "displayName": "Group B", 1977 "members": [ 1978 { 1979 "type": "group", 1980 "value": "bulkId:qwerty" 1981 } 1982 ] 1983 } 1984 } 1985 ] 1986 } 1988 If the service provider resolved the above circular references the 1989 following is returned from a subsequent GET request. 1991 GET /v2/Groups?filter=displayName sw 'Group' 1992 Host: example.com 1993 Accept: application/scim+json 1994 Authorization: Bearer h480djs93hd8 1996 HTTP/1.1 200 OK 1997 Content-Type: application/scim+json 1999 { 2000 "schemas": ["urn:scim:api:messages:2.0:ListResponse"], 2001 "totalResults": 2, 2002 "Resources": [ 2003 { 2004 "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 2005 "schemas": ["urn:scim:schemas:core:2.0:Group"], 2006 "displayName": "Group A", 2007 "meta": { 2008 "resourceType": "Group", 2009 "created": "2011-08-01T18:29:49.793Z", 2010 "lastModified": "2011-08-01T18:29:51.135Z", 2011 "location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 2012 "version": "W\/\"mvwNGaxB5SDq074p\"" 2013 }, 2014 "members": [ 2015 { 2016 "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 2017 "$ref": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 2018 "type": "Group" 2019 } 2020 ] 2021 }, 2022 { 2023 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 2024 "schemas": ["urn:scim:schemas:core:2.0:Group"], 2025 "displayName": "Group B", 2026 "meta": { 2027 "resourceType": "Group", 2028 "created": "2011-08-01T18:29:50.873Z", 2029 "lastModified": "2011-08-01T18:29:50.873Z", 2030 "location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 2031 "version": "W\/\"wGB85s2QJMjiNnuI\"" 2032 }, 2033 "members": [ 2034 { 2035 "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 2036 "$ref": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 2037 "type": "Group" 2038 } 2039 ] 2040 } 2041 ] 2042 } 2043 The service provider MUST define the maximum number of operations and 2044 maximum payload size a client may send in a single request. If 2045 either limits are exceeded the service provider MUST return the HTTP 2046 response code 413 Request Entity Too Large. The returned response 2047 MUST specify the limit exceeded in the body of the error response. 2049 The following example the client sent a request exceeding the service 2050 provider's max payload size of 1 megabyte. 2052 POST /v2/Bulk 2053 Host: example.com 2054 Accept: application/scim+json 2055 Content-Type: application/scim+json 2056 Authorization: Bearer h480djs93hd8 2057 Content-Length: 4294967296 2059 ... 2061 HTTP/1.1 413 Request Entity Too Large 2062 Content-Type: application/scim+json 2063 Location: https://example.com/v2/Bulk/yfCrVJhFIJagAHj8 2065 { 2066 "schemas":["urn:scim:api:messages:2.0:Error"], 2067 "Errors":[ 2068 { 2069 "description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).", 2070 "code":"413" 2071 } 2072 ] 2073 } 2075 3.6. Data Input/Output Formats 2077 Servers MUST accept requests and respond with JSON structured 2078 responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default 2079 encoding format. 2081 Clients using other encodings MUST specify the format in which the 2082 data is submitted via HTTP header "Content-Type" as specified in 2083 Section 3.1.1.5 [RFC7231] and MAY specify the desired response data 2084 format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g., 2085 "Accept: application/scim+json" or via URI suffix; e.g., 2086 GET /Users/2819c223-7f76-453a-919d-413861904646.scim 2087 Host: example.com 2089 Service providers MUST support the accept header "Accept: 2090 application/scim+json" and SHOULD support header "Accept: 2091 application/json" both of which specify JSON documents conforming to 2092 [RFC7159]. The format defaults to "application/scim+json" if no 2093 format is specified. 2095 Singular attributes are encoded as string name-value-pairs in JSON; 2096 e.g., 2098 "attribute": "value" 2100 Multi-valued attributes in JSON are encoded as arrays; e.g., 2102 "attributes": [ "value1", "value2" ] 2104 Elements with nested elements are represented as objects in JSON; 2105 e.g, 2107 "attribute": { "subattribute1": "value1", "subattribute2": "value2" } 2109 3.7. Additional Operation Response Parameters 2111 For any SCIM operation where a resource representation is returned 2112 (e.g. HTTP GET), the attributes normally returned are defined as the 2113 minimum attribute set plus default attributes. The minimum set are 2114 those attributes whose schema have "returned" set to "always". The 2115 defaut attribute set are those attributes whose schema have 2116 "returned" set to "default". 2118 Clients MAY request a partial resource representation on any 2119 operation that returns a resource within the response by specifying 2120 either of the mutually exclusive URL query parameters "attributes" OR 2121 "excludedAtributes" as follows: 2123 attributes When specified, each resource returned MUST contain the 2124 minimal set of resource attributes and MUST contain no other 2125 attributes or sub-attributes other than those explicitly 2126 requested. The query parameter attributes value is a comma 2127 separated list of resource attribute names in standard 2128 attribute notation (Section 3.8) form (e.g. userName, name, 2129 emails). 2131 excludedAttributes When specified, each resource returned MUST 2132 contain the minimal set of resource attributes. 2133 Additionally, the default set of attributes minus those 2134 attributes listed in "excludedAttributes" are also returned. 2135 The query parameter attributes value is a comma separated 2136 list of resource attribute names in standard attribute 2137 notation (Section 3.8) form (e.g. userName, name, emails). 2139 . 2141 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName 2142 Host: example.com 2143 Accept: application/json 2144 Authorization: Bearer h480djs93hd8 2146 Giving the response 2148 HTTP/1.1 200 OK 2149 Content-Type: application/json 2150 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2151 ETag: W/"a330bc54f0671c9" 2153 { 2154 "schemas":["urn:scim:schemas:core:2.0:User"], 2155 "id":"2819c223-7f76-453a-919d-413861904646", 2156 "userName":"bjensen", 2157 "meta":{ 2158 "resourceType": "User", 2159 "created":"2011-08-01T18:29:49.793Z", 2160 "lastModified":"2011-08-01T18:29:49.793Z", 2161 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2162 "version":"W\/\"a330bc54f0671c9\"" 2163 } 2164 } 2166 3.8. Attribute Notation 2168 All operations share a common scheme for referencing simple and 2169 complex attributes. In general, attributes are identified by 2170 prefixing the attribute name with its schema URN separated by a ':' 2171 character; e.g., the core User resource attribute 'userName' is 2172 identified as 'urn:scim:schemas:core:2.0:User:userName'. Clients MAY 2173 omit core schema attribute URN prefixes though MUST fully qualify 2174 extended attributes with the associated resource URN; e.g., the 2175 attribute 'age' defined in 'urn:hr:schemas:user' is fully encoded as 2176 'urn:hr:schemas:user:age'. A Complex attributes' Sub-Attributes are 2177 referenced via nested, dot ('.') notation; i.e., {urn}:{Attribute 2178 name}.{Sub-Attribute name}. For example, the fully qualified path for 2179 a User's givenName is urn:scim:schemas:core:2.0:User:name.givenName 2180 All facets (URN, attribute and Sub-Attribute name) of the fully 2181 encoded Attribute name are case insensitive. 2183 3.9. "/Me" Authenticated Subject Alias 2185 A client MAY use a URL of the form "/Me" as an URL alias 2186 for the User or other resource associated with the currently 2187 authenticated subject for any SCIM operation. A service provider MAY 2188 respond in ONE of 3 ways: 2190 o A service provider that does NOT support this feature SHOULD 2191 respond with status 403 (FORBIDDEN). 2193 o A service provider MAY choose to redirect the client using HTTP 2194 status 308 to the resource associated with the authenticated 2195 subject. The client MAY then repeat the request at the indicated 2196 location. 2198 o A service provider MAY process the SCIM request directly. In any 2199 response, the HTTP "Location" header MUST be the permanent 2200 location of the aliased resource associated with the authenticated 2201 subject. 2203 3.10. HTTP Response Codes 2205 The SCIM Protocol uses the response status codes defined in HTTP 2206 Section 6 [RFC7231] to indicate operation success or failure. In 2207 addition to returning a HTTP response code implementers MUST return 2208 the errors in the body of the response in the client requested format 2209 containing the error response and, per the HTTP specification, human- 2210 readable explanations. Error responses are identified using the 2211 following URI: 'urn:scim:api:messages:2.0:Error'. The following 2212 multi-valued attribute is defined in addition to those attributes 2213 defined in SCIM Core Schema: 2215 Errors The list of errors encountered by the service provider. The 2216 value attribute is a complex type with the following sub- 2217 attributes. 2219 description A human-readable explanation of the error. REQUIRED. 2221 code A string indicating the HTTP response code. REQUIRED. 2223 Implementers SHOULD handle the identified errors as described below. 2225 +--------------+---------------+------------------------------------+ 2226 | Code | Applicability | Suggested Explanation | 2227 +--------------+---------------+------------------------------------+ 2228 | 307 | GET, POST, | The client is directed to repeat | 2229 | TEMPORARY | PUT, PATCH, | the same HTTP request at the | 2230 | REDIRECT | DELETE | location identified. The client | 2231 | | | SHOULD NOT use the location | 2232 | | | provided in the response as a | 2233 | | | permanent reference to the | 2234 | | | resource and SHOULD continue to | 2235 | | | use the original request URI | 2236 | | | [RFC7231]. | 2237 | 308 | GET, POST, | The client is directed to repeat | 2238 | PERMANENT | PUT, PATCH, | the same HTTP request at the | 2239 | REDIRECT | DELETE | location identified. The client | 2240 | | | SHOULD use the location provided | 2241 | | | in the response as the permanent | 2242 | | | reference to the resource | 2243 | | | [I-D.reschke-http-status-308]. | 2244 | 400 BAD | GET, POST, | Request is unparseable, | 2245 | REQUEST | PUT, PATCH, | syntactically incorrect, or | 2246 | | DELETE | violates schema | 2247 | 401 | GET, POST, | Authorization failure | 2248 | UNAUTHORIZED | PUT, PATCH, | | 2249 | | DELETE | | 2250 | 403 | GET, POST, | Server does not support requested | 2251 | FORBIDDEN | PUT, PATCH, | operation | 2252 | | DELETE | | 2253 | 404 NOT | GET, PUT, | Specified resource; e.g., User, | 2254 | FOUND | PATCH, DELETE | does not exist | 2255 | 409 CONFLICT | POST, PUT, | The specified version number does | 2256 | | PATCH, DELETE | not match the resource's latest | 2257 | | | version number or a service | 2258 | | | provider refused to create a new, | 2259 | | | duplicate resource | 2260 | 412 | PUT, PATCH,D | Failed to update as resource {id} | 2261 | PRECONDITION | ELETE | changed on the server last | 2262 | FAILED | | retrieved | 2263 | 413 REQUEST | POST | {"maxOperations": | 2264 | ENTITY TOO | | 1000,"maxPayload": 1048576} | 2265 | LARGE | | | 2266 | 500 INTERNAL | GET, POST, | An internal error. Implementers | 2267 | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive | 2268 | | DELETE | debugging advice | 2269 | 501 NOT | GET, POST, | Service Provider does not support | 2270 | IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH | 2271 | | DELETE | | 2272 +--------------+---------------+------------------------------------+ 2274 Table 7: Defined error cases 2276 Error example in response to a non-existent GET request. 2278 HTTP/1.1 404 NOT FOUND 2280 { 2281 "schemas": ["urn:scim:api:messages:2.0:Error"], 2282 "Errors":[ 2283 { 2284 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 2285 "code":"404" 2286 } 2287 ] 2288 } 2290 3.11. API Versioning 2292 The Base URL MAY be appended with a version identifier as a separate 2293 segment in the URL path. At this time of this specification, the 2294 identifier is 'v2'. If specified, the version identifier MUST appear 2295 in the URL path immediately preceding the resource endpoint and 2296 conform to the following scheme: the character 'v' followed by the 2297 desired SCIM version number; e.g., a version 'v2' User request is 2298 specified as /v2/Users. When specified service providers MUST 2299 perform the operation using the desired version or reject the 2300 request. When omitted service providers SHOULD perform the operation 2301 using the most recent API supported by the service provider. 2303 3.12. Versioning Resources 2305 The API supports resource versioning via standard HTTP ETags 2306 Section 2.3 [RFC7233]. Service providers MAY support weak ETags as 2307 the preferred mechanism for performing conditional retrievals and 2308 ensuring clients do not inadvertently overwrite each others changes, 2309 respectively. When supported SCIM ETags MUST be specified as an HTTP 2310 header and SHOULD be specified within the 'version' attribute 2311 contained in the resource's 'meta' attribute. 2313 Example: 2315 POST /Users HTTP/1.1 2316 Host: example.com 2317 Content-Type: application/json 2318 Authorization: Bearer h480djs93hd8 2319 Content-Length: ... 2321 { 2322 "schemas":["urn:scim:schemas:core:2.0:User"], 2323 "userName":"bjensen", 2324 "externalId":"bjensen", 2325 "name":{ 2326 "formatted":"Ms. Barbara J Jensen III", 2327 "familyName":"Jensen", 2328 "givenName":"Barbara" 2329 } 2330 } 2332 The server responds with an ETag in the response header and meta 2333 structure. 2335 HTTP/1.1 201 Created 2336 Content-Type: application/json 2337 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2338 ETag: W/"e180ee84f0671b1" 2340 { 2341 "schemas":["urn:scim:schemas:core:2.0:User"], 2342 "id":"2819c223-7f76-453a-919d-413861904646", 2343 "meta":{ 2344 "resourceType":"User", 2345 "created":"2011-08-01T21:32:44.882Z", 2346 "lastModified":"2011-08-01T21:32:44.882Z", 2347 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2348 "version":"W\/\"e180ee84f0671b1\"" 2349 }, 2350 "name":{ 2351 "formatted":"Ms. Barbara J Jensen III", 2352 "familyName":"Jensen", 2353 "givenName":"Barbara" 2354 }, 2355 "userName":"bjensen" 2356 } 2358 With the returned ETag, clients MAY choose to retrieve the resource 2359 only if the resource has been modified. 2361 Conditional retrieval example using If-None-Match Section 3.2 2362 [RFC7233] header: 2364 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName 2365 Host: example.com 2366 Accept: application/json 2367 Authorization: Bearer h480djs93hd8 2368 If-None-Match: W/"e180ee84f0671b1" 2370 If the resource has not changed the service provider simply returns 2371 an empty body with a 304 "Not Modified" response code. 2373 If the service providers supports versioning of resources the client 2374 MAY supply an If-Match Section 3.1 [RFC7233] header for PUT and PATCH 2375 operations to ensure that the requested operation succeeds only if 2376 the supplied ETag matches the latest service provider resource; e.g., 2377 If-Match: W/"e180ee84f0671b1" 2379 4. Preparation and Comparison of Internationalized Strings 2381 To increase the likelihood that the input and comparison of unicode 2382 usernames and passwords will work in ways that make sense for typical 2383 users throughout the world there are special string preparation and 2384 comparison methods (PRECIS) that MUST be followed for usernames and 2385 passwords. Before comparing or evaluating uniqueness of a "userName" 2386 or "password" attribute, service providers MUST use the "PRECIS" 2387 profile described in Sections 4 and 5 respectively of 2388 [I-D.ietf-precis-saslprepbis] and is based on the "PRECIS" framework 2389 specification [I-D.ietf-precis-framework]. 2391 5. Multi-Tenancy 2393 A single service provider may expose the SCIM protocol to multiple 2394 clients. Depending on the nature of the service, the clients may 2395 have authority to access and alter resources initially created by 2396 other clients. Alternatively, clients may expect to access disjoint 2397 sets of resources, and may expect that their resources are 2398 inaccessible by other clients. These scenarios are called "multi- 2399 tenancy", where each client is understood to be or represent a 2400 "tenant" of the service provider. Clients may also be multi- 2401 tenanted. 2403 The following common cases may occur: 2405 1. All clients share all resources (no tenancy) 2407 2. Each single client creates and accesses a private subset of 2408 resources (1 client:1 Tenant) 2410 3. Sets of clients share sets of resources (M clients:1 Tenant) 2411 4. One client to Multiple Tenants (1 client:M Tenants) 2413 Service providers may implement any subset of the above cases. 2415 Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a 2416 scheme for multi-tenancy. 2418 The SCIM protocol does not prescribe the mechanisms whereby clients 2419 and service providers interact for: 2421 o Registering or provisioning Tenants 2423 o Associating a subset of clients with a subset of the Tenants 2425 o Indicating which tenant is associated with the data in a request 2426 or response, or indicating which Tenant is the subject of a query 2428 5.1. Associating Clients to Tenants 2430 The service provider MAY use the authentication mechanism (Section 2) 2431 to determine the identity of the client, and thus infer the 2432 associated Tenant. 2434 For implementations where a client is associated with more than one 2435 Tenant, the service provider MAY use one of the following methods for 2436 explicit specification of the Tenant. 2438 If any of these methods of allowing the client to explicitly specify 2439 the Tenant are employed, the service provider should ensure that 2440 access controls are in place to prevent or allow cross-tenant use 2441 cases. 2443 The service provider should consider precedence in cases where a 2444 client may explicitly specify a Tenant while being implicitly 2445 associated with a different Tenant. 2447 In all of these methods, the {tenant_id} is a unique identifier for 2448 the Tenant as defined by the service provider. 2450 o A URL prefix: "https://www.example.com/Tenants/{tenant_id}/v2/ 2451 Users" 2453 o A sub-domain: "https://{tenant_id}.example.com/v2/Groups" 2455 o The service provider may recognize a {tenant_id} provided by the 2456 client in an HTTP Header as the indicator of the desired target 2457 Tenant. 2459 5.2. SCIM Identifiers with Multiple Tenants 2461 Considerations for a Multi-Tenant Implementation: 2463 The service provider may choose to implement SCIM ids which are 2464 unique across all resources for all Tenants, but this is not 2465 required. 2467 The externalId, defined by the client, is required to be unique ONLY 2468 within the resources associated with the associated Tenant. 2470 6. Security Considerations 2472 6.1. TLS Support 2474 The SCIM Protocol layers on top of Hypertext Transfer Protocol and 2475 thus subject to the security considerations of HTTP Section 9 2476 [RFC7230] and its related specifications. 2478 SCIM resources (e.g., Users and Groups) can contain sensitive 2479 information. Therefore, SCIM clients and service providers MUST 2480 implement TLS. Which version(s) ought to be implemented will vary 2481 over time, and depend on the widespread deployment and known security 2482 vulnerabilities at the time of implementation. At the time of this 2483 writing, TLS version 1.2 [RFC5246] is the most recent version, but 2484 has very limited actual deployment, and might not be readily 2485 available in implementation toolkits. TLS version 1.0 [RFC2246] is 2486 the most widely deployed version, and will give the broadest 2487 interoperability. 2489 6.2. Request URI Information Leakage 2491 Clients requesting information using query filters using HTTP GET 2492 SHOULD give consideration to the information content of the filters 2493 and whether their exposure in a URI would represent a breach of 2494 security or confidentiality through leakage in a web browsers or 2495 server logs. This is particularly true for information that is 2496 legally considered "personally identifiable information" or is 2497 otherwise restricted by privacy laws. In these situations to ensure 2498 maximum security and confidentiality, clients SHOULD query using HTTP 2499 POST (see Section 3.2.3 ). 2501 Servers that receive HTTP GET requests using filters that contain 2502 restricted or confidential information SHOULD respond with HTTP 2503 status 403 indicating the operation is FORBIDDEN. A detialed error, 2504 "confidential_restricted" may be returned indicating the request must 2505 be submitted using POST. A non-normative example: 2507 HTTP/1.1 403 FORBIDDEN 2509 { 2510 "schemas": ["urn:scim:api:messages:2.0:Error"], 2511 "Errors":[ 2512 { 2513 "description":"Query filter involving 'name' is restricted or confidential", 2514 "error":"confidential_restricted" 2515 } 2516 ] 2517 } 2519 6.3. Case Insensitive Comparision & International Languages 2521 When comparing unicode strings such as in query filters or testing 2522 for uniqueness of usernames and passwords, strings MUST be 2523 appopriately prepared before comparison. See Section 4. 2525 6.4. Universal Identifiers 2527 7. IANA Considerations 2529 7.1. Media Type Registration 2531 To: ietf-types@iana.org 2533 Subject: Registration of media type application/scim+json 2535 Type name: application 2537 Subtype name: scim+json 2539 Required parameters: none 2541 Optional parameters: none 2543 Encoding considerations: 8bit 2545 Security considerations: See Section 6 2547 Interoperability considerations: The "application/scim+json" media 2548 type is intended to identify JSON structure data that conforms to 2549 the SCIM 2 api and schema specifications. Older versions of SCIM 2550 are known to informally use "application/json". 2552 Published specification: [[this document]] 2553 Applications that use this media type: It is expected that 2554 applications that use this type may be special purpose 2555 applications intended for inter-domain provisioning. Clients may 2556 also be applications (e.g. mobile applications) that need to use 2557 SCIM for self-registration of user accounts. SCIM services may be 2558 offered by web applications wishin to offer support for standards 2559 based provisioning or may be a dedicated SCIM service provider 2560 such as a "cloud directory". Content may be treated as equivalent 2561 to "application/json" type for the purpose of displaying in web 2562 browsers. 2564 Additional information: 2566 Magic number(s): 2568 File extension(s): .scim .scm 2570 Macintosh file type code(s): 2572 Person & email address to contact for futher information: SCIM 2573 mailing list "" 2575 Intended usage: COMMON* (see restrictions) 2577 Restrictions on usage: For most client types, it is sufficient to 2578 recognize the content as equivalent to "application/json". 2579 Applications intending to use the SCIM API SHOULD use the 2580 application/scim+json media type. 2582 Author: Phil Hunt 2584 Change controller: IETF 2586 7.2. SCIM API Message Schema Registry 2588 As per the IANA SCIM Schema Registry in [I-D.ietf-scim-core-schema], 2589 the following registers and extends the SCIM Schema Registry to 2590 define API request/response JSON schema URN identifier prefix of 2591 "urn:scim:api:messages:2.0" which is part of the URN sub-Namespace 2592 for SCIM. There is no specific associated resource type. 2594 +---------------------------------------+-----------+---------------+ 2595 | Schema URI | Name | Reference | 2596 +---------------------------------------+-----------+---------------+ 2597 | urn:scim:api:messages:2.0:ListRespons | List/Quer | See Section | 2598 | e | y | 3.2.2 | 2599 | | Response | | 2600 | urn:scim:api:messages:2.0:SearchReque | POST | See Section | 2601 | st | Query | 3.2.3 | 2602 | | Request | | 2603 | urn:scim:api:messages:2.0:PatchOp | Patch | See Section | 2604 | | Operation | 3.3.2 | 2605 | urn:scim:api:messages:2.0:BulkRequest | Bulk Oper | See Section | 2606 | | ations | 3.5 | 2607 | | Request | | 2608 | urn:scim:api:messages:2.0:BulkRespons | Bulk Oper | See Section | 2609 | e | ations | 3.5 | 2610 | | Response | | 2611 | urn:scim:api:messages:2.0:Error | Error | See Section | 2612 | | Response | 3.10 | 2613 +---------------------------------------+-----------+---------------+ 2615 SCIM Schema URIs for Data Resources 2617 8. References 2619 8.1. Normative References 2621 [I-D.ietf-precis-saslprepbis] 2622 Saint-Andre, P. and A. Melnikov, "Preparation and 2623 Comparison of Internationalized Strings Representing 2624 Usernames and Passwords", draft-ietf-precis-saslprepbis-07 2625 (work in progress), March 2014. 2627 [I-D.ietf-scim-core-schema] 2628 Grizzle, K., Hunt, P., Wahlstroem, E., and C. Mortimore, 2629 "System for Cross-Domain Identity Management: Core 2630 Schema", draft-ietf-scim-core-schema-05 (work in 2631 progress), May 2014. 2633 [IANA.Language] 2634 Internet Assigned Numbers Authority (IANA), "Language 2635 Subtag Registry", 2005. 2637 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2638 Requirement Levels", BCP 14, RFC 2119, March 1997. 2640 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2641 RFC 2246, January 1999. 2643 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2644 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2645 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2647 [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of 2648 Internationalized Strings ("stringprep")", RFC 3454, 2649 December 2002. 2651 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2652 10646", STD 63, RFC 3629, November 2003. 2654 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2655 Resource Identifier (URI): Generic Syntax", STD 66, RFC 2656 3986, January 2005. 2658 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2659 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2661 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2662 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2664 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 2665 5789, March 2010. 2667 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 2668 Framework: Bearer Token Usage", RFC 6750, October 2012. 2670 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 2671 Interchange Format", RFC 7159, March 2014. 2673 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2674 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 2675 2014. 2677 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2678 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 2680 [RFC7233] Fielding, R., Lafon, Y., and J. Reschke, "Hypertext 2681 Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, 2682 June 2014. 2684 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2685 (HTTP/1.1): Authentication", RFC 7235, June 2014. 2687 8.2. Informative References 2689 [I-D.ietf-precis-framework] 2690 Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 2691 Preparation and Comparison of Internationalized Strings in 2692 Application Protocols", draft-ietf-precis-framework-17 2693 (work in progress), May 2014. 2695 [I-D.reschke-http-status-308] 2696 Reschke, J., "The Hypertext Transfer Protocol (HTTP) 2697 Status Code 308 (Permanent Redirect)", draft-reschke-http- 2698 status-308-07 (work in progress), March 2012. 2700 [OpenSearch] 2701 Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . 2703 [Order-Operations] 2704 Wikipedia, "Order of Operations: Programming Languages", . 2706 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 2707 Languages", BCP 18, RFC 2277, January 1998. 2709 [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation 2710 (JSON) Patch", RFC 6902, April 2013. 2712 Appendix A. Contributors 2714 Samuel Erdtman (samuel@erdtman.se) 2716 Patrick Harding (pharding@pingidentity.com) 2718 Appendix B. Acknowledgments 2720 The editors would like to acknowledge the contribution and work of 2721 the past draft editors: 2723 Trey Drake, UnboundID 2725 Chuck Mortimore, Salesforce 2727 The editor would like to thank the participants in the the SCIM 2728 working group for their support of this specification. 2730 Appendix C. Change Log 2732 [[This section to be removed prior to publication as an RFC]] 2734 Draft 02 - KG - Addition of schema extensibility 2735 Draft 03 - PH - Revisions based on following tickets: 2737 24 - Add filter negation 2739 39 - Clarification on response for DELETE 2741 42 - Make root searches optional 2743 49 - Add "ew" filter 2745 50 - Filters for multi-valued complex attributes 2747 51 - Search by Schema 2749 53 - Standard use of term client (some was consumer) 2751 55 - Redirect support (3xx) 2753 56 - Make manager attribute consistent with other $ref attrs 2755 57 - Update all "/v1" examples to '/v2" 2757 59 - Fix capitalization per IETF editor practices 2759 60 - Changed tags to normal and tags 2761 Draft 04 - PH - Revisions based on the following tickets: 2763 18 - New PATCH command based on JSON Patch (RFC6902) 2765 - Provided ABNF specification for filters (used in PATCH) 2767 - Updated references to RFC4627 to RFC7159 2769 Draft 05 - PH - Revisions based on the following tickets: 2771 03 - Support for excludedAttributes parameter 2773 13 - Change client use of Etags from MUST to MAY (correction) 2775 23 - Clarifications regarding case exact processing. 2777 41 - Add IANA considerations 2779 65 - Removed X-HTTP-Method-Override support 2781 69 - Added clarifications to intro to align with draft-nottingham- 2782 uri-get-off-my-lawn 2783 70 - Remove SCIM_TENANT_ID header 2785 72 - Added text to indicate UTF-8 is default and mandatory 2786 encoding format per BCP18 2788 74 - Added security considerations for using GET with confidential 2789 attribute filters 2791 - corrected error response in JSON PATCH operation 2793 Draft 06 - PH - Revisions based on the following tickets and 2794 editorial changes 2796 41 - Revised content types from application/json to application/ 2797 scim+json, registered API schemas 2799 63 - Revised uri schema prefixes for API json message schemas 2801 66 - Updated references for RFC2616 to HTTPbis 2803 75 - Added security considerations for International Strings and 2804 "PRECIS" support 2806 76 - Clarified handling of PUT (& POST) with regards to mutability 2807 and default values 2809 - Corrected version numbers in sec 3.11 API Versioning to v2 (from 2810 v1) 2812 - Clarified that no filter matches should return success 2813 totalResults=0 2815 Authors' Addresses 2817 Phil Hunt (editor) 2818 Oracle Corporation 2820 Email: phil.hunt@yahoo.com 2822 Kelly Grizzle 2823 SailPoint 2825 Email: kelly.grizzle@sailpoint.com 2826 Morteza Ansari 2827 Cisco 2829 Email: morteza.ansari@cisco.com 2831 Erik Wahlstroem 2832 Technology Nexus 2834 Email: erik.wahlstrom@nexussafe.com 2836 Chuck Mortimore 2837 Salesforce.com 2839 Email: cmortimore@salesforce.com