idnits 2.17.1 draft-ietf-scim-api-07.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 35 instances of too long lines in the document, the longest one being 28 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: +------------+----------------------------+-------------------------+ | Parameter | Description | Default | +------------+----------------------------+-------------------------+ | startIndex | The 1-based index of the | 1 | | | first search result. A | | | | value less than 1 SHALL be | | | | interpreted as 1. | | | count | Non-negative Integer. | None. When specified | | | Specifies the desired | the service provider | | | maximum number of search | MUST not return more | | | results per page; e.g., | results than specified | | | 10. A negative value SHALL | though MAY return fewer | | | be interpreted as "0". A | results. If | | | value of "0" indicates no | unspecified, the | | | resource results are to be | maximum number of | | | returned except for | results is set by the | | | "totalResults". | service 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 (July 3, 2014) is 3585 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 2715, but no explicit reference was found in the text == Unused Reference: 'RFC3454' is defined on line 2719, but no explicit reference was found in the text == Unused Reference: 'RFC2277' is defined on line 2778, 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-06 ** 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: January 4, 2015 SailPoint 6 M. Ansari 7 Cisco 8 E. Wahlstroem 9 Technology Nexus 10 C. Mortimore 11 Salesforce 12 July 3, 2014 14 System for Cross-Domain Identity Management:Protocol 15 draft-ietf-scim-api-07 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 January 4, 2015. 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 . . . . . . . . . . . . . . . . . . . 23 78 3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 24 79 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 26 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 Error Responses . . . . . . . . . . . . . . . . . . 53 87 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 57 88 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 57 89 4. Preparation and Comparison of Internationalized Strings . . . 59 90 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 59 91 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 60 92 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 61 93 6. Security Considerations . . . . . . . . . . . . . . . . . . . 61 94 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 61 95 6.2. Request URI Information Leakage . . . . . . . . . . . . . 61 96 6.3. Case Insensitive Comparision & International Languages . 62 97 6.4. Universal Identifiers . . . . . . . . . . . . . . . . . . 62 98 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 62 99 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 62 100 7.2. SCIM API Message Schema Registry . . . . . . . . . . . . 63 101 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 64 102 8.1. Normative References . . . . . . . . . . . . . . . . . . 64 103 8.2. Informative References . . . . . . . . . . . . . . . . . 66 104 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 66 105 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 66 106 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 66 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 68 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 (see following 409 sub-sections). Service providers MAY support additional query 410 parameters not specified here, and Providers SHOULD ignore any query 411 parameters they don't 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 of the | 1 | 769 | | first search result. A | | 770 | | value less than 1 SHALL be | | 771 | | interpreted as 1. | | 772 | count | Non-negative Integer. | None. When specified | 773 | | Specifies the desired | the service provider | 774 | | maximum number of search | MUST not return more | 775 | | results per page; e.g., | results than specified | 776 | | 10. A negative value SHALL | though MAY return fewer | 777 | | be interpreted as "0". A | results. If | 778 | | value of "0" indicates no | unspecified, the | 779 | | resource results are to be | maximum number of | 780 | | returned except for | results is set by the | 781 | | "totalResults". | service provider. | 782 +------------+----------------------------+-------------------------+ 784 Table 5: Pagination Request parameters 786 The following table describes the query response pagination 787 attributes specified by the service provider. 789 +--------------+----------------------------------------------------+ 790 | Element | Description | 791 +--------------+----------------------------------------------------+ 792 | itemsPerPage | Non-negative Integer. Specifies the number of | 793 | | search results returned in a query response page; | 794 | | e.g., 10. | 795 | totalResults | Non-negative Integer. Specifies the total number | 796 | | of results matching the client query; e.g., 1000. | 797 | startIndex | The 1-based index of the first result in the | 798 | | current set of search results; e.g., 1. | 799 +--------------+----------------------------------------------------+ 801 Table 6: Pagination Response Elements 803 For example, to retrieve the first 10 Users set the startIndex to 1 804 and the count to 10: 806 GET /Users?startIndex=1&count=10 807 Host: example.com 808 Accept: application/scim+json 809 Authorization: Bearer h480djs93hd8 810 The response to the query above returns metadata regarding paging 811 similar to the following example (actual resources removed for 812 brevity): 814 { 815 "totalResults":100, 816 "itemsPerPage":10, 817 "startIndex":1, 818 "schemas":["urn:scim:api:messages:2.0"], 819 "Resources":[{ 820 ... 821 }] 822 } 824 Given the example above, to continue paging set the startIndex to 11 825 and re-fetch; i.e., /Users?startIndex=11&count=10 827 3.2.2.5. Attributes 829 The following attributes control which attributes SHALL be returned 830 with a returned resource. 832 attributes A multi-valued list of strings indicating the names of 833 resource attributes to return in the response overriding the set 834 of attributes that would be returned by default. Attribute names 835 MUST be in standard attribute notation (Section 3.8) form. See 836 additional retrieval query parameters (Section 3.7). OPTIONAL. 838 excludedAttributes A multi-valued list of strings indicating the 839 names of resource attributes to be removed from the default set of 840 attributes to return. This parameter SHALL have no effect on 841 attributes whose schema "returned" setting is "always" see Server 842 Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in 843 standard attribute notation (Section 3.8) form. See additional 844 retrieval query parameters (Section 3.7). OPTIONAL. 846 3.2.3. Querying Resources Using HTTP POST 848 Clients MAY execute queries without passing parameters on the URL by 849 using the HTTP POST verb combined with the '/.search' path extension. 850 The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL 851 be used to indicate the HTTP POST verb is intended to be a query 852 operation. 854 To create a new search result set, a SCIM client sends an HTTP POST 855 request to the desired SCIM resource endpoint (ending in '/.search'). 856 The body of the POST request MAY include any of the parameters as 857 defined in Section 3.2.2. 859 Search requests MUST be identified using the following URI: 860 'urn:scim:api:messages:2.0:SearchRequest'. The following attributes 861 are defined for search requests: 863 attributes A multi-valued list of strings indicating the names of 864 resource attributes to return in the response overriding the set 865 of attributes that would be returned by default. Attribute names 866 MUST be in standard attribute notation (Section 3.8) form. See 867 additional retrieval query parameters (Section 3.7). OPTIONAL. 869 excludedAttributes A multi-valued list of strings indicating the 870 names of resource attributes to be removed from the default set of 871 attributes to return. This parameter SHALL have no effect on 872 attributes whose schema "returned" setting is "always" see Server 873 Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in 874 standard attribute notation (Section 3.8) form. See additional 875 retrieval query parameters (Section 3.7). OPTIONAL. 877 filter The filter string used to request a subset of resources. The 878 filter string MUST be a valid filter (Section 3.2.2.2) expression. 879 OPTIONAL. 881 sortBy A string indicating the attribute whose value SHALL be used 882 to order the returned responses. The sortBy attribute MUST be in 883 standard attribute notation (Section 3.8) form. See sorting 884 (Section 3.2.2.3). OPTIONAL. 886 sortOrder A string indicating the order in which the sortBy 887 parameter is applied. Allowed values are "ascending" and 888 "descending". See sorting (Section 3.2.2.3). OPTIONAL. 890 startIndex An integer indicating the 1-based index of the first 891 search result. See pagination (Section 3.2.2.4). OPTIONAL. 893 count An integer indicating the desired maximum number of search 894 results per page. See pagination (Section 3.2.2.4). OPTIONAL. 896 After receiving a HTTP POST request, a response is returned as 897 specified in Section 3.2.2. 899 The following example shows an HTTP POST Search request with search 900 parameters attributes, filter, and count included: 902 POST /.search 903 Host: example.com 904 Accept: application/scim+json 905 Content-Type: application/scim+json 906 Authorization: Bearer h480djs93hd8 907 Content-Length: ... 909 { 910 "schemas": ["urn:scim:api:messages:2.0:SearchRequest"], 911 "attributes": ["displayName", "userName"], 912 "filter": "displayName sw \"smith\"", 913 "startIndex": 1, 914 "count": 10 915 } 917 Figure 2: Example POST Search Request 919 A search response is shown with the first page of results. For 920 brevity reasons, only two matches are shown: one User and one Group. 922 HTTP/1.1 200 OK 923 Content-Type: application/scim+json 924 Location: https://example.com/.search 925 { 926 "schemas": ["urn:scim:api:messages:2.0:ListResponse"], 927 "totalResults":100, 928 "itemsPerPage":10, 929 "startIndex":1, 930 "Resources":[ 931 { 932 "meta":{ 933 "location": 934 "https://example.com/Users/2819c223-7f76-413861904646", 935 "resourceType":"User", 936 "lastModified": ... 937 }, 938 "userName":"jsmith", 939 "displayName":"Smith, James" 940 }, 941 { 942 "meta":{ 943 "location": 944 "https://example.com/Groups/c8596b90-7539-4f20968d1908", 945 "resourceType":"Group", 946 "lastModified": ... 947 }, 948 "displayName":"Smith Family" 949 }, 950 ... 951 ] 952 } 954 Figure 3: Example POST Search Response 956 3.3. Modifying Resources 958 Resources can be modified in whole or in part via PUT or PATCH, 959 respectively. Implementers MUST support PUT as specified in 960 Section 4.3 [RFC7231]. Resources such as Groups may be very large 961 hence implementers SHOULD support PATCH [RFC5789] to enable partial 962 resource modifications. 964 3.3.1. Replacing with PUT 966 HTTP PUT is used to perform a full update of a resource's attributes. 967 Clients that MAY have previously retrieved the entire resource in 968 advance and revised it, MAY replace the resource using an HTTP PUT. 969 Because SCIM resource identifiers are typically assigned by the 970 service provider, HTTP PUT SHOULD NOT be used to create new 971 resources. 973 As the operation intent is to replace all attributes, SCIM clients 974 MAY send all attributes regardless of each attribute's mutability. 975 The server will apply attribute by attribute replace according to the 976 following attribute mutability rules: 978 readWrite, writeOnly Any values provided SHALL replace the existing 979 attribute values. 981 immutable If value(s) are already set for the attribute, the input 982 value(s) MUST match or HTTP status 400 SHOULD be returned with 983 error code "mutability". If the service provider has no existing 984 values, the new value(s) SHALL be applied. 986 readOnly Any values provided (e.g. meta.resourceType) SHALL be 987 ignored. 989 If an attribute is "required", clients MUST specify the attribute in 990 the PUT request. 992 Attributes whose mutability is "readWrite", that are omitted from the 993 request body, MAY be assumed to be not asserted by the client. The 994 service provider MAY assume any existing values are to be cleared or 995 the service provider MAY assign a default value to the final resource 996 representation. Service providers MAY take into account whether a 997 client has access to, or understands, all of the resource's 998 attributes when deciding whether non-asserted attributes SHALL be 999 removed or defaulted. Clients that would like to override a server 1000 defaults, MAY specify "null" for a single-valued attribute or an 1001 empty array "[]" for a multi-valued attribute to clear all values. 1003 Unless otherwise specified a successful PUT operation returns a 200 1004 OK response code and the entire resource within the response body, 1005 enabling the client to correlate the client's and Provider's views of 1006 the updated resource. Example: 1008 PUT /Users/2819c223-7f76-453a-919d-413861904646 1009 Host: example.com 1010 Accept: application/scim+json 1011 Content-Type: application/scim+json 1012 Authorization: Bearer h480djs93hd8 1013 If-Match: W/"a330bc54f0671c9" 1015 { 1016 "schemas":["urn:scim:api:messages:2.0:User"], 1017 "id":"2819c223-7f76-453a-919d-413861904646", 1018 "userName":"bjensen", 1019 "externalId":"bjensen", 1020 "name":{ 1021 "formatted":"Ms. Barbara J Jensen III", 1022 "familyName":"Jensen", 1023 "givenName":"Barbara", 1024 "middleName":"Jane" 1025 }, 1026 "roles":[], 1027 "emails":[ 1028 { 1029 "value":"bjensen@example.com" 1030 }, 1031 { 1032 "value":"babs@jensen.org" 1033 } 1034 ] 1035 } 1036 The service responds with the entire, updated User: 1038 HTTP/1.1 200 OK 1039 Content-Type: application/scim+json 1040 ETag: W/"b431af54f0671a2" 1041 Location:"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646" 1042 { 1043 "schemas":["urn:scim:api:messages:2.0:User"], 1044 "id":"2819c223-7f76-453a-919d-413861904646", 1045 "userName":"bjensen", 1046 "externalId":"bjensen", 1047 "name":{ 1048 "formatted":"Ms. Barbara J Jensen III", 1049 "familyName":"Jensen", 1050 "givenName":"Barbara", 1051 "middleName":"Jane" 1052 }, 1053 "emails":[ 1054 { 1055 "value":"bjensen@example.com" 1056 }, 1057 { 1058 "value":"babs@jensen.org" 1059 } 1060 ], 1061 "meta": { 1062 "resourceType":"User", 1063 "created":"2011-08-08T04:56:22Z", 1064 "lastModified":"2011-08-08T08:00:12Z", 1065 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 1066 "version":"W\/\"b431af54f0671a2\"" 1067 } 1068 } 1070 3.3.2. Modifying with PATCH 1072 HTTP PATCH is an OPTIONAL server function that enables clients to 1073 update one or more attributes of a SCIM resource using a sequence of 1074 operations to "add", "remove", or "replace" values. The general form 1075 of the SCIM patch request is based on JavaScript Object Notation 1076 (JSON) Patch [RFC6902]. One difference between SCIM patch and JSON 1077 patch is that SCIM servers do not support array indexing and may not 1078 support all [RFC6902] operation types. 1080 The body of an HTTP PATCH request MUST contain one or more patch 1081 operation objects. A patch operation object MUST have exactly one 1082 "op" member, whose value indicates the operation to perform and MAY 1083 be one of "add", "remove", or "replace". The semantics of each 1084 operation are defined below. 1086 Each operation object MUST contain the following "schemas" URI: 1087 "urn:scim:api:messages:2.0:PatchOp" 1089 Operation objects MUST have exactly one "path" member which is a 1090 "String" containing an attribute path as specified by the following 1091 ABNF syntax rule: 1093 PATH = attrPath / valuePath [subAttr] 1095 Figure 4: SCIM Patch PATH Rule 1097 The rules, "attrPath", "valuePath", and "subAttr" are defined in 1098 Section 3.2.2.2. The "valuePath" rule allows specific values of a 1099 complex, multi-valued attribute to be selected. 1101 Valid examples of "path" values are as follows: 1103 "path":"members" 1105 "path":"name.familyName" 1107 "path":"addresses[type eq \"work\"]" 1109 "path":"members[value eq 1110 \"2819c223-7f76-453a-919d-413861904646\"]" 1112 "path":"members[value eq 1113 \"2819c223-7f76-453a-919d-413861904646\"].displayName" 1115 Each operation against an attribute MUST be compatible with the 1116 attribute's mutability and schema as defined in the Attribute Types 1117 Section of [I-D.ietf-scim-core-schema]. For example, a client MAY 1118 NOT modify an attribute that has mutability "readOnly" or 1119 "immutable". However, a client MAY "add" a value to an "immutable" 1120 attribute if the attribute had no previous value. An operation that 1121 is not compatibile with an attribute's mutability or schema SHALL 1122 return an error as indicated below. 1124 Each patch operation represents a single action to be applied to the 1125 same SCIM resource specified by the request URI. Operations are 1126 applied sequentially in the order they appear in the array. Each 1127 operation in the sequence is applied to the target resource; the 1128 resulting resource becomes the target of the next operation. 1129 Evaluation continues until all operations are successfully applied or 1130 until an error condition is encountered. 1132 A patch request, regardless of the number of operations, SHALL be 1133 treated as atomic. If a single operation encounters an error 1134 condition, the original SCIM resource MUST be restored, and a failure 1135 status SHALL be returned. 1137 If a request fails. the server SHALL return an HTTP response status 1138 code and a JSON detail error response as defined in Section 3.10. 1140 On successful completion, the server MUST return either a 200 OK 1141 response code and the entire resource (subject to the "attributes" 1142 query parameter - see Additional Retrieval Query Parameters 1143 (Section 3.7) ) within the response body, or a 204 No Content 1144 response code and the appropriate response headers for a successful 1145 patch request. The server MUST return a 200 OK if the "attributes" 1146 parameter is specified on the request. 1148 3.3.2.1. Add Operation 1150 The "add" operation performs one of the following functions, 1151 depending upon what the target location indicated by "path" 1152 references: 1154 o If the target location does not exist, the attribute and value is 1155 added. 1157 o If the target location specifies a multi-valued attribute, a new 1158 value is added to the attribute. 1160 o if the target location specifies a single-valued attribute, the 1161 existing value is replaced. 1163 o If the target location specifies an attribute that does not exist 1164 (has no value), the attribute is added with the new value. 1166 o If the target location exists, the value is replaced. 1168 o If the target location already contains the value specified, no 1169 changes SHOULD be made to the resource and a success response 1170 SHOULD be returned. Unless other operations change the resource, 1171 this operation SHALL NOT change the modify timestamp of the 1172 resource. 1174 The operation MUST contain a "value" member whose content specifies 1175 the value to be added. The value MAY be a quoted value OR it may be 1176 a JSON object containing the sub-attributes of the complex attribute 1177 specified in the operation's "path". 1179 The following example shows how to add a member to a group. Some 1180 text removed for readability ("..."): 1182 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1183 Host: example.com 1184 Accept: application/scim+json 1185 Content-Type: application/scim+json 1186 Authorization: Bearer h480djs93hd8 1187 If-Match: W/"a330bc54f0671c9" 1189 { 1190 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1191 "op":"add", 1192 "path":"members", 1193 "value":[ 1194 { 1195 "display": "Babs Jensen", 1196 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1197 "value": "2819c223-7f76-453a-919d-413861904646" 1198 } 1199 ] 1200 } 1202 The "display" Sub-Attribute in this request is optional since the 1203 value attribute uniquely identifies the user to be added. If the 1204 user was already a member of this group, no changes should be made to 1205 the resource and a success response should be returned. The server 1206 responds with either the entire updated Group or no response body: 1208 HTTP/1.1 204 No Content 1209 Authorization: Bearer h480djs93hd8 1210 ETag: W/"b431af54f0671a2" 1211 Location: "https://example.com/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" 1213 3.3.2.2. Remove Operation 1215 The "remove" operation removes the value at the target location 1216 specified by the "path". The operation performs the following 1217 functions depending on the target location specified by "path" : 1219 o If the target location is a single-value attribute, the attribute 1220 and its associated value is removed. 1222 o If the target location is a multi-valued attribute and no filter 1223 is specified, the attribute and all values are removed. 1225 o If the target location is a multi-valued attribute and a complex 1226 filter is specified comparing a "value", the values matched by the 1227 filter are removed. 1229 o If the target location is a complex-multi-valued attribute and a 1230 complex filter is specified based on the attribute's sub- 1231 attributes, the matching records are removed. 1233 The following example shows how to remove a member from a group. As 1234 with the previous example, the "display" Sub-Attribute is optional. 1235 If the user was not a member of this group, no changes should be made 1236 to the resource and a success response should be returned. 1238 Note that server responses have been omitted for the rest of the 1239 PATCH examples. 1241 Remove a single member from a group. Some text removed for 1242 readability ("..."): 1244 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1245 Host: example.com 1246 Accept: application/scim+json 1247 Content-Type: application/scim+json 1248 Authorization: Bearer h480djs93hd8 1249 If-Match: W/"a330bc54f0671c9" 1251 { 1252 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1253 "op":"remove", 1254 "path":"members[value eq \"2819c223-7f76-...413861904646\"]" 1255 } 1257 Remove all members of a group: 1259 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1260 Host: example.com 1261 Accept: application/scim+json 1262 Content-Type: application/scim+json 1263 Authorization: Bearer h480djs93hd8 1264 If-Match: W/"a330bc54f0671c9" 1266 { "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1267 "op":"remove","path":"members"} 1269 Removal of a value from a complex-multi-valued attribute (request 1270 headers removed for brevity): 1272 { 1273 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1274 "op":"remove", 1275 "path":"emails[type eq \"work\" and value ew \"example.com\"]" 1276 } 1278 Example request to remove and add a member. Some text removed for 1279 readability ("..."): 1281 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1282 Host: example.com 1283 Accept: application/scim+json 1284 Content-Type: application/scim+json 1285 Authorization: Bearer h480djs93hd8 1286 If-Match: W/"a330bc54f0671c9" 1288 [ 1289 { 1290 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1291 "op":"remove", 1292 "path":"members[value eq\"2819c223...919d-413861904646\"]" 1293 }, 1294 { 1295 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1296 "op":"add", 1297 "path":"members", 1298 "value": [ 1299 { 1300 "display": "James Smith", 1301 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1302 "value": "08e1d05d...473d93df9210" 1303 } 1304 ] 1305 } 1306 ] 1307 The following example shows how to replace all the members of a group 1308 with a different members list. Some text removed for readabilty 1309 ("..."): 1311 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1312 Host: example.com 1313 Accept: application/scim+json 1314 Content-Type: application/scim+json 1315 Authorization: Bearer h480djs93hd8 1316 If-Match: W/"a330bc54f0671c9" 1318 [ 1319 { "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1320 "op":"remove","path":"members"}, 1321 { 1322 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1323 "op":"add", 1324 "path":"members", 1325 "value":[ 1326 { 1327 "display": "Babs Jensen", 1328 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1329 "value": "2819c223-7f76-453a-919d-413861904646" 1330 }, 1331 { 1332 "display": "James Smith", 1333 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1334 "value": "08e1d05d-121c-4561-8b96-473d93df9210" 1335 }] 1336 } 1337 ] 1339 3.3.2.3. Replace Operation 1341 The "replace" operation replaces the value at the target location 1342 specified by the "path". The operation performs the following 1343 functions depending on the target location specified by "path" : 1345 o If the target location is a single-value attribute, the attributes 1346 value is replaced. 1348 o If the target location is a multi-valued attribute and no filter 1349 is specified, the attribute and all values are replaced. 1351 o If the target location is a multi-valued attribute and a complex 1352 filter is specified comparing a "value", the values matched by the 1353 filter are replaced. 1355 o If the target location is a complex-multi-valued attribute and a 1356 complex filter is specified based on the attribute's sub- 1357 attributes, the matching records are replaced. 1359 o If the target location is a complex-multi-valued attribute with a 1360 complex filter and a specific sub-attribute (e.g. "addresses[type 1361 eq "work"].streetAddress" ), the matching sub-attribute of the 1362 matching record is replaced. 1364 The following example shows how to replace all the members of a group 1365 with a different members list in a single replace operation. Some 1366 text removed for readability ("..."): 1368 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1369 Host: example.com 1370 Accept: application/scim+json 1371 Content-Type: application/scim+json 1372 Authorization: Bearer h480djs93hd8 1373 If-Match: W/"a330bc54f0671c9" 1375 { 1376 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1377 "op":"replace", 1378 "path":"members", 1379 "value":[ 1380 { 1381 "display": "Babs Jensen", 1382 "$ref": "https://example.com/v2/Users/2819c223...413861904646", 1383 "value": "2819c223...413861904646" 1384 }, 1385 { 1386 "display": "James Smith", 1387 "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", 1388 "value": "08e1d05d...473d93df9210" 1389 } 1390 ] 1391 } 1392 The following example shows how to change a User's entire "work" 1393 address. 1395 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1396 Host: example.com 1397 Accept: application/scim+json 1398 Content-Type: application/scim+json 1399 Authorization: Bearer h480djs93hd8 1400 If-Match: W/"a330bc54f0671c9" 1402 { 1403 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1404 "op":"replace", 1405 "path":"addresses[type eq \"work\"]", 1406 "value": 1407 { 1408 "type": "work", 1409 "streetAddress": "911 Universal City Plaza", 1410 "locality": "Hollywood", 1411 "region": "CA", 1412 "postalCode": "91608", 1413 "country": "US", 1414 "formatted": "911 Universal City Plaza\nHollywood, CA 91608 US", 1415 "primary": true 1416 } 1417 } 1419 The following example shows how to change a User's address. Since 1420 address does not have a value Sub-Attribute, the existing address 1421 must be removed and the modified address added. 1423 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1424 Host: example.com 1425 Accept: application/scim+json 1426 Content-Type: application/scim+json 1427 Authorization: Bearer h480djs93hd8 1428 If-Match: W/"a330bc54f0671c9" 1430 { 1431 "schemas": ["urn:scim:api:messages:2.0:PatchOp"], 1432 "op":"replace", 1433 "path":"addresses[type eq \"work\"].streetAddress", 1434 "value":"911 Universal City Plaza" 1435 } 1437 3.4. Deleting Resources 1439 Clients request resource removal via DELETE. Service providers MAY 1440 choose not to permanently delete the resource, but MUST return a 404 1441 error code for all operations associated with the previously deleted 1442 Id. Service providers MUST also omit the resource from future query 1443 results. In addition the service provider MUST not consider the 1444 deleted resource in conflict calculation. For example if a User 1445 resource is deleted, a CREATE request for a User resource with the 1446 same userName as the previously deleted resource should not fail with 1447 a 409 error due to userName conflict. 1449 DELETE /Users/2819c223-7f76-453a-919d-413861904646 1450 Host: example.com 1451 Authorization: Bearer h480djs93hd8 1452 If-Match: W/"c310cd84f0281b7" 1454 In response to a successful delete, the server SHALL respond with 1455 successful HTTP status 204 (No Content). A non-normative example 1456 response: 1458 HTTP/1.1 204 No Content 1460 Example: client attempt to retrieve the previously deleted User 1462 GET /Users/2819c223-7f76-453a-919d-413861904646 1463 Host: example.com 1464 Authorization: Bearer h480djs93hd8 1466 Server Response: 1468 HTTP/1.1 404 NOT FOUND 1470 { 1471 "schemas": ["urn:scim:api:messages:2.0:Error"], 1472 "Errors":[ 1473 { 1474 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 1475 "code":"404" 1476 } 1477 ] 1478 } 1480 3.5. Bulk 1482 The SCIM bulk operation is an optional server feature that enables 1483 clients to send a potentially large collection of resource operations 1484 in a single request. The body of a a bulk operation contains a set 1485 of HTTP resource operations using one of the API supported HTTP 1486 methods; i.e., POST, PUT, PATCH or DELETE. 1488 Bulk requests are identified using the following URI: 1489 'urn:scim:api:messages:2.0:BulkRequest'. Bulk responses are 1490 identified using the following URI: 1491 'urn:scim:api:messages:2.0:BulkResponse'. Bulk requests and bulk 1492 responses share many attributes. Unless otherwise specified, each 1493 attribute below is present in both bulk requests and bulk responses. 1495 The following Singular Attribute is defined in addition to the common 1496 attributes defined in SCIM core schema. 1498 failOnErrors An Integer specifying the number of errors that the 1499 service provider will accept before the operation is terminated 1500 and an error response is returned. OPTIONAL in a request. Not 1501 valid in a response. 1503 The following Complex Multi-valued Attribute is defined in addition 1504 to the common attributes defined in core schema. 1506 Operations Defines operations within a bulk job. Each operation 1507 corresponds to a single HTTP request against a resource endpoint. 1508 REQUIRED. 1510 method The HTTP method of the current operation. Possible values 1511 are POST, PUT, PATCH or DELETE. REQUIRED. 1513 bulkId The transient identifier of a newly created resource, 1514 unique within a bulk request and created by the client. The 1515 bulkId serves as a surrogate resource id enabling clients to 1516 uniquely identify newly created resources in the Response and 1517 cross reference new resources in and across operations within a 1518 bulk request. REQUIRED when method is POST. 1520 version The current resource version. Version is REQUIRED if the 1521 service provider supports ETags and the method is PUT, DELETE, 1522 or PATCH. 1524 path The resource's relative path. If the method is POST the 1525 value must specify a resource type endpoint; e.g., /Users or 1526 /Groups whereas all other method values must specify the path 1527 to a specific resource; e.g., /Users/2819c223-7f76-453a-919d- 1528 413861904646. REQUIRED in a request. 1530 data The resource data as it would appear for a single POST, PUT 1531 or PATCH resource operation. REQUIRED in a request when method 1532 is POST, PUT and PATCH. 1534 location The resource endpoint URL. REQUIRED in a response, 1535 except in the event of a POST failure. 1537 status A complex type that contains information about the success 1538 or failure of one operation within the bulk job. REQUIRED in a 1539 response. 1541 code The HTTP response code that would have been returned if a 1542 a single HTTP request would have been used. REQUIRED. 1544 description A human readable error message. REQUIRED when an 1545 error occurred. 1547 If a bulk job is processed successfully the HTTP response code 200 OK 1548 MUST be returned, otherwise an appropriate HTTP error code MUST be 1549 returned. 1551 The service provider MUST continue performing as many changes as 1552 possible and disregard partial failures. The client MAY override 1553 this behavior by specifying a value for failOnErrors attribute. The 1554 failOnErrors attribute defines the number of errors that the service 1555 provider should accept before failing the remaining operations 1556 returning the response. 1558 To be able to reference a newly created resource the attribute bulkId 1559 MUST be specified when creating new resources. The bulkId is defined 1560 by the client as a surrogate identifier in a POST operation. The 1561 service provider MUST return the same bulkId together with the newly 1562 created resource. The bulkId can then be used by the client to map 1563 the service provider id with the bulkId of the created resource. 1565 There can be more then one operation per resource in each bulk job. 1566 The Service client MUST take notice of the unordered structure of 1567 JSON and the service provider can process operations in any order. 1568 For example, if the Service client sends two PUT operations in one 1569 request, the outcome is non-deterministic. 1571 The service provider response MUST include the result of all 1572 processed operations. A location attribute that includes the 1573 resource's end point MUST be returned for all operations excluding 1574 failed POSTs. The status attribute includes information about the 1575 success or failure of one operation within the bulk job. The 1576 attribute status MUST include the code attribute that holds the HTTP 1577 response code that would have been returned if a single HTTP request 1578 would have been used. If an error occurred the status MUST also 1579 include the description attribute containing a human readable 1580 explanation of the error. 1582 "status": { 1583 "code": "201" 1584 } 1586 The following is an example of a status in a failed operation. 1588 "status": { 1589 "code": "400", 1590 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1591 } 1593 The following example shows how to add, update, and remove a user. 1594 The failOnErrors attribute is set to '1' indicating the service 1595 provider should return on the first error. The POST operation's 1596 bulkId value is set to 'qwerty' enabling the client to match the new 1597 User with the returned resource id '92b725cd-9465-4e7d- 1598 8c16-01f8e146b87a'. 1600 POST /v2/Bulk 1601 Host: example.com 1602 Accept: application/scim+json 1603 Content-Type: application/scim+json 1604 Authorization: Bearer h480djs93hd8 1605 Content-Length: ... 1607 { 1608 "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], 1609 "failOnErrors":1, 1610 "Operations":[ 1611 { 1612 "method":"POST", 1613 "path":"/Users", 1614 "bulkId":"qwerty", 1615 "data":{ 1616 "schemas": ["urn:scim:api:messages:2.0:User"], 1617 "userName":"Alice" 1618 } 1619 }, 1620 { 1621 "method":"PUT", 1622 "path":"/Users/b7c14771-226c-4d05-8860-134711653041", 1623 "version":"W\/\"3694e05e9dff591\"", 1624 "data":{ 1625 "schemas": ["urn:scim:api:messages:2.0:User"], 1626 "id":"b7c14771-226c-4d05-8860-134711653041", 1627 "userName":"Bob" 1629 } 1630 }, 1631 { 1632 "method": "PATCH", 1633 "path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1634 "version": "W/\"edac3253e2c0ef2\"", 1635 "data": {[ 1636 { 1637 "op": "remove", 1638 "path": "nickName" 1639 }, 1640 { 1641 "op": "add", 1642 "path": "userName", 1643 "value": "Dave" 1644 } 1645 ]} 1646 }, 1647 { 1648 "method":"DELETE", 1649 "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1650 "version":"W\/\"0ee8add0a938e1a\"" 1651 } 1652 ] 1653 } 1655 The service provider returns the following response. 1657 HTTP/1.1 200 OK 1658 Content-Type: application/scim+json 1660 { 1661 "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], 1662 "Operations": [ 1663 { 1664 "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1665 "method": "POST", 1666 "bulkId": "qwerty", 1667 "version": "W\/\"oY4m4wn58tkVjJxK\"", 1668 "status": { 1669 "code": "201" 1670 } 1671 }, 1672 { 1673 "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 1674 "method": "PUT", 1675 "version": "W\/\"huJj29dMNgu3WXPD\"", 1676 "status": { 1677 "code": "200" 1678 } 1679 }, 1680 { 1681 "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1682 "method": "PATCH", 1683 "version": "W\/\"huJj29dMNgu3WXPD\"", 1684 "status": { 1685 "code": "200" 1686 } 1687 }, 1688 { 1689 "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1690 "method": "DELETE", 1691 "status": { 1692 "code": "204" 1693 } 1694 } 1695 ] 1696 } 1698 The following response is returned if an error occurred when 1699 attempting to create the User 'Alice'. The service provider stops 1700 processing the bulk operation and immediately returns a response to 1701 the client. The response contains the error and any successful 1702 results prior to the error. 1704 HTTP/1.1 200 OK 1705 Content-Type: application/scim+json 1707 { 1708 "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], 1709 "Operations": [ 1710 { 1711 "method": "POST", 1712 "bulkId": "qwerty", 1713 "status": { 1714 "code": "400", 1715 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1716 } 1717 } 1718 ] 1719 } 1721 If the failOnErrors attribute is not specified or the service 1722 provider has not reached the error limit defined by the client the 1723 service provider will continue to process all operations. The 1724 following is an example in which all operations failed. 1726 HTTP/1.1 200 OK 1727 Content-Type: application/scim+json 1729 { 1730 "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], 1731 "Operations": [ 1732 { 1733 "method": "POST", 1734 "bulkId": "qwerty", 1735 "status": { 1736 "code": "400", 1737 "description": "Request is unparseable, syntactically incorrect, or violates schema." 1738 } 1739 }, 1740 { 1741 "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 1742 "method": "PUT", 1743 "status": { 1744 "code": "412", 1745 "description": "Failed to update as user changed on the server since you last retrieved it." 1746 } 1747 }, 1748 { 1749 "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 1750 "method": "PATCH", 1751 "status": { 1752 "code": "412", 1753 "description": "Failed to update as user changed on the server since you last retrieved it." 1754 } 1755 }, 1756 { 1757 "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 1758 "method": "DELETE", 1759 "status": { 1760 "code": "404", 1761 "description": "Specified resource; e.g., User, does not exist." 1762 } 1763 } 1764 ] 1765 } 1767 The client can, within one bulk operation, create a new User, a new 1768 Group and add the newly created User to the newly created Group. In 1769 order to add the new User to the Group the client must use the 1770 surrogate id attribute, bulkId, to reference the User. The bulkId 1771 attribute value must be pre-pended with the literal "bulkId:"; e.g., 1772 if the bulkId is 'qwerty' the value is "bulkId:qwerty". The service 1773 provider MUST replace the string "bulkId:qwerty" with the permanent 1774 resource id once created. 1776 The following example creates a User with the userName 'Alice' and a 1777 Group with the displayName 'Tour Guides' with Alice as a member. 1779 POST /v2/Bulk 1780 Host: example.com 1781 Accept: application/scim+json 1782 Content-Type: application/scim+json 1783 Authorization: Bearer h480djs93hd8 1784 Content-Length: ... 1786 { 1787 "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], 1788 "Operations": [ 1789 { 1790 "method": "POST", 1791 "path": "/Users", 1792 "bulkId": "qwerty", 1793 "data": { 1794 "schemas": ["urn:scim:schemas:core:2.0:User"], 1795 "userName": "Alice" 1796 } 1797 }, 1798 { 1799 "method": "POST", 1800 "path": "/Groups", 1801 "bulkId": "ytrewq", 1802 "data": { 1803 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1804 "displayName": "Tour Guides", 1805 "members": [ 1806 { 1807 "type": "user", 1808 "value": "bulkId:qwerty" 1809 } 1810 ] 1811 } 1812 } 1813 ] 1814 } 1816 The service provider returns the following response. 1818 HTTP/1.1 200 OK 1819 Content-Type: application/scim+json 1821 { 1822 "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], 1823 "Operations": [ 1824 { 1825 "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1826 "method": "POST", 1827 "bulkId": "qwerty", 1828 "version": "W\/\"4weymrEsh5O6cAEK\"", 1829 "status": { 1830 "code": "201" 1831 } 1832 }, 1833 { 1834 "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1835 "method": "POST", 1836 "bulkId": "ytrewq", 1837 "version": "W\/\"lha5bbazU3fNvfe5\"", 1838 "status": { 1839 "code": "201" 1840 } 1841 } 1842 ] 1843 } 1845 A subsequent request for the 'Tour Guides' Group ('e9e30dba-f08f- 1846 4109-8486-d5c6a331660a') returns the following: 1848 GET /v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1849 Host: example.com 1850 Accept: application/scim+json 1851 Authorization: Bearer h480djs93hd8 1853 HTTP/1.1 200 OK 1854 Content-Type: application/scim+json 1855 Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 1856 ETag: W/"lha5bbazU3fNvfe5" 1858 { 1859 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1860 "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", 1861 "displayName": "Tour Guides", 1862 "meta": { 1863 "resourceType": "Group", 1864 "created": "2011-08-01T18:29:49.793Z", 1865 "lastModified": "2011-08-01T20:31:02.315Z", 1866 "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 1867 "version": "W\/\"lha5bbazU3fNvfe5\"" 1868 }, 1869 "members": [ 1870 { 1871 "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", 1872 "$ref": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 1873 "type": "User" 1874 } 1875 ] 1876 } 1878 Extensions that include references to other resources MUST be handled 1879 in the same way by the service provider. The following example uses 1880 the bulkId attribute within the enterprise extension managerId 1881 attribute. 1883 POST /v2/Bulk 1884 Host: example.com 1885 Accept: application/scim+json 1886 Content-Type: application/scim+json 1887 Authorization: Bearer h480djs93hd8 1888 Content-Length: ... 1890 { 1891 "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], 1892 "Operations": [ 1893 { 1894 "method": "POST", 1895 "path": "/Users", 1896 "bulkId": "qwerty", 1897 "data": { 1898 "schemas": ["urn:scim:schemas:core:2.0:User"], 1899 "userName": "Alice" 1900 } 1901 }, 1902 { 1903 "method": "POST", 1904 "path": "/Users", 1905 "bulkId": "ytrewq", 1906 "data": { 1907 "schemas": [ 1908 "urn:scim:schemas:core:2.0:User", 1909 "urn:scim:schemas:extension:enterprise:2.0:User" 1910 ], 1911 "userName": "Bob", 1912 "urn:scim:schemas:extension:enterprise:2.0:User": { 1913 "employeeNumber": "11250", 1914 "manager": { 1915 "managerId": "batchId:qwerty", 1916 "displayName": "Alice" 1917 } 1918 } 1919 } 1920 } 1921 ] 1922 } 1924 The service provider MUST try to resolve circular cross references 1925 between resources in a single bulk job but MAY stop after a failed 1926 attempt and instead return the status code 409 Conflict. The 1927 following example exhibits the potential conflict. 1929 POST /v2/Bulk 1930 Host: example.com 1931 Accept: application/scim+json 1932 Content-Type: application/scim+json 1933 Authorization: Bearer h480djs93hd8 1934 Content-Length: ... 1936 { 1937 "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], 1938 "Operations": [ 1939 { 1940 "method": "POST", 1941 "path": "/Groups", 1942 "bulkId": "qwerty", 1943 "data": { 1944 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1945 "displayName": "Group A", 1946 "members": [ 1947 { 1948 "type": "group", 1949 "value": "bulkId:ytrewq" 1950 } 1951 ] 1952 } 1953 }, 1954 { 1955 "method": "POST", 1956 "path": "/Groups", 1957 "bulkId": "ytrewq", 1958 "data": { 1959 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1960 "displayName": "Group B", 1961 "members": [ 1962 { 1963 "type": "group", 1964 "value": "bulkId:qwerty" 1965 } 1966 ] 1967 } 1968 } 1969 ] 1970 } 1972 If the service provider resolved the above circular references the 1973 following is returned from a subsequent GET request. 1975 GET /v2/Groups?filter=displayName sw 'Group' 1976 Host: example.com 1977 Accept: application/scim+json 1978 Authorization: Bearer h480djs93hd8 1980 HTTP/1.1 200 OK 1981 Content-Type: application/scim+json 1983 { 1984 "schemas": ["urn:scim:api:messages:2.0:ListResponse"], 1985 "totalResults": 2, 1986 "Resources": [ 1987 { 1988 "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1989 "schemas": ["urn:scim:schemas:core:2.0:Group"], 1990 "displayName": "Group A", 1991 "meta": { 1992 "resourceType": "Group", 1993 "created": "2011-08-01T18:29:49.793Z", 1994 "lastModified": "2011-08-01T18:29:51.135Z", 1995 "location": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 1996 "version": "W\/\"mvwNGaxB5SDq074p\"" 1997 }, 1998 "members": [ 1999 { 2000 "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 2001 "$ref": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 2002 "type": "Group" 2003 } 2004 ] 2005 }, 2006 { 2007 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 2008 "schemas": ["urn:scim:schemas:core:2.0:Group"], 2009 "displayName": "Group B", 2010 "meta": { 2011 "resourceType": "Group", 2012 "created": "2011-08-01T18:29:50.873Z", 2013 "lastModified": "2011-08-01T18:29:50.873Z", 2014 "location": "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 2015 "version": "W\/\"wGB85s2QJMjiNnuI\"" 2016 }, 2017 "members": [ 2018 { 2019 "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 2020 "$ref": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 2021 "type": "Group" 2022 } 2023 ] 2024 } 2025 ] 2026 } 2027 The service provider MUST define the maximum number of operations and 2028 maximum payload size a client may send in a single request. If 2029 either limits are exceeded the service provider MUST return the HTTP 2030 response code 413 Request Entity Too Large. The returned response 2031 MUST specify the limit exceeded in the body of the error response. 2033 The following example the client sent a request exceeding the service 2034 provider's max payload size of 1 megabyte. 2036 POST /v2/Bulk 2037 Host: example.com 2038 Accept: application/scim+json 2039 Content-Type: application/scim+json 2040 Authorization: Bearer h480djs93hd8 2041 Content-Length: 4294967296 2043 ... 2045 HTTP/1.1 413 Request Entity Too Large 2046 Content-Type: application/scim+json 2047 Location: https://example.com/v2/Bulk/yfCrVJhFIJagAHj8 2049 { 2050 "schemas":["urn:scim:api:messages:2.0:Error"], 2051 "Errors":[ 2052 { 2053 "description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).", 2054 "code":"413" 2055 } 2056 ] 2057 } 2059 3.6. Data Input/Output Formats 2061 Servers MUST accept requests and respond with JSON structured 2062 responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default 2063 encoding format. 2065 Clients using other encodings MUST specify the format in which the 2066 data is submitted via HTTP header "Content-Type" as specified in 2067 Section 3.1.1.5 [RFC7231] and MAY specify the desired response data 2068 format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g., 2069 "Accept: application/scim+json" or via URI suffix; e.g., 2070 GET /Users/2819c223-7f76-453a-919d-413861904646.scim 2071 Host: example.com 2073 Service providers MUST support the accept header "Accept: 2074 application/scim+json" and SHOULD support header "Accept: 2075 application/json" both of which specify JSON documents conforming to 2076 [RFC7159]. The format defaults to "application/scim+json" if no 2077 format is specified. 2079 Singular attributes are encoded as string name-value-pairs in JSON; 2080 e.g., 2082 "attribute": "value" 2084 Multi-valued attributes in JSON are encoded as arrays; e.g., 2086 "attributes": [ "value1", "value2" ] 2088 Elements with nested elements are represented as objects in JSON; 2089 e.g, 2091 "attribute": { "subattribute1": "value1", "subattribute2": "value2" } 2093 3.7. Additional Operation Response Parameters 2095 For any SCIM operation where a resource representation is returned 2096 (e.g. HTTP GET), the attributes normally returned are defined as the 2097 minimum attribute set plus default attributes. The minimum set are 2098 those attributes whose schema have "returned" set to "always". The 2099 defaut attribute set are those attributes whose schema have 2100 "returned" set to "default". 2102 Clients MAY request a partial resource representation on any 2103 operation that returns a resource within the response by specifying 2104 either of the mutually exclusive URL query parameters "attributes" OR 2105 "excludedAtributes" as follows: 2107 attributes When specified, each resource returned MUST contain the 2108 minimal set of resource attributes and MUST contain no other 2109 attributes or sub-attributes other than those explicitly 2110 requested. The query parameter attributes value is a comma 2111 separated list of resource attribute names in standard 2112 attribute notation (Section 3.8) form (e.g. userName, name, 2113 emails). 2115 excludedAttributes When specified, each resource returned MUST 2116 contain the minimal set of resource attributes. 2117 Additionally, the default set of attributes minus those 2118 attributes listed in "excludedAttributes" are also returned. 2119 The query parameter attributes value is a comma separated 2120 list of resource attribute names in standard attribute 2121 notation (Section 3.8) form (e.g. userName, name, emails). 2123 . 2125 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName 2126 Host: example.com 2127 Accept: application/json 2128 Authorization: Bearer h480djs93hd8 2130 Giving the response 2132 HTTP/1.1 200 OK 2133 Content-Type: application/json 2134 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2135 ETag: W/"a330bc54f0671c9" 2137 { 2138 "schemas":["urn:scim:schemas:core:2.0:User"], 2139 "id":"2819c223-7f76-453a-919d-413861904646", 2140 "userName":"bjensen", 2141 "meta":{ 2142 "resourceType": "User", 2143 "created":"2011-08-01T18:29:49.793Z", 2144 "lastModified":"2011-08-01T18:29:49.793Z", 2145 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2146 "version":"W\/\"a330bc54f0671c9\"" 2147 } 2148 } 2150 3.8. Attribute Notation 2152 All operations share a common scheme for referencing simple and 2153 complex attributes. In general, attributes are identified by 2154 prefixing the attribute name with its schema URN separated by a ':' 2155 character; e.g., the core User resource attribute 'userName' is 2156 identified as 'urn:scim:schemas:core:2.0:User:userName'. Clients MAY 2157 omit core schema attribute URN prefixes though MUST fully qualify 2158 extended attributes with the associated resource URN; e.g., the 2159 attribute 'age' defined in 'urn:hr:schemas:user' is fully encoded as 2160 'urn:hr:schemas:user:age'. A Complex attributes' Sub-Attributes are 2161 referenced via nested, dot ('.') notation; i.e., {urn}:{Attribute 2162 name}.{Sub-Attribute name}. For example, the fully qualified path for 2163 a User's givenName is urn:scim:schemas:core:2.0:User:name.givenName 2164 All facets (URN, attribute and Sub-Attribute name) of the fully 2165 encoded Attribute name are case insensitive. 2167 3.9. "/Me" Authenticated Subject Alias 2169 A client MAY use a URL of the form "/Me" as an URL alias 2170 for the User or other resource associated with the currently 2171 authenticated subject for any SCIM operation. A service provider MAY 2172 respond in ONE of 3 ways: 2174 o A service provider that does NOT support this feature SHOULD 2175 respond with status 403 (FORBIDDEN). 2177 o A service provider MAY choose to redirect the client using HTTP 2178 status 308 to the resource associated with the authenticated 2179 subject. The client MAY then repeat the request at the indicated 2180 location. 2182 o A service provider MAY process the SCIM request directly. In any 2183 response, the HTTP "Location" header MUST be the permanent 2184 location of the aliased resource associated with the authenticated 2185 subject. 2187 3.10. HTTP Error Responses 2189 The SCIM Protocol uses the response status codes defined in HTTP 2190 Section 6 [RFC7231] to indicate operation success or failure. In 2191 addition to returning a HTTP response code implementers MUST return 2192 the errors in the body of the response in the client requested format 2193 containing the error response and, per the HTTP specification, human- 2194 readable explanations. Error responses are identified using the 2195 following "schema" URI: "urn:scim:api:messages:2.0:Error". The 2196 following attributes are defined inclusion in a SCIM error response 2197 using a JSON body: 2199 status 2200 The HTTP status value (e.g. 400). REQUIRED 2202 scimType 2203 A SCIM detailed error keyword. See Table 8. OPTIONAL 2205 detail 2206 A detailed, human readable message. OPTIONAL 2208 Implementers SHOULD handle the identified errors as described below. 2210 +--------------+---------------+------------------------------------+ 2211 | Status | Applicability | Suggested Explanation | 2212 +--------------+---------------+------------------------------------+ 2213 | 307 | GET, POST, | The client is directed to repeat | 2214 | TEMPORARY | PUT, PATCH, | the same HTTP request at the | 2215 | REDIRECT | DELETE | location identified. The client | 2216 | | | SHOULD NOT use the location | 2217 | | | provided in the response as a | 2218 | | | permanent reference to the | 2219 | | | resource and SHOULD continue to | 2220 | | | use the original request URI | 2221 | | | [RFC7231]. | 2222 | 308 | GET, POST, | The client is directed to repeat | 2223 | PERMANENT | PUT, PATCH, | the same HTTP request at the | 2224 | REDIRECT | DELETE | location identified. The client | 2225 | | | SHOULD use the location provided | 2226 | | | in the response as the permanent | 2227 | | | reference to the resource | 2228 | | | [I-D.reschke-http-status-308]. | 2229 | 400 BAD | GET, POST, | Request is unparseable, | 2230 | REQUEST | PUT, PATCH, | syntactically incorrect, or | 2231 | | DELETE | violates schema | 2232 | 401 | GET, POST, | Authorization failure | 2233 | UNAUTHORIZED | PUT, PATCH, | | 2234 | | DELETE | | 2235 | 403 | GET, POST, | Server does not support requested | 2236 | FORBIDDEN | PUT, PATCH, | operation | 2237 | | DELETE | | 2238 | 404 NOT | GET, PUT, | Specified resource (e.g., User) or | 2239 | FOUND | PATCH, DELETE | end-point, does not exist | 2240 | 409 CONFLICT | POST, PUT, | The specified version number does | 2241 | | PATCH, DELETE | not match the resource's latest | 2242 | | | version number or a service | 2243 | | | provider refused to create a new, | 2244 | | | duplicate resource | 2245 | 412 | PUT, PATCH,D | Failed to update as resource {id} | 2246 | PRECONDITION | ELETE | changed on the server last | 2247 | FAILED | | retrieved | 2248 | 413 REQUEST | POST | {"maxOperations": | 2249 | ENTITY TOO | | 1000,"maxPayload": 1048576} | 2250 | LARGE | | | 2251 | 500 INTERNAL | GET, POST, | An internal error. Implementers | 2252 | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive | 2253 | | DELETE | debugging advice | 2254 | 501 NOT | GET, POST, | Service Provider does not support | 2255 | IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH | 2256 | | DELETE | | 2257 +--------------+---------------+------------------------------------+ 2258 Table 7: Defined error cases 2260 For HTTP Status 400 (Bad Request) responses, the following detail 2261 error types are defined: 2263 +--------------+------------------------------+---------------------+ 2264 | scimType | Description | Applicability | 2265 +--------------+------------------------------+---------------------+ 2266 | invalidFilte | The specified filter syntax | GET(Section 3.2.2), | 2267 | r | was invalid (does not comply | POST (Search - | 2268 | | with Figure 1) or the | Section 3.2.3), | 2269 | | specified attribute and | PATCH (Path Filter | 2270 | | filter comparison | - Section 3.3.2) | 2271 | | combination is not | | 2272 | | supported. | | 2273 | tooMany | The specified filter yields | GET(Section 3.2.2), | 2274 | | many more results than the | POST (Search - | 2275 | | server is willing calculate | Section 3.2.3) | 2276 | | or process. For example, a | | 2277 | | filter such as "userName eq | | 2278 | | "*"" would return all | | 2279 | | entries with a "userName" | | 2280 | | and MAY not be acceptable to | | 2281 | | the service provider. | | 2282 | uniqueness | One or more of attribute | POST (Create - | 2283 | | values is already in use or | Section 3.1), PUT | 2284 | | is reserved. | (Section 3.3.1), | 2285 | | | PATCH (Section | 2286 | | | 3.3.2) | 2287 | mutability | The attempted modification | PUT (Section | 2288 | | is not compatible with the | 3.3.1), PATCH | 2289 | | target attributes mutability | (Section 3.3.2) | 2290 | | or current state (e.g. | | 2291 | | modification of an immutable | | 2292 | | attribute with an existing | | 2293 | | value). | | 2294 | invalidSynta | The request body message | POST (Search - | 2295 | x | structure was invalid or did | Section 3.2.2, | 2296 | | not conform to the request | Create - Section | 2297 | | schema. | 3.1, Bulk - Section | 2298 | | | 3.5), PUT (Section | 2299 | | | 3.3.1) | 2300 | invalidPath | The path attribute was | PATCH (Section | 2301 | | invalid or malformed (see | 3.3.2) | 2302 | | Figure 4). | | 2303 | noTarget | The specified "path" did not | PATCH (Section | 2304 | | yield an attribute or | 3.3.2) | 2305 | | attribute value that could | | 2306 | | be operated on. This occurs | | 2307 | | when the specified "path" | | 2308 | | value contains a filter that | | 2309 | | yields no match. | | 2310 | invalidValue | A required value was | GET (Section | 2311 | | missing, or the value | 3.2.2), POST | 2312 | | specified was not compatible | (Create - Section | 2313 | | with the operation or | 3.1, Search - | 2314 | | attribute type (see Section | Section 3.2.2), PUT | 2315 | | 2.1 [I-D.ietf-scim-core-sche | (Section 3.3.1), | 2316 | | ma]). | PATCH (Section | 2317 | | | 3.3.2) | 2318 | invalidVers | The specified API version is | GET (Section | 2319 | | not supported (see Section | 3.2.2), POST (ALL), | 2320 | | 3.11). | PUT (Section | 2321 | | | 3.3.1), PATCH | 2322 | | | (Section 3.3.2), | 2323 | | | DELETE (Section | 2324 | | | 3.4) | 2325 +--------------+------------------------------+---------------------+ 2327 Table 8: Table of Detail Error Keyword Values 2329 Note that in the table above (Table 8), the applicability table 2330 applies to the normal HTTP method but MAY apply within a SCIM Bulk 2331 operation (via HTTP POST). 2333 Error example in response to a non-existent GET request. 2335 HTTP/1.1 404 NOT FOUND 2337 { 2338 "schemas": ["urn:scim:api:messages:2.0:Error"], 2339 "detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 2340 "status":"404 2341 } 2343 Error example in response to a PUT request. 2345 HTTP/1.1 400 BAD REQUEST 2347 { 2348 "schemas": ["urn:scim:api:messages:2.0:Error"], 2349 "scimType":"mutability" 2350 "detail":"Attribute 'id' is readOnly", 2351 "status":"400" 2352 } 2354 [[Editor's note: while the detail error codes seem to have consensus, 2355 there is a question about whether the error codes should be 2356 extensible so that individual service providers may define site 2357 specific codes. Should all scimTypes be URIs, so that scimTypes can 2358 be registered via IANA? Should there be a separate field defined for 2359 this purpose? Or, should custom signalling (for non-protocol/schema 2360 errors, be out of scope?]] 2362 3.11. API Versioning 2364 The Base URL MAY be appended with a version identifier as a separate 2365 segment in the URL path. At this time of this specification, the 2366 identifier is 'v2'. If specified, the version identifier MUST appear 2367 in the URL path immediately preceding the resource endpoint and 2368 conform to the following scheme: the character 'v' followed by the 2369 desired SCIM version number; e.g., a version 'v2' User request is 2370 specified as /v2/Users. When specified service providers MUST 2371 perform the operation using the desired version or reject the 2372 request. When omitted service providers SHOULD perform the operation 2373 using the most recent API supported by the service provider. 2375 3.12. Versioning Resources 2377 The API supports resource versioning via standard HTTP ETags 2378 Section 2.3 [RFC7233]. Service providers MAY support weak ETags as 2379 the preferred mechanism for performing conditional retrievals and 2380 ensuring clients do not inadvertently overwrite each others changes, 2381 respectively. When supported SCIM ETags MUST be specified as an HTTP 2382 header and SHOULD be specified within the 'version' attribute 2383 contained in the resource's 'meta' attribute. 2385 Example: 2387 POST /Users HTTP/1.1 2388 Host: example.com 2389 Content-Type: application/json 2390 Authorization: Bearer h480djs93hd8 2391 Content-Length: ... 2393 { 2394 "schemas":["urn:scim:schemas:core:2.0:User"], 2395 "userName":"bjensen", 2396 "externalId":"bjensen", 2397 "name":{ 2398 "formatted":"Ms. Barbara J Jensen III", 2399 "familyName":"Jensen", 2400 "givenName":"Barbara" 2401 } 2402 } 2404 The server responds with an ETag in the response header and meta 2405 structure. 2407 HTTP/1.1 201 Created 2408 Content-Type: application/json 2409 Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2410 ETag: W/"e180ee84f0671b1" 2412 { 2413 "schemas":["urn:scim:schemas:core:2.0:User"], 2414 "id":"2819c223-7f76-453a-919d-413861904646", 2415 "meta":{ 2416 "resourceType":"User", 2417 "created":"2011-08-01T21:32:44.882Z", 2418 "lastModified":"2011-08-01T21:32:44.882Z", 2419 "location":"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2420 "version":"W\/\"e180ee84f0671b1\"" 2421 }, 2422 "name":{ 2423 "formatted":"Ms. Barbara J Jensen III", 2424 "familyName":"Jensen", 2425 "givenName":"Barbara" 2426 }, 2427 "userName":"bjensen" 2428 } 2430 With the returned ETag, clients MAY choose to retrieve the resource 2431 only if the resource has been modified. 2433 Conditional retrieval example using If-None-Match Section 3.2 2434 [RFC7233] header: 2436 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName 2437 Host: example.com 2438 Accept: application/json 2439 Authorization: Bearer h480djs93hd8 2440 If-None-Match: W/"e180ee84f0671b1" 2442 If the resource has not changed the service provider simply returns 2443 an empty body with a 304 "Not Modified" response code. 2445 If the service providers supports versioning of resources the client 2446 MAY supply an If-Match Section 3.1 [RFC7233] header for PUT and PATCH 2447 operations to ensure that the requested operation succeeds only if 2448 the supplied ETag matches the latest service provider resource; e.g., 2449 If-Match: W/"e180ee84f0671b1" 2451 4. Preparation and Comparison of Internationalized Strings 2453 To increase the likelihood that the input and comparison of unicode 2454 usernames and passwords will work in ways that make sense for typical 2455 users throughout the world there are special string preparation and 2456 comparison methods (PRECIS) that MUST be followed for usernames and 2457 passwords. Before comparing or evaluating uniqueness of a "userName" 2458 or "password" attribute, service providers MUST use the "PRECIS" 2459 profile described in Sections 4 and 5 respectively of 2460 [I-D.ietf-precis-saslprepbis] and is based on the "PRECIS" framework 2461 specification [I-D.ietf-precis-framework]. 2463 5. Multi-Tenancy 2465 A single service provider may expose the SCIM protocol to multiple 2466 clients. Depending on the nature of the service, the clients may 2467 have authority to access and alter resources initially created by 2468 other clients. Alternatively, clients may expect to access disjoint 2469 sets of resources, and may expect that their resources are 2470 inaccessible by other clients. These scenarios are called "multi- 2471 tenancy", where each client is understood to be or represent a 2472 "tenant" of the service provider. Clients may also be multi- 2473 tenanted. 2475 The following common cases may occur: 2477 1. All clients share all resources (no tenancy) 2479 2. Each single client creates and accesses a private subset of 2480 resources (1 client:1 Tenant) 2482 3. Sets of clients share sets of resources (M clients:1 Tenant) 2483 4. One client to Multiple Tenants (1 client:M Tenants) 2485 Service providers may implement any subset of the above cases. 2487 Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a 2488 scheme for multi-tenancy. 2490 The SCIM protocol does not prescribe the mechanisms whereby clients 2491 and service providers interact for: 2493 o Registering or provisioning Tenants 2495 o Associating a subset of clients with a subset of the Tenants 2497 o Indicating which tenant is associated with the data in a request 2498 or response, or indicating which Tenant is the subject of a query 2500 5.1. Associating Clients to Tenants 2502 The service provider MAY use the authentication mechanism (Section 2) 2503 to determine the identity of the client, and thus infer the 2504 associated Tenant. 2506 For implementations where a client is associated with more than one 2507 Tenant, the service provider MAY use one of the following methods for 2508 explicit specification of the Tenant. 2510 If any of these methods of allowing the client to explicitly specify 2511 the Tenant are employed, the service provider should ensure that 2512 access controls are in place to prevent or allow cross-tenant use 2513 cases. 2515 The service provider should consider precedence in cases where a 2516 client may explicitly specify a Tenant while being implicitly 2517 associated with a different Tenant. 2519 In all of these methods, the {tenant_id} is a unique identifier for 2520 the Tenant as defined by the service provider. 2522 o A URL prefix: "https://www.example.com/Tenants/{tenant_id}/v2/ 2523 Users" 2525 o A sub-domain: "https://{tenant_id}.example.com/v2/Groups" 2527 o The service provider may recognize a {tenant_id} provided by the 2528 client in an HTTP Header as the indicator of the desired target 2529 Tenant. 2531 5.2. SCIM Identifiers with Multiple Tenants 2533 Considerations for a Multi-Tenant Implementation: 2535 The service provider may choose to implement SCIM ids which are 2536 unique across all resources for all Tenants, but this is not 2537 required. 2539 The externalId, defined by the client, is required to be unique ONLY 2540 within the resources associated with the associated Tenant. 2542 6. Security Considerations 2544 6.1. TLS Support 2546 The SCIM Protocol layers on top of Hypertext Transfer Protocol and 2547 thus subject to the security considerations of HTTP Section 9 2548 [RFC7230] and its related specifications. 2550 SCIM resources (e.g., Users and Groups) can contain sensitive 2551 information. Therefore, SCIM clients and service providers MUST 2552 implement TLS. Which version(s) ought to be implemented will vary 2553 over time, and depend on the widespread deployment and known security 2554 vulnerabilities at the time of implementation. At the time of this 2555 writing, TLS version 1.2 [RFC5246] is the most recent version, but 2556 has very limited actual deployment, and might not be readily 2557 available in implementation toolkits. TLS version 1.0 [RFC2246] is 2558 the most widely deployed version, and will give the broadest 2559 interoperability. 2561 6.2. Request URI Information Leakage 2563 Clients requesting information using query filters using HTTP GET 2564 SHOULD give consideration to the information content of the filters 2565 and whether their exposure in a URI would represent a breach of 2566 security or confidentiality through leakage in a web browsers or 2567 server logs. This is particularly true for information that is 2568 legally considered "personally identifiable information" or is 2569 otherwise restricted by privacy laws. In these situations to ensure 2570 maximum security and confidentiality, clients SHOULD query using HTTP 2571 POST (see Section 3.2.3 ). 2573 Servers that receive HTTP GET requests using filters that contain 2574 restricted or confidential information SHOULD respond with HTTP 2575 status 403 indicating the operation is FORBIDDEN. A detialed error, 2576 "confidential_restricted" may be returned indicating the request must 2577 be submitted using POST. A non-normative example: 2579 HTTP/1.1 403 FORBIDDEN 2581 { 2582 "schemas": ["urn:scim:api:messages:2.0:Error"], 2583 "Errors":[ 2584 { 2585 "description":"Query filter involving 'name' is restricted or confidential", 2586 "error":"confidential_restricted" 2587 } 2588 ] 2589 } 2591 6.3. Case Insensitive Comparision & International Languages 2593 When comparing unicode strings such as in query filters or testing 2594 for uniqueness of usernames and passwords, strings MUST be 2595 appopriately prepared before comparison. See Section 4. 2597 6.4. Universal Identifiers 2599 7. IANA Considerations 2601 7.1. Media Type Registration 2603 To: ietf-types@iana.org 2605 Subject: Registration of media type application/scim+json 2607 Type name: application 2609 Subtype name: scim+json 2611 Required parameters: none 2613 Optional parameters: none 2615 Encoding considerations: 8bit 2617 Security considerations: See Section 6 2619 Interoperability considerations: The "application/scim+json" media 2620 type is intended to identify JSON structure data that conforms to 2621 the SCIM 2 api and schema specifications. Older versions of SCIM 2622 are known to informally use "application/json". 2624 Published specification: [[this document]] 2625 Applications that use this media type: It is expected that 2626 applications that use this type may be special purpose 2627 applications intended for inter-domain provisioning. Clients may 2628 also be applications (e.g. mobile applications) that need to use 2629 SCIM for self-registration of user accounts. SCIM services may be 2630 offered by web applications wishin to offer support for standards 2631 based provisioning or may be a dedicated SCIM service provider 2632 such as a "cloud directory". Content may be treated as equivalent 2633 to "application/json" type for the purpose of displaying in web 2634 browsers. 2636 Additional information: 2638 Magic number(s): 2640 File extension(s): .scim .scm 2642 Macintosh file type code(s): 2644 Person & email address to contact for futher information: SCIM 2645 mailing list "" 2647 Intended usage: COMMON* (see restrictions) 2649 Restrictions on usage: For most client types, it is sufficient to 2650 recognize the content as equivalent to "application/json". 2651 Applications intending to use the SCIM API SHOULD use the 2652 application/scim+json media type. 2654 Author: Phil Hunt 2656 Change controller: IETF 2658 7.2. SCIM API Message Schema Registry 2660 As per the IANA SCIM Schema Registry in [I-D.ietf-scim-core-schema], 2661 the following registers and extends the SCIM Schema Registry to 2662 define API request/response JSON schema URN identifier prefix of 2663 "urn:scim:api:messages:2.0" which is part of the URN sub-Namespace 2664 for SCIM. There is no specific associated resource type. 2666 +---------------------------------------+-----------+---------------+ 2667 | Schema URI | Name | Reference | 2668 +---------------------------------------+-----------+---------------+ 2669 | urn:scim:api:messages:2.0:ListRespons | List/Quer | See Section | 2670 | e | y | 3.2.2 | 2671 | | Response | | 2672 | urn:scim:api:messages:2.0:SearchReque | POST | See Section | 2673 | st | Query | 3.2.3 | 2674 | | Request | | 2675 | urn:scim:api:messages:2.0:PatchOp | Patch | See Section | 2676 | | Operation | 3.3.2 | 2677 | urn:scim:api:messages:2.0:BulkRequest | Bulk Oper | See Section | 2678 | | ations | 3.5 | 2679 | | Request | | 2680 | urn:scim:api:messages:2.0:BulkRespons | Bulk Oper | See Section | 2681 | e | ations | 3.5 | 2682 | | Response | | 2683 | urn:scim:api:messages:2.0:Error | Error | See Section | 2684 | | Response | 3.10 | 2685 +---------------------------------------+-----------+---------------+ 2687 SCIM Schema URIs for Data Resources 2689 8. References 2691 8.1. Normative References 2693 [I-D.ietf-precis-saslprepbis] 2694 Saint-Andre, P. and A. Melnikov, "Preparation and 2695 Comparison of Internationalized Strings Representing 2696 Usernames and Passwords", draft-ietf-precis-saslprepbis-07 2697 (work in progress), March 2014. 2699 [I-D.ietf-scim-core-schema] 2700 Grizzle, K., Hunt, P., Wahlstroem, E., and C. Mortimore, 2701 "System for Cross-Domain Identity Management: Core 2702 Schema", draft-ietf-scim-core-schema-06 (work in 2703 progress), June 2014. 2705 [IANA.Language] 2706 Internet Assigned Numbers Authority (IANA), "Language 2707 Subtag Registry", 2005. 2709 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2710 Requirement Levels", BCP 14, RFC 2119, March 1997. 2712 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2713 RFC 2246, January 1999. 2715 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2716 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2717 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2719 [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of 2720 Internationalized Strings ("stringprep")", RFC 3454, 2721 December 2002. 2723 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2724 10646", STD 63, RFC 3629, November 2003. 2726 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2727 Resource Identifier (URI): Generic Syntax", STD 66, RFC 2728 3986, January 2005. 2730 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2731 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2733 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2734 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2736 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 2737 5789, March 2010. 2739 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 2740 Framework: Bearer Token Usage", RFC 6750, October 2012. 2742 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 2743 Interchange Format", RFC 7159, March 2014. 2745 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2746 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 2747 2014. 2749 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2750 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 2752 [RFC7233] Fielding, R., Lafon, Y., and J. Reschke, "Hypertext 2753 Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, 2754 June 2014. 2756 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 2757 (HTTP/1.1): Authentication", RFC 7235, June 2014. 2759 8.2. Informative References 2761 [I-D.ietf-precis-framework] 2762 Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 2763 Preparation and Comparison of Internationalized Strings in 2764 Application Protocols", draft-ietf-precis-framework-17 2765 (work in progress), May 2014. 2767 [I-D.reschke-http-status-308] 2768 Reschke, J., "The Hypertext Transfer Protocol (HTTP) 2769 Status Code 308 (Permanent Redirect)", draft-reschke-http- 2770 status-308-07 (work in progress), March 2012. 2772 [OpenSearch] 2773 Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . 2775 [Order-Operations] 2776 Wikipedia, "Order of Operations: Programming Languages", . 2778 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 2779 Languages", BCP 18, RFC 2277, January 1998. 2781 [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation 2782 (JSON) Patch", RFC 6902, April 2013. 2784 Appendix A. Contributors 2786 Samuel Erdtman (samuel@erdtman.se) 2788 Patrick Harding (pharding@pingidentity.com) 2790 Appendix B. Acknowledgments 2792 The editors would like to acknowledge the contribution and work of 2793 the past draft editors: 2795 Trey Drake, UnboundID 2797 Chuck Mortimore, Salesforce 2799 The editor would like to thank the participants in the the SCIM 2800 working group for their support of this specification. 2802 Appendix C. Change Log 2804 [[This section to be removed prior to publication as an RFC]] 2806 Draft 02 - KG - Addition of schema extensibility 2807 Draft 03 - PH - Revisions based on following tickets: 2809 24 - Add filter negation 2811 39 - Clarification on response for DELETE 2813 42 - Make root searches optional 2815 49 - Add "ew" filter 2817 50 - Filters for multi-valued complex attributes 2819 51 - Search by Schema 2821 53 - Standard use of term client (some was consumer) 2823 55 - Redirect support (3xx) 2825 56 - Make manager attribute consistent with other $ref attrs 2827 57 - Update all "/v1" examples to '/v2" 2829 59 - Fix capitalization per IETF editor practices 2831 60 - Changed tags to normal and tags 2833 Draft 04 - PH - Revisions based on the following tickets: 2835 18 - New PATCH command based on JSON Patch (RFC6902) 2837 - Provided ABNF specification for filters (used in PATCH) 2839 - Updated references to RFC4627 to RFC7159 2841 Draft 05 - PH - Revisions based on the following tickets: 2843 03 - Support for excludedAttributes parameter 2845 13 - Change client use of Etags from MUST to MAY (correction) 2847 23 - Clarifications regarding case exact processing. 2849 41 - Add IANA considerations 2851 65 - Removed X-HTTP-Method-Override support 2853 69 - Added clarifications to intro to align with draft-nottingham- 2854 uri-get-off-my-lawn 2855 70 - Remove SCIM_TENANT_ID header 2857 72 - Added text to indicate UTF-8 is default and mandatory 2858 encoding format per BCP18 2860 74 - Added security considerations for using GET with confidential 2861 attribute filters 2863 - corrected error response in JSON PATCH operation 2865 Draft 06 - PH - Revisions based on the following tickets and 2866 editorial changes 2868 41 - Revised content types from application/json to application/ 2869 scim+json, registered API schemas 2871 63 - Revised uri schema prefixes for API json message schemas 2873 66 - Updated references for RFC2616 to HTTPbis 2875 75 - Added security considerations for International Strings and 2876 "PRECIS" support 2878 76 - Clarified handling of PUT (& POST) with regards to mutability 2879 and default values 2881 - Corrected version numbers in sec 3.11 API Versioning to v2 (from 2882 v1) 2884 - Clarified that no filter matches should return success 2885 totalResults=0 2887 Draft 07 - PH - Revisions regarding support of detailed errors 2888 (Tickets 37, 46, 67) 2890 Authors' Addresses 2892 Phil Hunt (editor) 2893 Oracle Corporation 2895 Email: phil.hunt@yahoo.com 2897 Kelly Grizzle 2898 SailPoint 2900 Email: kelly.grizzle@sailpoint.com 2901 Morteza Ansari 2902 Cisco 2904 Email: morteza.ansari@cisco.com 2906 Erik Wahlstroem 2907 Technology Nexus 2909 Email: erik.wahlstrom@nexussafe.com 2911 Chuck Mortimore 2912 Salesforce.com 2914 Email: cmortimore@salesforce.com