idnits 2.17.1 draft-ietf-scim-api-19.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 15, 2015) is 3268 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-18) exists of draft-ietf-precis-saslprepbis-16 == Outdated reference: A later version (-22) exists of draft-ietf-scim-core-schema-20 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** 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 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7233 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7538 (Obsoleted by RFC 9110) == Outdated reference: A later version (-08) exists of draft-ietf-oauth-pop-architecture-01 -- Obsolete informational reference (is this intentional?): RFC 7525 (Obsoleted by RFC 9325) Summary: 9 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Hunt, Ed. 3 Internet-Draft Oracle 4 Intended status: Standards Track K. Grizzle 5 Expires: November 16, 2015 SailPoint 6 M. Ansari 7 Cisco 8 E. Wahlstroem 9 Nexus Technology 10 C. Mortimore 11 Salesforce 12 May 15, 2015 14 System for Cross-Domain Identity Management: Protocol 15 draft-ietf-scim-api-19 17 Abstract 19 The System for Cross-Domain Identity Management (SCIM) specification 20 is an HTTP based protocol that makes managing identities in multi- 21 domain scenarios easier to support through a standardized service. 22 Examples include but are not limited to enterprise to cloud service 23 providers, and inter-cloud based scenarios. The specification suite 24 seeks to build upon experience with existing schemas and deployments, 25 placing specific emphasis on simplicity of development and 26 integration, while applying existing authentication, authorization, 27 and privacy models. SCIM's intent is to reduce the cost and 28 complexity of user management operations by providing a common user 29 schema, an extension model, and a service protocol defined by this 30 document. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on November 16, 2015. 49 Copyright Notice 51 Copyright (c) 2015 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 67 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3 68 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 4 69 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 70 2. Authentication and Authorization . . . . . . . . . . . . . . 5 71 2.1. Use of Tokens as Authorizations . . . . . . . . . . . . . 7 72 2.2. Anonymous Requests . . . . . . . . . . . . . . . . . . . 7 73 3. SCIM Protocol . . . . . . . . . . . . . . . . . . . . . . . . 8 74 3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 8 75 3.2. SCIM Endpoints and HTTP Methods . . . . . . . . . . . . . 9 76 3.3. Creating Resources . . . . . . . . . . . . . . . . . . . 10 77 3.3.1. Resource Types . . . . . . . . . . . . . . . . . . . 13 78 3.4. Retrieving Resources . . . . . . . . . . . . . . . . . . 13 79 3.4.1. Retrieving a known Resource . . . . . . . . . . . . . 13 80 3.4.2. Query Resources . . . . . . . . . . . . . . . . . . . 14 81 3.4.3. Querying Resources Using HTTP POST . . . . . . . . . 26 82 3.5. Modifying Resources . . . . . . . . . . . . . . . . . . . 29 83 3.5.1. Replacing with PUT . . . . . . . . . . . . . . . . . 29 84 3.5.2. Modifying with PATCH . . . . . . . . . . . . . . . . 31 85 3.6. Deleting Resources . . . . . . . . . . . . . . . . . . . 45 86 3.7. Bulk Operations . . . . . . . . . . . . . . . . . . . . . 46 87 3.7.1. Circular Reference Processing . . . . . . . . . . . . 48 88 3.7.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 51 89 3.7.3. Response and Error Handling . . . . . . . . . . . . . 55 90 3.7.4. Maximum Operations . . . . . . . . . . . . . . . . . 60 91 3.8. Data Input/Output Formats . . . . . . . . . . . . . . . . 61 92 3.9. Additional Operation Response Parameters . . . . . . . . 62 93 3.10. Attribute Notation . . . . . . . . . . . . . . . . . . . 63 94 3.11. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 63 95 3.12. HTTP Status and Error Response Handling . . . . . . . . . 64 96 3.13. SCIM Protocol Versioning . . . . . . . . . . . . . . . . 68 97 3.14. Versioning Resources . . . . . . . . . . . . . . . . . . 68 98 4. Service Provider Configuration Endpoints . . . . . . . . . . 70 99 5. Preparation and Comparison of Internationalized Strings . . . 72 100 6. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 73 101 6.1. Associating Clients to Tenants . . . . . . . . . . . . . 73 102 6.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 74 103 7. Security Considerations . . . . . . . . . . . . . . . . . . . 74 104 7.1. HTTP Considerations . . . . . . . . . . . . . . . . . . . 74 105 7.2. TLS Support Considerations . . . . . . . . . . . . . . . 75 106 7.3. Authorization Token Considerations . . . . . . . . . . . 75 107 7.4. Bearer and Cookie Considerations . . . . . . . . . . . . 75 108 7.5. Privacy Considerations . . . . . . . . . . . . . . . . . 76 109 7.5.1. Personal Information . . . . . . . . . . . . . . . . 76 110 7.5.2. Disclosure of Sensitive Information in URIs . . . . . 76 111 7.6. Anonymous Requests . . . . . . . . . . . . . . . . . . . 77 112 7.7. Secure Storage and Handling of Sensitive Data . . . . . . 77 113 7.8. Case Insensitive Comparison & International Languages . . 78 114 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 78 115 8.1. Media Type Registration . . . . . . . . . . . . . . . . . 78 116 8.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 79 117 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 80 118 9.1. Normative References . . . . . . . . . . . . . . . . . . 80 119 9.2. Informative References . . . . . . . . . . . . . . . . . 82 120 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 83 121 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 83 122 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 83 123 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 88 125 1. Introduction and Overview 127 The SCIM Protocol is an application-level, HTTP protocol for 128 provisioning and managing identity data on the web and in cross- 129 domain environments such as enterprise to cloud, or inter-cloud 130 scenarios. The protocol supports creation, modification, retrieval, 131 and discovery of core identity resources such as Users and Groups, as 132 well as custom resources and resource extensions. 134 The definition of resources, attributes, and overall schema are 135 defined in the SCIM Core Schema document (see 136 [I-D.ietf-scim-core-schema]). [[RFC Editor: These specifications 137 should be published together]] 139 1.1. Intended Audience 141 This document is intended as a guide to SCIM protocol usage for both 142 SCIM HTTP service providers and HTTP clients who may provision 143 information to service providers or retrieve information from them. 145 1.2. Notational Conventions 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 149 document are to be interpreted as described in [RFC2119]. These 150 keywords are capitalized when used to unambiguously specify 151 requirements of the protocol or application features and behavior 152 that affect the interoperability and security of implementations. 153 When these words are not capitalized, they are meant in their 154 natural-language sense. 156 For purposes of readability examples are not URL encoded. 157 Implementers MUST percent encode URLs as described in Section 2.1 of 158 [RFC3986]. 160 Throughout this documents all figures may contain spaces and extra 161 line-wrapping for readability and space limitations. Similarly, some 162 URI's contained within examples, have been shortened for space and 163 readability reasons. 165 1.3. Definitions 167 This specification uses the definitions from 168 [I-D.ietf-scim-core-schema], and defines the following additional 169 terms: 171 Base URI 172 The SCIM HTTP protocol is described in terms of a path relative to 173 a Base URI. The Base URI MUST NOT contain a query string as 174 clients MAY append additional path information and query 175 parameters as part of forming the request. The base URI most 176 often is a URL which most often consists of the "https" protocol 177 scheme, a domain name and some initial path [RFC3986]. Example: 178 "https://example.com/scim/" 180 For readability, all examples in this document are expressed 181 assuming the SCIM service root and the server root are the same 182 (no path pre-fix). It is expected that SCIM servers may be 183 deployed using any URI path prefix. For example, a SCIM server 184 might be have a prefix of "https://example.com/", or 185 "https://example.com/scim/tenancypath/". Additionally a client 186 MAY also apply a version number to the server root prefix (see 187 Section 3.13 ). 189 2. Authentication and Authorization 191 SCIM Protocol is based upon HTTP and does not itself define a SCIM 192 specific scheme for authentication and authorization. SCIM depends 193 on the use of TLS and/or standard HTTP authentication and 194 authorization schemes as per [RFC7235]. For example, the following 195 methodologies could be used among others: 197 TLS Client Authentication 198 The SCIM service provider MAY request TLS client authentication 199 (also known as mutual authentication). See Section 7.3 [RFC5246]. 201 HOBA Authentication 202 HTTP Origin-Bound Authentication (HOBA) is a variation on TLS 203 client authentication and uses a digital-signature-based design 204 for an HTTP authentication method (see [RFC7486]). The design can 205 also be used in JavaScript-based authentication embedded in HTML. 206 HOBA is an alternative to HTTP authentication schemes that require 207 passwords and therefore avoids all problems related to passwords, 208 such as leakage of server-side password databases. 210 Bearer Tokens 211 Bearer tokens [RFC6750] MAY be used when combined with TLS and a 212 token framework such as OAuth 2.0 [RFC6749]. Tokens that are 213 issued based on weak or no authentication of authorizing users 214 and/or OAuth clients SHOULD NOT be used, unless for example, they 215 are being used as single-use tokens to permit one-time requests 216 such as anonymous registration (see Section 3.3). For security 217 considerations regarding the use of bearer tokens in SCIM see 218 Section 7.4. While bearer tokens most often represent an 219 authorization, it is assumed that the authorization was based upon 220 a successful authentication of the SCIM client. Accordingly the 221 SCIM service provider must have a method for validating, parsing, 222 and or introspecting the bearer token for the relevant 223 authentication and authorization information. The method for this 224 is assumed to be defined by the token issuing system and is beyond 225 the scope of this specification. 227 POP Tokens 228 A proof-of-possession token demonstrates the presenter of the 229 token possesses a particular key and that the recipient can 230 cryptographically confirm proof-of-possession of the key by the 231 presenter. This property is sometimes also described as the 232 presenter being a holder-of-key. See OAuth 2.0 Proof-of- 233 Possession Security Architecture [I-D.ietf-oauth-pop-architecture] 234 for an example of such a token and its use. 236 Cookies 237 Javascript clients MAY assert HTTP cookies over TLS that contain 238 an authentication state that is understood by the SCIM service 239 provider (see [RFC6265]). An example of this is scenarios where 240 web-form authentication has taken place with the user and HTTP 241 cookies were set representing the authentication state. For the 242 purposes of SCIM, the security considerations in Section 7.4 243 apply. 245 Basic Authentication 246 Usage of basic authentication should be avoided due to its use of 247 a single factor that is based upon a relatively static, symmetric 248 secret. Implementers SHOULD combine the use of basic 249 authentication with other factors. The security considerations of 250 HTTP BASIC, are well documented in 251 [I-D.ietf-httpauth-basicauth-update], and therefore implementers 252 are encouraged to prefer stronger authentication methods. 253 Designating the specific methods of authentication and 254 authorization are out-of-scope for SCIM, however this information 255 is provided as a resource to implementers. 257 As per Section 4.1 of [RFC7235], a SCIM service provider SHALL 258 indicate supported HTTP authentication schemes via the "WWW- 259 Authenticate" header. 261 Regardless of methodology, the SCIM service provider MUST be able to 262 map the authenticated client to an access control policy in order to 263 determine the client's authorization to retrieve and update SCIM 264 resources. For example, while a browser session may have been 265 established via HTTP cookie or TLS client authentication, the unique 266 client MUST be mapped to a security subject (e.g., User). The 267 authorization model and the process by which this is done is beyond 268 the scope of this specification. 270 When processing requests, the service provider SHOULD consider the 271 subject performing the request and whether the action is appropriate 272 given the subject and the resource affected by the request. The 273 subject performing the request is usually determined directly or 274 indirectly from the "Authorization" header present in the request. 275 For example, a subject MAY be permitted to retrieve and update their 276 own "User" resource, but will normally have restricted ability to 277 access resources associated with other Users. In other cases, the 278 SCIM service provider might only grant access to a subject's own 279 associated "User" resource (e.g., for the purpose of updating 280 personal contact attributes). 282 For illustrative purposes only, SCIM protocol examples show an OAuth2 283 bearer token value [RFC6750] in the authorization header; e.g., 284 GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 285 Host: example.com 286 Authorization: Bearer h480djs93hd8 288 This is not intended to imply that bearer tokens are preferred. 289 However, the use of bearer tokens in the specification does reflect 290 common implementation practice. 292 2.1. Use of Tokens as Authorizations 294 When using bearer tokens or proof-of-possession tokens that represent 295 an authorization grant such as issued by OAuth (see [RFC6749]), 296 implementers SHOULD consider the type of authorization granted, any 297 authorized scopes (see Section 3.3 of [RFC6749]), and the security 298 subject(s) that SHOULD be mapped from the authorization when 299 considering local access control rules. Section 6 of the OAuth 300 Assertions draft [I-D.ietf-oauth-assertions], documents common 301 scenarios for authorization including: 303 o Clients using an assertion to authenticate and/or act on behalf of 304 itself; 306 o Clients acting on behalf of a user; and, 308 o A Client acting on behalf of an anonymous user (e.g., see next 309 section). 311 When using OAuth authorization tokens, implementers MUST take into 312 account the threats and countermeasures documented in the security 313 considerations for the use of client authorizations (see Section 8 of 314 [I-D.ietf-oauth-assertions]). When using other token formats or 315 frameworks, implementers MUST take into account similar threats and 316 countermeasures, especially those documented by the relevant 317 specifications. 319 2.2. Anonymous Requests 321 In some SCIM deployments it MAY be acceptable to permit 322 unauthenticated (anonymous) requests. For example, a user self- 323 registration request where the service provider chooses to accept a 324 SCIM Create request (see Section 3.3) from an anonymous client. See 325 Section 7.6, for security considerations regarding anonymous 326 requests. 328 3. SCIM Protocol 330 3.1. Introduction 332 SCIM is a protocol that is based on HTTP protocol [RFC7230]. Along 333 with HTTP headers and URIs, SCIM uses JSON [RFC7159] payloads to 334 convey both SCIM resources, as well as protocol specific payload 335 messages that convey request parameters and response information such 336 as errors. Both resources and messages are passed in the form of 337 JSON based structures in the message body of an HTTP request or 338 response. To identify this content, SCIM uses a media type of 339 "application/scim+json" (see Section 8.1). 341 A SCIM "resource" is a JSON object [RFC7159] that may be created, 342 maintained, and retrieved through HTTP request methods as described 343 in this document. Each JSON resource representation contains a 344 "schemas" attribute that contains a list of one or more URIs that 345 indicate included SCIM schemas that are used to indicate the 346 attributes contained within a resource. Specific information about 347 what attributes are defined within a schema MAY be obtained by 348 querying a SCIM service provider's "/Schemas" endpoint for a schema 349 definition (see Section 8.7 [I-D.ietf-scim-core-schema]). Responses 350 from this endpoint describe how a service provider supports a schema 351 and in particular how attribute qualities such as cardinality, case- 352 exactness, mutability, uniqueness, returnability, and whether an 353 attribute is required. While SCIM schemas and associated extension 354 model are defined in [I-D.ietf-scim-core-schema], SCIM clients should 355 expect that some attribute schema may change from service provider to 356 service provider, particularly across administrative domains. In 357 cases where SCIM may be used as an open protocol in front of an 358 application service, it is quite reasonable to expect that some 359 service providers may only support a sub-set of the schema defined in 360 [I-D.ietf-scim-core-schema]. 362 A SCIM message conveys protocol parameters about a SCIM request or 363 response that are defined by this specification. As with a SCIM 364 resource, a SCIM message is a JSON object [RFC7159] that contains a 365 "schemas" attribute with a URI whose namespace prefix that MUST begin 366 with "urn:ietf:params:scim:api:". As SCIM protocol messages are 367 fixed and defined by SCIM specifications and registered extensions, 368 SCIM message schemas using the above prefix URN SHALL NOT be 369 discoverable using the "/Schemas" endpoint. 371 As SCIM is intended for use in cross-domain scenarios where schema 372 and implementations may vary, techniques such as document validation, 373 such as in [XML-Schema], are not recommended. A SCIM service 374 provider interprets a request in the context of its own schema (which 375 may be different from the client's schema) and following the defined 376 processing rules for each request. The following sections in this 377 document define the processing rules for SCIM and provide allowances 378 for schema differences where appropriate. For example, in a SCIM PUT 379 request, "readOnly" attributes are ignored, while "readWrite" 380 attributes are updated. There is no need for a SCIM client to 381 discover which attributes are "readOnly" and the client does not need 382 to remove them from a PUT request in order to be accepted. Similarly 383 a SCIM client SHOULD NOT expect a service provider to return SCIM 384 resources with exactly the same schema and values as submitted. SCIM 385 responses SHALL reflect resource state as interpreted by the SCIM 386 service provider. 388 3.2. SCIM Endpoints and HTTP Methods 390 The SCIM protocol specifies well-known endpoints and HTTP methods for 391 managing resources defined in the core schema; i.e., "User" and 392 "Group" resources correspond to "/Users" and "/Groups" respectively. 393 Service providers that support extended resources SHOULD define 394 resource endpoints using the convention of pluralizing the resource 395 name defined in the extended schema by appending an 's'. Given there 396 are cases where resource pluralization is ambiguous; e.g., a resource 397 named "Person" is legitimately "Persons" and "People", clients SHOULD 398 discover resource endpoints via the "/ResourceTypes" endpoint. 400 HTTP SCIM Usage 401 Method 402 ------ -------------------------------------------------------------- 403 GET Retrieves one or more complete or partial resources. 404 POST Depending on the endpoint, creates new resources, create a 405 search request, or MAY be used to bulk modify resources. 406 PUT Modifies a resource by replacing existing attributes with a 407 specified set of replacement attributes (replace). PUT MUST 408 NOT be used to create new resources. 409 PATCH Modifies a resource with a set of client specified changes 410 (partial update). 411 DELETE Deletes a resource. 413 Table 1: SCIM HTTP Methods 415 Resource Endpoint Operations Description 416 -------- ---------------- ---------------------- -------------------- 417 User /Users GET (Section 3.4.1), Retrieve, Add, 418 POST (Section 3.3), Modify Users 419 PUT (Section 3.5.1), 420 PATCH (Section 3.5.2), 421 DELETE (Section 3.6) 422 Group /Groups GET (Section 3.4.1), Retrieve, Add, 423 POST (Section 3.3), Modify Groups 424 PUT (Section 3.5.1), 425 PATCH (Section 3.5.2), 426 DELETE (Section 3.6) 427 Self /Me GET, POST, PUT, PATCH, Alias for operations 428 DELETE (Section 3.11) against a resource 429 mapped to an 430 authenticated 431 Subject (e.g., 432 User). 433 Service /ServiceProvider GET (Section 4) Retrieve Service 434 Provider Config Provider's 435 Config configuration 436 Resource /ResourceTypes GET (Section 4) Retrieve supported 437 Type resource types 438 Schema /Schemas GET (Section 4) Retrieve one or more 439 supported schemas. 440 Bulk /Bulk POST (Section 3.7) Bulk updates to one 441 or more resources 442 Search [prefix]/.search POST (Section 3.4.3) Search from system 443 root or within a 444 resource endpoint 445 for one or more 446 resource types using 447 POST. 449 Table 2: Defined endpoints 451 All requests to the service provider are made via HTTP Methods as per 452 Section 4.3 [RFC7231] on a URL derived from the Base URL. Responses 453 are returned in the body of the HTTP response, formatted as JSON. 454 Error status codes SHOULD be transmitted via the HTTP status code of 455 the response (if possible), and SHOULD also be specified in the body 456 of the response (see Section 3.12). 458 3.3. Creating Resources 460 To create new resources, clients send HTTP POST requests to the 461 resource endpoint such as: "/Users" or "/Groups", as defined by the 462 associated resource type endpoint discovery (see Section 4). 464 The server SHALL process attributes according to the following 465 mutability rules: 467 o Attributes in the request body, whose mutability is "readOnly" 468 (see Section 2.2 of [I-D.ietf-scim-core-schema]), SHALL be 469 ignored. 471 o Attributes whose mutability is "readWrite"(see Section 2.2 of 472 [I-D.ietf-scim-core-schema]), that are omitted from the request 473 body, MAY be assumed to be not asserted by the client. The 474 service provider MAY assign a default value to non-asserted 475 attributes in the final resource representation. 477 o Service providers MAY take into account whether a client has 478 access to all of the resource's attributes when deciding whether 479 non-asserted attributes should be defaulted. 481 o Clients that intend to override existing or server defaulted 482 values for attributes MAY specify "null" for a single-valued 483 attribute or an empty array "[]" for a multi-valued attribute to 484 clear all values. 486 When the service provider successfully creates the new resource, an 487 HTTP response SHALL be returned with HTTP status "201" ("Created"). 488 The response body SHOULD contain the service provider's 489 representation of the newly created resource. The URI of the created 490 resource SHALL included in the HTTP "Location" header and theHTTP 491 body, a JSON representation [RFC7159] with the attribute 492 "meta.location". Since the server is free to alter and/or ignore 493 POSTed content, returning the full representation can be useful to 494 the client, enabling it to correlate the client and server views of 495 the new resource. 497 If the service provider determines creation of the requested resource 498 conflicts with existing resources; e.g., a "User" resource with a 499 duplicate "userName", the service provider MUST return an HTTP Status 500 409, with "scimType" error code of "uniqueness" as per Section 3.12. 502 In the following example, a client sends a POST request containing a 503 "User" to the "/Users" endpoint. 505 POST /Users HTTP/1.1 506 Host: example.com 507 Accept: application/scim+json 508 Content-Type: application/scim+json 509 Authorization: Bearer h480djs93hd8 510 Content-Length: ... 512 { 513 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 514 "userName":"bjensen", 515 "externalId":"bjensen", 516 "name":{ 517 "formatted":"Ms. Barbara J Jensen III", 518 "familyName":"Jensen", 519 "givenName":"Barbara" 520 } 521 } 523 In response to the example request above, the server signals a 524 successful creation with an HTTP status code 201 (Created) and 525 returns a representation of the resource created. 527 HTTP/1.1 201 Created 528 Content-Type: application/scim+json 529 Location: 530 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 531 ETag: W/"e180ee84f0671b1" 533 { 534 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 535 "id":"2819c223-7f76-453a-919d-413861904646", 536 "externalId":"bjensen", 537 "meta":{ 538 "resourceType":"User", 539 "created":"2011-08-01T21:32:44.882Z", 540 "lastModified":"2011-08-01T21:32:44.882Z", 541 "location": 542 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 543 "version":"W\/\"e180ee84f0671b1\"" 544 }, 545 "name":{ 546 "formatted":"Ms. Barbara J Jensen III", 547 "familyName":"Jensen", 548 "givenName":"Barbara" 549 }, 550 "userName":"bjensen" 551 } 553 3.3.1. Resource Types 555 When adding a resource to a specific endpoint, the meta attribute 556 "resourceType" SHALL be set by the HTTP service provider to the 557 corresponding resource type for the endpoint. For example, a POST to 558 the endpoint "/Users" will set "resourceType" to "User", and 559 "/Groups" will set "resourceType" to "Group". 561 3.4. Retrieving Resources 563 Resources MAY be retrieved via opaque, unique URLs or via Query (see 564 Section 3.4.2). The attributes returned are defined in the server's 565 attribute schema (see Section 8.7 [I-D.ietf-scim-core-schema]) and 566 request parameters (see Section 3.9). By default, resource 567 attributes returned in a response are those attributes whose 568 characteristic "returned" setting is "always" or "default" (see 569 Section 2.2 of [I-D.ietf-scim-core-schema]). 571 3.4.1. Retrieving a known Resource 573 To retrieve a known resource, clients send GET requests to the 574 resource endpoint; e.g., "/Users/{id}" or "/Groups/{id}", or 575 "/Schemas/{id}", where "{id}" is a resource identifier (for example 576 the value of the "id" attribute). 578 If the resource exists the server responds with HTTP Status code 200 579 (OK) and includes the result in the body of the response. 581 The below example retrieves a single User via the "/Users" endpoint. 583 GET /Users/2819c223-7f76-453a-919d-413861904646 584 Host: example.com 585 Accept: application/scim+json 586 Authorization: Bearer h480djs93hd8 588 The server responds with: 590 HTTP/1.1 200 OK 591 Content-Type: application/scim+json 592 Location: 593 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 594 ETag: W/"f250dd84f0671c3" 596 { 597 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 598 "id":"2819c223-7f76-453a-919d-413861904646", 599 "externalId":"bjensen", 600 "meta":{ 601 "resourceType":"User", 602 "created":"2011-08-01T18:29:49.793Z", 603 "lastModified":"2011-08-01T18:29:49.793Z", 604 "location": 605 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 606 "version":"W\/\"f250dd84f0671c3\"" 607 }, 608 "name":{ 609 "formatted":"Ms. Barbara J Jensen III", 610 "familyName":"Jensen", 611 "givenName":"Barbara" 612 }, 613 "userName":"bjensen", 614 "phoneNumbers":[ 615 { 616 "value":"555-555-8377", 617 "type":"work" 618 } 619 ], 620 "emails":[ 621 { 622 "value":"bjensen@example.com", 623 "type":"work" 624 } 625 ] 626 } 628 3.4.2. Query Resources 630 The SCIM protocol defines a standard set of query parameters that can 631 be used to filter, sort, and paginate to return zero or more 632 resources in a query response. Queries MAY be made against a single 633 resource or a resource type endpoint (e.g., "/Users"), or the service 634 provider Base URI. SCIM service providers MAY support additional 635 query parameters not specified here and SHOULD ignore any query 636 parameters they do not recognize instead of rejecting the query for 637 versioning compatibility reasons. 639 Responses MUST be identified using the following URI: 640 "urn:ietf:params:scim:api:messages:2.0:ListResponse". The following 641 attributes are defined for responses: 643 totalResults The total number of results returned by the list or 644 query operation. The value may be larger than the number of 645 resources returned such as when returning a single page (see 646 Section 3.4.2.4) of results where multiple pages are available. 647 REQUIRED. 649 Resources A multi-valued list of complex objects containing the 650 requested resources. This MAY be a subset of the full set of 651 resources if pagination (Section 3.4.2.4) is requested. REQUIRED 652 if "totalResults" is non-zero. 654 startIndex The 1-based index of the first result in the current set 655 of list results. REQUIRED when partial results returned due to 656 pagination. 658 itemsPerPage The number of resources returned in a list response 659 page. REQUIRED when partial results returned due to pagination. 661 A query that does not return any matches SHALL return success (HTTP 662 Status 200) with "totalResults" set to a value of 0. 664 The example query below requests the userName for all Users: 666 GET /Users?attributes=userName 667 Host: example.com 668 Accept: application/scim+json 669 Authorization: Bearer h480djs93hd8 670 The following is an example response to the query above: 672 HTTP/1.1 200 OK 673 Content-Type: application/scim+json 675 { 676 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 677 "totalResults":2, 678 "Resources":[ 679 { 680 "id":"2819c223-7f76-453a-919d-413861904646", 681 "userName":"bjensen" 682 }, 683 { 684 "id":"c75ad752-64ae-4823-840d-ffa80929976c", 685 "userName":"jsmith" 686 } 687 ] 688 } 690 Note that in the above example, "id" is returned because the "id" 691 attribute has the "returned" characteristic of "always". 693 3.4.2.1. Query Endpoints 695 Queries MAY be performed against a SCIM resource object, a resource 696 type endpoint, or a SCIM server root. For example: 698 "/Users/{id}" 700 "/Users" 702 "/Groups" 704 A query against a server root indicates that all resources within the 705 server SHALL be included subject to filtering. A filter expression 706 using "meta.resourceType" MAY be used to restrict results to one or 707 more specific resource types (to exclude others). For example: 709 filter=(meta.resourceType eq User) or (meta.resourceType eq Group) 711 If a SCIM service provider determines that too many results would be 712 returned (e.g., because a client queried a resource type endpoint or 713 the server base URI), the server SHALL reject the request by 714 returning an HTTP response with "status" 400 and json attribute 715 "scimType" set to "tooMany" (see Table 9). 717 When processing query operations using endpoints that include more 718 than one SCIM resource type (e.g., a query from the server root 719 endpoint), filters MUST be processed as outlined in Section 3.4.2.2. 720 For filtered attributes that are not part of a particular resource 721 type, the service provider SHALL treat the attribute as if there is 722 no attribute value. For example, a presence or equality filter for 723 an undefined attribute evaluates as FALSE. 725 3.4.2.2. Filtering 727 Filtering is an OPTIONAL parameter for SCIM service providers. 728 Clients MAY discover service provider filter capabilities by looking 729 at the "filter" attribute of the "ServiceProviderConfig" (see 730 Section 4). Clients MAY request a subset of resources by specifying 731 the "filter" query parameter containing a filter expression. When 732 specified only those resources matching the filter expression SHALL 733 be returned. The expression language that is used with the filter 734 parameter supports references to attributes and literals. 736 Attribute names and attribute operators used in filters are case 737 insensitive. For example, the following two expressions will 738 evaluate to the same logical value: 740 filter=userName Eq "john" 742 filter=Username eq "john" 744 The filter parameter MUST contain at least one valid expression (see 745 Table 3). Each expression MUST contain an attribute name followed by 746 an attribute operator and optional value. Multiple expressions MAY 747 be combined using a logical operators (see Table 4). Expressions MAY 748 be grouped together using brackets "(" and ")" (see Table 5). 750 The operators supported in the expression are listed in the following 751 table. 753 +----------+-------------+------------------------------------------+ 754 | Operator | Description | Behavior | 755 +----------+-------------+------------------------------------------+ 756 | eq | equal | The attribute and operator values must | 757 | | | be identical for a match. | 758 | ne | not equal | The attribute and operator values are | 759 | | | not identical. | 760 | co | contains | The entire operator value must be a | 761 | | | substring of the attribute value for a | 762 | | | match. | 763 | sw | starts with | The entire operator value must be a | 764 | | | substring of the attribute value, | 765 | | | starting at the beginning of the | 766 | | | attribute value. This criterion is | 767 | | | satisfied if the two strings are | 768 | | | identical. | 769 | ew | ends with | The entire operator value must be a | 770 | | | substring of the attribute value, | 771 | | | matching at the end of the attribute | 772 | | | value. This criterion is satisfied if | 773 | | | the two strings are identical. | 774 | pr | present | If the attribute has a non-empty or non- | 775 | | (has value) | null value, or if it contains a non- | 776 | | | empty node for complex attributes there | 777 | | | is a match. | 778 | gt | greater | If the attribute value is greater than | 779 | | than | operator value, there is a match. The | 780 | | | actual comparison is dependent on the | 781 | | | attribute type. For string attribute | 782 | | | types, this is a lexicographical | 783 | | | comparison and for DateTime types, it is | 784 | | | a chronological comparison. For Integer | 785 | | | attributes it is a comparison by numeric | 786 | | | value. Boolean and Binary attributes | 787 | | | SHALL cause a failed response (HTTP | 788 | | | Status 400) with scimType of | 789 | | | invalidFilter. | 790 | ge | greater | If the attribute value is greater than | 791 | | than or | or equal to the operator value, there is | 792 | | equal | a match. The actual comparison is | 793 | | | dependent on the attribute type. For | 794 | | | string attribute types, this is a | 795 | | | lexicographical comparison and for | 796 | | | DateTime types, it is a chronological | 797 | | | comparison. For Integer attributes it is | 798 | | | a comparison by numeric value. Boolean | 799 | | | and Binary attributes SHALL cause a | 800 | | | failed response (HTTP Status 400) with | 801 | | | scimType of invalidFilter. | 802 | lt | less than | If the attribute value is less than | 803 | | | operator value, there is a match. The | 804 | | | actual comparison is dependent on the | 805 | | | attribute type. For string attribute | 806 | | | types, this is a lexicographical | 807 | | | comparison and for DateTime types, it is | 808 | | | a chronological comparison. For Integer | 809 | | | attributes it is a comparison by numeric | 810 | | | value. Boolean and Binary attributes | 811 | | | SHALL cause a failed response (HTTP | 812 | | | Status 400) with scimType of | 813 | | | invalidFilter. | 814 | le | less than | If the attribute value is less than or | 815 | | or equal | equal to the operator value, there is a | 816 | | | match. The actual comparison is | 817 | | | dependent on the attribute type. For | 818 | | | string attribute types, this is a | 819 | | | lexicographical comparison and for | 820 | | | DateTime types, it is a chronological | 821 | | | comparison. For Integer attributes it is | 822 | | | a comparison by numeric value. Boolean | 823 | | | and Binary attributes SHALL cause a | 824 | | | failed response (HTTP Status 400) with | 825 | | | scimType of invalidFilter. | 826 +----------+-------------+------------------------------------------+ 828 Table 3: Attribute Operators 830 +----------+-------------+------------------------------------------+ 831 | Operator | Description | Behavior | 832 +----------+-------------+------------------------------------------+ 833 | and | Logical And | The filter is only a match if both | 834 | | | expressions evaluate to true. | 835 | or | Logical or | The filter is a match if either | 836 | | | expression evaluates to true. | 837 | not | Not | The filter is a match if the expression | 838 | | function | evaluates to false. | 839 +----------+-------------+------------------------------------------+ 841 Table 4: Logical Operators 843 +----------+-------------+------------------------------------------+ 844 | Operator | Description | Behavior | 845 +----------+-------------+------------------------------------------+ 846 | ( ) | Precedence | Boolean expressions MAY be grouped using | 847 | | grouping | parentheses to change the standard order | 848 | | | of operations; i.e., evaluate "or" | 849 | | | logical operators before logical "and" | 850 | | | operators. | 851 | [ ] | Complex | Service providers MAY support complex | 852 | | attribute | filters where expressions MUST be | 853 | | filter | applied to the same value of a parent | 854 | | grouping | attribute specified immediately before | 855 | | | the left square bracket ("["). The | 856 | | | expression within square brackets ("[" | 857 | | | and "]") MUST be a valid filter | 858 | | | expression based upon sub-attributes of | 859 | | | the parent attribute. Nested expressions | 860 | | | MAY be used. See examples below. | 861 +----------+-------------+------------------------------------------+ 863 Table 5: Grouping Operators 865 SCIM filters MUST conform to the following ABNF [RFC5234] rules as 866 specified below: 868 FILTER = attrExp / logExp / valuePath / *1"not" "(" FILTER ")" 870 valuePath = attrPath "[" valFilter "]" 871 ; FILTER uses sub-attribs of a parent attrPath 873 valFilter = attrExp / logExp / *1"not" "(" valFilter ")" 875 attrExp = (attrPath SP "pr") / 876 (attrPath SP compareOp SP compValue) 878 logExp = FILTER SP ("and" / "or") SP FILTER 880 compValue = false / null / true / number / string 881 ; rules from JSON (RFC7159) 883 compareOp = "eq" / "ne" / "co" / 884 "sw" / "ew" / 885 "gt" / "lt" / 886 "ge" / "le" 888 attrPath = [URI ":"] ATTRNAME *1subAttr 889 ; SCIM attribute name 890 ; URI is SCIM "schema" URI 892 ATTRNAME = ALPHA *(nameChar) 894 nameChar = "-" / "_" / DIGIT / ALPHA 896 subAttr = "." ATTRNAME 897 ; a sub-attribute of a complex attribute 899 Figure 1: ABNF Specification of SCIM Filters 901 In the above ABNF rules, the "compValue" (comparison value) rule is 902 built on JSON Data Interchange format ABNF rules as specified in 903 [RFC7159], "DIGIT" and "ALPHA" are defined per Appendix B.1 of 904 [RFC5234] and, "URI" is defined per Appendix A of [RFC3986]. 906 Filters MUST be evaluated using the following order of operations in 907 order of precedence: 909 1. Grouping Operators 911 2. Logical Operators. Where "not" takes precedence over "and", 912 which takes precedence over "or". 914 3. Attribute Operators 916 If the specified attribute in a filter expression is a multi-valued 917 attribute, the filter matches if any of the values of the specified 918 attribute match the specified criterion; e.g., if a User has multiple 919 emails values, only one has to match for the entire User to match. 920 For complex attributes, a fully qualified Sub-Attribute MUST be 921 specified using standard attribute notation (Section 3.10). For 922 example, to filter by userName the parameter value is "userName". To 923 filter by first name, the parameter value is "name.givenName". 925 When applying a comparison (e.g., "eq") or presence filter (e.g., 926 "pr"), to a defaulted attribute the service provider SHALL use the 927 value that was returned to the client that last created or modified 928 the attribute. 930 Providers MAY support additional filter operations if they choose. 931 Providers MUST decline to filter results if the specified filter 932 operation is not recognized and return a HTTP 400 error with a scim 933 error type of "invalidFilter" and an appropriate human readable 934 response as per Section 3.12. For example, if a client specified an 935 unsupported operator named 'regex' the service provider should 936 specify an error response description identifying the client error; 937 e.g., 'The operator 'regex' is not supported.' 939 When comparing attributes of type String, the case sensitivity for 940 String type attributes SHALL be determined by the attribute's 941 "caseExact" characteristic (see Section 2.2 942 [I-D.ietf-scim-core-schema]). 944 Clients MAY query by schema or schema extensions by using a filter 945 expression including the "schemas" attribute (as shown in the 946 following figure). 948 The following are examples of valid filters. Some attributes (e.g., 949 rooms and rooms.number) are hypothetical extensions and are not part 950 of SCIM core schema: 952 filter=userName eq "bjensen" 954 filter=name.familyName co "O'Malley" 956 filter=userName sw "J" 958 filter=urn:ietf:params:scim:schemas:core:2.0:User:userName sw "J" 960 filter=title pr 962 filter=meta.lastModified gt "2011-05-13T04:42:34Z" 964 filter=meta.lastModified ge "2011-05-13T04:42:34Z" 966 filter=meta.lastModified lt "2011-05-13T04:42:34Z" 968 filter=meta.lastModified le "2011-05-13T04:42:34Z" 970 filter=title pr and userType eq "Employee" 972 filter=title pr or userType eq "Intern" 974 filter= 975 schemas eq "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" 977 filter=userType eq "Employee" and (emails co "example.com" or emails 978 co "example.org") 980 filter=userType ne "Employee" and not (emails co "example.com" or 981 emails co "example.org") 983 filter=userType eq "Employee" and (emails.type eq "work") 985 filter=userType eq "Employee" and emails[type eq "work" and 986 value co "@example.com"] 988 filter=emails[type eq "work" and value co "@example.com"] or 989 ims[type eq "xmpp" and value co "@foo.com"] 991 Figure 2: Example Filters 993 3.4.2.3. Sorting 995 Sort is OPTIONAL. Clients MAY discover sort capability by looking at 996 the "sort" attribute of the service provider configuration (see 997 Section 4). Sorting allows clients to specify the order in which 998 resources are returned by specifying a combination of sortBy and 999 sortOrder URL parameters. 1001 sortBy The sortBy parameter specifies the attribute whose value 1002 SHALL be used to order the returned responses. If the sortBy 1003 attribute corresponds to a singular attribute, resources are 1004 sorted according to that attribute's value; if it's a multi-valued 1005 attribute, resources are sorted by the value of the primary 1006 attribute (see Section 2.4 [I-D.ietf-scim-core-schema]), if any, 1007 or else the first value in the list, if any. If the attribute is 1008 complex the attribute name must be a path to a sub-attribute in 1009 standard attribute notation (Section 3.10) ; e.g., 1010 "sortBy=name.givenName". For all attribute types, if there is no 1011 data for the specified "sortBy" value they are sorted via the 1012 "sortOrder" parameter; i.e., they are ordered last if ascending 1013 and first if descending. 1015 sortOrder The order in which the sortBy parameter is applied. 1016 Allowed values are "ascending" and "descending". If a value for 1017 sortBy is provided and no sortOrder is specified, the sortOrder 1018 SHALL default to ascending. String type attributes are case 1019 insensitive by default unless the attribute type is defined as a 1020 case exact string. "sortOrder" MUST sort according to the 1021 attribute type; i.e., for case insensitive attributes, sort the 1022 result using case insensitive, unicode alphabetic sort order, with 1023 no specific locale implied and for case exact attribute types, 1024 sort the result using case sensitive, Unicode alphabetic sort 1025 order. 1027 3.4.2.4. Pagination 1029 Pagination parameters can be used together to "page through" large 1030 numbers of resources so as not to overwhelm the client or service 1031 provider. Because pagination is not stateful, clients MUST be 1032 prepared to handle inconsistent results. For example, a request for 1033 a list of 10 resources beginning with a startIndex of 1 MAY return 1034 different results when repeated as a resource in the original result 1035 could be deleted or new ones could be added in-between requests. 1036 Pagination parameters and general behavior are derived from the 1037 OpenSearch Protocol [OpenSearch]. 1039 The following table describes the URL pagination parameters. 1041 +------------+----------------------------+-------------------------+ 1042 | Parameter | Description | Default | 1043 +------------+----------------------------+-------------------------+ 1044 | startIndex | The 1-based index of the | 1 | 1045 | | first query result. A | | 1046 | | value less than 1 SHALL be | | 1047 | | interpreted as 1. | | 1048 | count | Non-negative Integer. | None. When specified | 1049 | | Specifies the desired | the service provider | 1050 | | maximum number of query | MUST NOT return more | 1051 | | results per page; e.g., | results than specified | 1052 | | 10. A negative value SHALL | though MAY return fewer | 1053 | | be interpreted as "0". A | results. If | 1054 | | value of "0" indicates no | unspecified, the | 1055 | | resource results are to be | maximum number of | 1056 | | returned except for | results is set by the | 1057 | | "totalResults". | service provider. | 1058 +------------+----------------------------+-------------------------+ 1060 Table 6: Pagination Request parameters 1062 The following table describes the query response pagination 1063 attributes specified by the service provider. 1065 +--------------+----------------------------------------------------+ 1066 | Element | Description | 1067 +--------------+----------------------------------------------------+ 1068 | itemsPerPage | Non-negative Integer. Specifies the number of | 1069 | | query results returned in a query response page; | 1070 | | e.g., 10. | 1071 | totalResults | Non-negative Integer. Specifies the total number | 1072 | | of results matching the client query; e.g., 1000. | 1073 | startIndex | The 1-based index of the first result in the | 1074 | | current set of query results; e.g., 1. | 1075 +--------------+----------------------------------------------------+ 1077 Table 7: Pagination Response Elements 1079 For example, to retrieve the first 10 Users, set the startIndex to 1 1080 and the count to 10: 1082 GET /Users?startIndex=1&count=10 1083 Host: example.com 1084 Accept: application/scim+json 1085 Authorization: Bearer h480djs93hd8 1086 The response to the query above returns metadata regarding paging 1087 similar to the following example (actual resources removed for 1088 brevity): 1090 { 1091 "totalResults":100, 1092 "itemsPerPage":10, 1093 "startIndex":1, 1094 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 1095 "Resources":[{ 1096 ... 1097 }] 1098 } 1100 Figure 3: ListResponse format for returning multiple resources 1102 Given the example above, to continue paging set the startIndex to 11 1103 and re-fetch; i.e., /Users?startIndex=11&count=10 1105 3.4.2.5. Attributes 1107 The following attributes control which attributes SHALL be returned 1108 with a returned resource. SCIM clients MAY use up to one of these 1109 two OPTIONAL parameters which MUST be supported by SCIM service 1110 providers: 1112 attributes A multi-valued list of strings indicating the names of 1113 resource attributes to return in the response overriding the set 1114 of attributes that would be returned by default. Attribute names 1115 MUST be in standard.attribute notation (Section 3.10) form. See 1116 additional retrieval query parameters (Section 3.9). 1118 excludedAttributes A multi-valued list of strings indicating the 1119 names of resource attributes to be removed from the default set of 1120 attributes to return. This parameter SHALL have no effect on 1121 attributes whose schema "returned" setting is "always" see Server 1122 Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in 1123 standard attribute notation (Section 3.10) form. See additional 1124 retrieval query parameters (Section 3.9). 1126 3.4.3. Querying Resources Using HTTP POST 1128 Clients MAY execute queries without passing parameters on the URL by 1129 using the HTTP POST verb combined with the "/.search" path extension. 1130 The inclusion of "/.search" on the end of a valid SCIM endpoint SHALL 1131 be used to indicate the HTTP POST verb is intended to be a query 1132 operation. 1134 To create a new query result set, a SCIM client sends an HTTP POST 1135 request to the desired SCIM resource endpoint (ending in "/.search"). 1136 The body of the POST request MAY include any of the parameters as 1137 defined in Section 3.4.2. 1139 Query requests MUST be identified using the following URI: 1140 "urn:ietf:params:scim:api:messages:2.0:SearchRequest". The following 1141 attributes are defined for query requests: 1143 attributes A multi-valued list of strings indicating the names of 1144 resource attributes to return in the response overriding the set 1145 of attributes that would be returned by default. Attribute names 1146 MUST be in standard attribute notation (Section 3.10) form. See 1147 additional retrieval query parameters (Section 3.9). OPTIONAL. 1149 excludedAttributes A multi-valued list of strings indicating the 1150 names of resource attributes to be removed from the default set of 1151 attributes to return. This parameter SHALL have no effect on 1152 attributes whose schema "returned" setting is "always" see Server 1153 Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in 1154 standard attribute notation (Section 3.10) form. See additional 1155 retrieval query parameters (Section 3.9). OPTIONAL. 1157 filter The filter string used to request a subset of resources. The 1158 filter string MUST be a valid filter (Section 3.4.2.2) expression. 1159 OPTIONAL. 1161 sortBy A string indicating the attribute whose value SHALL be used 1162 to order the returned responses. The sortBy attribute MUST be in 1163 standard attribute notation (Section 3.10) form. See sorting 1164 (Section 3.4.2.3). OPTIONAL. 1166 sortOrder A string indicating the order in which the sortBy 1167 parameter is applied. Allowed values are "ascending" and 1168 "descending". See sorting (Section 3.4.2.3). OPTIONAL. 1170 startIndex An integer indicating the 1-based index of the first 1171 query result. See pagination (Section 3.4.2.4). OPTIONAL. 1173 count An integer indicating the desired maximum number of query 1174 results per page. See pagination (Section 3.4.2.4). OPTIONAL. 1176 After receiving a HTTP POST request, a response is returned as 1177 specified in Section 3.4.2. 1179 The following example shows an HTTP POST Query request with search 1180 parameters attributes, filter, and count included: 1182 POST /.search 1183 Host: example.com 1184 Accept: application/scim+json 1185 Content-Type: application/scim+json 1186 Authorization: Bearer h480djs93hd8 1187 Content-Length: ... 1189 { 1190 "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"], 1191 "attributes": ["displayName", "userName"], 1192 "filter": 1193 "displayName sw \"smith\"", 1194 "startIndex": 1, 1195 "count": 10 1196 } 1198 Figure 4: Example POST Query Request 1200 A query response is shown with the first page of results. For 1201 brevity reasons, only two matches are shown: one User and one Group. 1203 HTTP/1.1 200 OK 1204 Content-Type: application/scim+json 1205 Location: https://example.com/.search 1206 { 1207 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 1208 "totalResults":100, 1209 "itemsPerPage":10, 1210 "startIndex":1, 1211 "Resources":[ 1212 { 1213 "id":"2819c223-7f76-413861904646", 1214 "userName":"jsmith", 1215 "displayName":"Smith, James" 1216 }, 1217 { 1218 "id":"c8596b90-7539-4f20968d1908", 1219 "displayName":"Smith Family" 1220 }, 1221 ... 1222 ] 1223 } 1225 Figure 5: Example POST Query Response 1227 3.5. Modifying Resources 1229 Resources can be modified in whole or in part using HTTP "PUT" or 1230 "PATCH", respectively. Implementers MUST support "PUT" as specified 1231 in Section 4.3 [RFC7231]. Resources such as Groups may be very large 1232 hence implementers SHOULD support HTTP PATCH [RFC5789] to enable 1233 partial resource modifications. Service provider support for HTTP 1234 "PATCH" may be discovered by querying the service provider 1235 configuration (see Section 4). 1237 3.5.1. Replacing with PUT 1239 HTTP PUT is used to replace a resource's attributes. For example, 1240 clients that have previously retrieved the entire resource in advance 1241 and revised it, MAY replace the resource using an HTTP PUT. Because 1242 SCIM resource identifiers are assigned by the service provider, HTTP 1243 PUT MUST NOT be used to create new resources. 1245 As the operation intent is to replace all attributes, SCIM clients 1246 MAY send all attributes regardless of each attribute's mutability. 1247 The server will apply attribute by attribute replace according to the 1248 following attribute mutability rules: 1250 readWrite, writeOnly Any values provided SHALL replace the existing 1251 attribute values. 1253 Attributes whose mutability is "readWrite", that are omitted from 1254 the request body, MAY be assumed to be not asserted by the client. 1255 The service provider MAY assume any existing values are to be 1256 cleared or the service provider MAY assign a default value to the 1257 final resource representation. Service providers MAY take into 1258 account whether a client has access to, or understands, all of the 1259 resource's attributes when deciding whether non-asserted 1260 attributes SHALL be removed or defaulted. Clients that want to 1261 override a server's defaults MAY specify "null" for a single- 1262 valued attribute, or an empty array "[]" for a multi-valued 1263 attribute to clear all values. 1265 immutable If value(s) are already set for the attribute, the input 1266 value(s) MUST match or HTTP status 400 SHOULD be returned with 1267 "scimType" error code "mutability". If the service provider has 1268 no existing values, the new value(s) SHALL be applied. 1270 readOnly Any values provided SHALL be ignored. 1272 If an attribute is "required", clients MUST specify the attribute in 1273 the PUT request. 1275 Unless otherwise specified, a successful PUT operation returns a 200 1276 OK response code and the entire resource within the response body, 1277 enabling the client to correlate the client's and the service 1278 provider's views of the updated resource. Example: 1280 PUT /Users/2819c223-7f76-453a-919d-413861904646 1281 Host: example.com 1282 Accept: application/scim+json 1283 Content-Type: application/scim+json 1284 Authorization: Bearer h480djs93hd8 1285 If-Match: W/"a330bc54f0671c9" 1287 { 1288 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 1289 "id":"2819c223-7f76-453a-919d-413861904646", 1290 "userName":"bjensen", 1291 "externalId":"bjensen", 1292 "name":{ 1293 "formatted":"Ms. Barbara J Jensen III", 1294 "familyName":"Jensen", 1295 "givenName":"Barbara", 1296 "middleName":"Jane" 1297 }, 1298 "roles":[], 1299 "emails":[ 1300 { 1301 "value":"bjensen@example.com" 1302 }, 1303 { 1304 "value":"babs@jensen.org" 1305 } 1306 ] 1307 } 1308 The service responds with the entire, updated User: 1310 HTTP/1.1 200 OK 1311 Content-Type: application/scim+json 1312 ETag: W/"b431af54f0671a2" 1313 Location: 1314 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646" 1315 { 1316 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 1317 "id":"2819c223-7f76-453a-919d-413861904646", 1318 "userName":"bjensen", 1319 "externalId":"bjensen", 1320 "name":{ 1321 "formatted":"Ms. Barbara J Jensen III", 1322 "familyName":"Jensen", 1323 "givenName":"Barbara", 1324 "middleName":"Jane" 1325 }, 1326 "emails":[ 1327 { 1328 "value":"bjensen@example.com" 1329 }, 1330 { 1331 "value":"babs@jensen.org" 1332 } 1333 ], 1334 "meta": { 1335 "resourceType":"User", 1336 "created":"2011-08-08T04:56:22Z", 1337 "lastModified":"2011-08-08T08:00:12Z", 1338 "location": 1339 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 1340 "version":"W\/\"b431af54f0671a2\"" 1341 } 1342 } 1344 3.5.2. Modifying with PATCH 1346 HTTP PATCH is an OPTIONAL server function that enables clients to 1347 update one or more attributes of a SCIM resource using a sequence of 1348 operations to "add", "remove", or "replace" values. Clients may 1349 discover service provider support for PATCH by querying the service 1350 provider configuration (see Section 4). 1352 The general form of the SCIM patch request is based on JavaScript 1353 Object Notation (JSON) Patch [RFC6902]. One difference between SCIM 1354 patch and JSON patch is that SCIM servers do not support array 1355 indexing and do not support [RFC6902] operation types relating to 1356 array element manipulation such as "move". 1358 The body of each request MUST contain the "schemas" attribute with 1359 the URI value of: "urn:ietf:params:scim:api:messages:2.0:PatchOp". 1361 The body of an HTTP PATCH request MUST contain the attribute 1362 "Operations", whose value is an array of one or more patch 1363 operations. Each patch operation object MUST have exactly one "op" 1364 member, whose value indicates the operation to perform and MAY be one 1365 of "add", "remove", or "replace". The semantics of each operation 1366 are defined in the following sub-sections. 1368 The following is an example representation of a PATCH request showing 1369 the basic JSON structure (non-normative): 1371 { "schemas": 1372 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1373 "Operations":[ 1374 { 1375 "op":"add", 1376 "path":"members", 1377 "value":[ 1378 { 1379 "display": "Babs Jensen", 1380 "$ref": 1381 "https://example.com/v2/Users/2819c223...413861904646", 1382 "value": "2819c223-7f76-453a-919d-413861904646" 1383 } 1384 ] 1385 }, 1386 ... + additional operations if needed ... 1387 ] 1388 } 1390 Figure 6: Example JSON body for SCIM PATCH Request 1392 The "path" attribute value is a String containing an attribute path 1393 describing the target of the operation. The "path" attribute is 1394 OPTIONAL for "add" and "replace" and is REQUIRED for "remove" 1395 operations. See relevant operation sections below for details. 1397 The "path" attribute is described by the following ABNF syntax rule: 1399 PATH = attrPath / valuePath [subAttr] 1401 Figure 7: SCIM Patch PATH Rule 1403 The ABNF rules, "attrPath", "valuePath", and "subAttr" are defined in 1404 Section 3.4.2.2. The "valuePath" rule allows specific values of a 1405 complex, multi-valued attribute to be selected. 1407 Valid examples of "path" are as follows: 1409 "path":"members" 1411 "path":"name.familyName" 1413 "path":"addresses[type eq \"work\"]" 1415 "path":"members[value eq 1416 \"2819c223-7f76-453a-919d-413861904646\"]" 1418 "path":"members[value eq 1419 \"2819c223-7f76-453a-919d-413861904646\"].displayName" 1421 Figure 8: Example Path Values 1423 Each operation against an attribute MUST be compatible with the 1424 attribute's mutability and schema as defined in the Section 2.2 and 1425 2.3 of [I-D.ietf-scim-core-schema]. For example, a client MUST NOT 1426 modify an attribute that has mutability "readOnly" or "immutable". 1427 However, a client MAY "add" a value to an "immutable" attribute if 1428 the attribute had no previous value. An operation that is not 1429 compatible with an attribute's mutability or schema SHALL return the 1430 appropriate HTTP response status code and a JSON detail error 1431 response as defined in Section 3.12. 1433 The attribute notation rules described in Section 3.10 apply for 1434 describing attribute paths. For all operations, the value of the 1435 "schemas" attribute on the SCIM service provider's representation of 1436 the resource SHALL be assumed by default. If one of the PATCH 1437 operations modifies the "schemas" attribute, subsequent operations 1438 SHALL assume the modified state of the "schemas" attribute. Clients 1439 MAY implicitly modify the "schemas" attribute by adding (or 1440 replacing) an attribute with its fully qualified name including 1441 schema URN. For example, adding the attribute "urn:ietf:params:scim: 1442 schemas:extension:enterprise:2.0:User:employeeNumber", automatically 1443 adds the value 1444 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" to the 1445 resource's "schemas" attribute. 1447 Each patch operation represents a single action to be applied to the 1448 same SCIM resource specified by the request URI. Operations are 1449 applied sequentially in the order they appear in the array. Each 1450 operation in the sequence is applied to the target resource; the 1451 resulting resource becomes the target of the next operation. 1452 Evaluation continues until all operations are successfully applied or 1453 until an error condition is encountered. 1455 For multi-valued attributes, a patch operation that sets a value's 1456 "primary" sub-attribute to "true", SHALL cause the server to 1457 automatically set "primary" to "false" for any other values in the 1458 array. 1460 A patch request, regardless of the number of operations, SHALL be 1461 treated as atomic. If a single operation encounters an error 1462 condition, the original SCIM resource MUST be restored, and a failure 1463 status SHALL be returned. 1465 If a request fails, the server SHALL return an HTTP response status 1466 code and a JSON detail error response as defined in Section 3.12. 1468 On successful completion, the server MUST return either a 200 OK 1469 response code and the entire resource within the response body, 1470 subject to the "attributes" query parameter (see Additional Retrieval 1471 Query Parameters (Section 3.9)); or the server MAY return a 204 No 1472 Content response code and the appropriate response headers for a 1473 successful patch request. The server MUST return a 200 OK if the 1474 "attributes" parameter is specified on the request. 1476 3.5.2.1. Add Operation 1478 The "add" operation is used to add a new attribute value to an 1479 existing resource. 1481 The operation MUST contain a "value" member whose content specifies 1482 the value to be added. The value MAY be a quoted value or it may be 1483 a JSON object containing the sub-attributes of the complex attribute 1484 specified in the operation's "path". 1486 The result of the add operation depends upon what the target location 1487 indicated by "path" references: 1489 o If omitted, the target location is assumed to be the resource 1490 itself. The "value" parameter contains a set of attributes to be 1491 added to the resource. 1493 o If the target location does not exist, the attribute and value is 1494 added. 1496 o If the target location specifies a complex attribute, a set of 1497 sub-attributes SHALL be specified in the "value" parameter. 1499 o If the target location specifies a multi-valued attribute, a new 1500 value is added to the attribute. 1502 o if the target location specifies a single-valued attribute, the 1503 existing value is replaced. 1505 o If the target location specifies an attribute that does not exist 1506 (has no value), the attribute is added with the new value. 1508 o If the target location exists, the value is replaced. 1510 o If the target location already contains the value specified, no 1511 changes SHOULD be made to the resource and a success response 1512 SHOULD be returned. Unless other operations change the resource, 1513 this operation SHALL NOT change the modify timestamp of the 1514 resource. 1516 The following example shows how to add a member to a group. Some 1517 text removed for readability ("..."): 1519 PATCH /Groups/acbf3ae7-8463-...-9b4da3f908ce 1520 Host: example.com 1521 Accept: application/scim+json 1522 Content-Type: application/scim+json 1523 Authorization: Bearer h480djs93hd8 1524 If-Match: W/"a330bc54f0671c9" 1525 { "schemas": 1526 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1527 "Operations":[ 1528 { 1529 "op":"add", 1530 "path":"members", 1531 "value":[ 1532 { 1533 "display": "Babs Jensen", 1534 "$ref": 1535 "https://example.com/v2/Users/2819c223...413861904646", 1536 "value": "2819c223-7f76-453a-919d-413861904646" 1537 } 1538 ] 1539 } 1540 ] 1541 } 1543 If the user was already a member of this group, no changes should be 1544 made to the resource and a success response should be returned. The 1545 server responds with either the entire updated Group or no response 1546 body: 1548 HTTP/1.1 204 No Content 1549 Authorization: Bearer h480djs93hd8 1550 ETag: W/"b431af54f0671a2" 1551 Location: 1552 "https://example.com/Groups/acbf3ae7-8463-...-9b4da3f908ce" 1554 The following example shows how to add one or more attributes to a 1555 User resource without using a "path" attribute. 1557 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1558 Host: example.com 1559 Accept: application/scim+json 1560 Content-Type: application/scim+json 1561 Authorization: Bearer h480djs93hd8 1562 If-Match: W/"a330bc54f0671c9" 1564 { 1565 "schemas": 1566 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1567 "Operations":[{ 1568 "op":"add", 1569 "value":{ 1570 "emails":[ 1571 { 1572 "value":"babs@jensen.org", 1573 "type":"home" 1574 } 1575 ], 1576 "nickname":"Babs" 1577 }] 1578 } 1580 In the above example, an additional value is added to the multi- 1581 valued attribute "emails". The second attribute, "nickname" is added 1582 to the User resource. If the resource already had an existing 1583 "nickname", the value is replaced per the processing rules above for 1584 single-valued attributes. 1586 3.5.2.2. Remove Operation 1588 The "remove" operation removes the value at the target location 1589 specified by the required attribute "path". The operation performs 1590 the following functions depending on the target location specified by 1591 "path" : 1593 o If "path" is unspecified, the operation fails with HTTP status 1594 "400" and "scimType" of "noTarget". 1596 o If the target location is a single-value attribute, the attribute 1597 and its associated value is removed and the attribute SHALL be 1598 considered unassigned. 1600 o If the target location is a multi-valued attribute and no filter 1601 is specified, the attribute and all values are removed and the 1602 attribute SHALL be considered unassigned. 1604 o If the target location is a multi-valued attribute and a complex 1605 filter is specified comparing a "value", the values matched by the 1606 filter are removed. If after removal of the selected values, no 1607 other values remain, the multi-valued attribute SHALL be 1608 considered unassigned. 1610 o If the target location is a complex-multi-valued attribute and a 1611 complex filter is specified based on the attribute's sub- 1612 attributes, the matching records are removed. Sub-attributes 1613 whose values have been removed SHALL be considered unassigned. If 1614 the complex-multi-valued attribute has no remaining records, the 1615 attribute SHALL be considered unassigned. 1617 If an attribute is removed or becomes unassigned and is defined as a 1618 required attribute or a read-only attribute, the server SHALL return 1619 an HTTP response status code and a JSON detail error response as 1620 defined in Section 3.12 with a "scimType" error of "mutability". 1622 The following example shows how to remove a member from a group. As 1623 with the previous example, the "display" sub-attribute is optional. 1624 If the user was not a member of this group, no changes should be made 1625 to the resource and a success response should be returned. 1627 Note that server responses have been omitted for the rest of the 1628 PATCH examples. 1630 Remove a single member from a group. Some text removed for 1631 readability ("..."): 1633 PATCH /Groups/acbf3ae7-8463-...-9b4da3f908ce 1634 Host: example.com 1635 Accept: application/scim+json 1636 Content-Type: application/scim+json 1637 Authorization: Bearer h480djs93hd8 1638 If-Match: W/"a330bc54f0671c9" 1640 { 1641 "schemas": 1642 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1643 "Operations":[{ 1644 "op":"remove", 1645 "path":"members[value eq \"2819c223-7f76-...413861904646\"]" 1646 }] 1647 } 1649 Remove all members of a group: 1651 PATCH /Groups/acbf3ae7-8463-...-9b4da3f908ce 1652 Host: example.com 1653 Accept: application/scim+json 1654 Content-Type: application/scim+json 1655 Authorization: Bearer h480djs93hd8 1656 If-Match: W/"a330bc54f0671c9" 1658 { "schemas": 1659 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1660 "Operations":[{ 1661 "op":"remove","path":"members" 1662 }] 1663 } 1665 Removal of a value from a complex-multi-valued attribute (request 1666 headers removed for brevity): 1668 { 1669 "schemas": 1670 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1671 "Operations": [{ 1672 "op":"remove", 1673 "path":"emails[type eq \"work\" and value ew \"example.com\"]" 1674 }] 1675 } 1676 Example request to remove and add a member. Some text removed for 1677 readability ("..."): 1679 PATCH /Groups/acbf3ae7-8463-...-9b4da3f908ce 1680 Host: example.com 1681 Accept: application/scim+json 1682 Content-Type: application/scim+json 1683 Authorization: Bearer h480djs93hd8 1684 If-Match: W/"a330bc54f0671c9" 1685 { "schemas": 1686 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1687 "Operations": [ 1688 { 1689 "op":"remove", 1690 "path": 1691 "members[value eq\"2819c223...919d-413861904646\"]" 1692 }, 1693 { 1694 "op":"add", 1695 "path":"members", 1696 "value": [ 1697 { 1698 "display": "James Smith", 1699 "$ref": 1700 "https://example.com/v2/Users/08e1d05d...473d93df9210", 1701 "value": "08e1d05d...473d93df9210" 1702 } 1703 ] 1704 } 1705 ] 1706 } 1707 The following example shows how to replace all the members of a group 1708 with a different members list. Some text removed for readabilty 1709 ("..."): 1711 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1712 Host: example.com 1713 Accept: application/scim+json 1714 Content-Type: application/scim+json 1715 Authorization: Bearer h480djs93hd8 1716 If-Match: W/"a330bc54f0671c9" 1717 { 1718 "schemas": 1719 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1720 "Operations": [ 1721 { 1722 "op":"remove","path":"members" 1723 }, 1724 { 1725 "op":"add", 1726 "path":"members", 1727 "value":[ 1728 { 1729 "display": "Babs Jensen", 1730 "$ref": 1731 "https://example.com/v2/Users/2819c223...413861904646", 1732 "value": "2819c223-7f76-453a-919d-413861904646" 1733 }, 1734 { 1735 "display": "James Smith", 1736 "$ref": 1737 "https://example.com/v2/Users/08e1d05d...473d93df9210", 1738 "value": "08e1d05d-121c-4561-8b96-473d93df9210" 1739 }] 1740 } 1741 ] 1742 } 1744 3.5.2.3. Replace Operation 1746 The "replace" operation replaces the value at the target location 1747 specified by the "path". The operation performs the following 1748 functions depending on the target location specified by "path" : 1750 o If the "path" parameter is omitted, the target is assumed to be 1751 the resource itself. In this case, the "value" attribute SHALL 1752 contain a list of one or more attributes that are to be replaced. 1754 o If the target location is a single-value attribute, the attributes 1755 value is replaced. 1757 o If the target location is a multi-valued attribute and no filter 1758 is specified, the attribute and all values are replaced. 1760 o If the target location path specifies an attribute that does not 1761 exist, the service provider SHALL treat the operation as an "add". 1763 o If the target location specifies a complex attribute, a set of 1764 sub-attributes SHALL be specified in the "value" parameter which 1765 replaces any existing values or adds where an attribute did not 1766 previously exist. Sub-attributes that are not specified in the 1767 "value" parameter are left unchanged. 1769 o If the target location is a multi-valued attribute and a value 1770 selection ("valuePath") filter is specified that matches one or 1771 more values of the multi-valued attribute, then all matching 1772 record values SHALL be replaced. 1774 o If the target location is a complex-multi-valued attribute with a 1775 value selection filter ("valuePath") and a specific sub-attribute 1776 (e.g., "addresses[type eq "work"].streetAddress" ), the matching 1777 sub-attribute of all matching records is replaced. 1779 o If the target location is a multi-valued attribute for which a 1780 value selection filter ("valuePath") has been supplied and no 1781 record match was made, the service provider SHALL fail by 1782 returning HTTP status "400", and a "scimType" of "noTarget". 1784 The following example shows how to replace all the members of a group 1785 with a different members list in a single replace operation. Some 1786 text removed for readability ("..."): 1788 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce 1789 Host: example.com 1790 Accept: application/scim+json 1791 Content-Type: application/scim+json 1792 Authorization: Bearer h480djs93hd8 1793 If-Match: W/"a330bc54f0671c9" 1795 { 1796 "schemas": 1797 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1798 "Operations": [{ 1799 "op":"replace", 1800 "path":"members", 1801 "value":[ 1802 { 1803 "display": "Babs Jensen", 1804 "$ref": 1805 "https://example.com/v2/Users/2819c223...413861904646", 1806 "value": "2819c223...413861904646" 1807 }, 1808 { 1809 "display": "James Smith", 1810 "$ref": 1811 "https://example.com/v2/Users/08e1d05d...473d93df9210", 1812 "value": "08e1d05d...473d93df9210" 1813 } 1814 ] 1815 }] 1816 } 1817 The following example shows how to change a User's entire "work" 1818 address using a "valuePath" filter. Note that by setting "primary" 1819 to "true", the service provider will reset primary to "false" for any 1820 other existing values of "addresses". 1822 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1823 Host: example.com 1824 Accept: application/scim+json 1825 Content-Type: application/scim+json 1826 Authorization: Bearer h480djs93hd8 1827 If-Match: W/"a330bc54f0671c9" 1829 { 1830 "schemas": 1831 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1832 "Operations": [{ 1833 "op":"replace", 1834 "path":"addresses[type eq \"work\"]", 1835 "value": 1836 { 1837 "type": "work", 1838 "streetAddress": "911 Universal City Plaza", 1839 "locality": "Hollywood", 1840 "region": "CA", 1841 "postalCode": "91608", 1842 "country": "US", 1843 "formatted": 1844 "911 Universal City Plaza\nHollywood, CA 91608 US", 1845 "primary": true 1846 } 1847 }] 1848 } 1849 The following example shows how to change a specific sub-attribute 1850 "streetAddress" of complex attribute "emails" selected by "valuePath" 1851 filter: 1853 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1854 Host: example.com 1855 Accept: application/scim+json 1856 Content-Type: application/scim+json 1857 Authorization: Bearer h480djs93hd8 1858 If-Match: W/"a330bc54f0671c9" 1860 { 1861 "schemas": 1862 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1863 "Operations": [{ 1864 "op":"replace", 1865 "path":"addresses[type eq \"work\"].streetAddress", 1866 "value":"1010 Broadway Ave" 1867 }] 1868 } 1869 The following example shows how to replace all values of one or more 1870 specific attributes of a User resource. Note that other attributes 1871 are unaffected. 1873 PATCH /Users/2819c223-7f76-453a-919d-413861904646 1874 Host: example.com 1875 Accept: application/scim+json 1876 Content-Type: application/scim+json 1877 Authorization: Bearer h480djs93hd8 1878 If-Match: W/"a330bc54f0671c9" 1880 { 1881 "schemas": 1882 ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 1883 "Operations": [{ 1884 "op":"replace", 1885 "value":"{ 1886 "emails":[ 1887 { 1888 "value":"bjensen@example.com", 1889 "type":"work", 1890 "primary":true 1891 }, 1892 { 1893 "value":"babs@jensen.org", 1894 "type":"home" 1895 } 1896 ], 1897 "nickname":"Babs" 1898 }] 1899 } 1901 3.6. Deleting Resources 1903 Clients request resource removal via DELETE. Service providers MAY 1904 choose not to permanently delete the resource, but MUST return a 404 1905 error code for all operations associated with the previously deleted 1906 resource. Service providers MUST omit the resource from future query 1907 results. In addition the service provider SHOULD NOT consider the 1908 deleted resource in conflict calculation. For example if a User 1909 resource is deleted, a CREATE request for a User resource with the 1910 same userName as the previously deleted resource SHOULD NOT fail with 1911 a 409 error due to userName conflict. 1913 DELETE /Users/2819c223-7f76-453a-919d-413861904646 1914 Host: example.com 1915 Authorization: Bearer h480djs93hd8 1916 If-Match: W/"c310cd84f0281b7" 1918 In response to a successful delete, the server SHALL respond with 1919 successful HTTP status 204 (No Content). A non-normative example 1920 response: 1922 HTTP/1.1 204 No Content 1924 Example: Client attempt to retrieve the previously deleted User 1926 GET /Users/2819c223-7f76-453a-919d-413861904646 1927 Host: example.com 1928 Authorization: Bearer h480djs93hd8 1930 Server Response: 1932 HTTP/1.1 404 NOT FOUND 1934 { 1935 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 1936 "Errors":[ 1937 { 1938 "description": 1939 "Resource 2819c223-7f76-453a-919d-413861904646 not found", 1940 "code":"404" 1941 } 1942 ] 1943 } 1945 3.7. Bulk Operations 1947 The SCIM bulk operation is an optional server feature that enables 1948 clients to send a potentially large collection of resource operations 1949 in a single request. Support for bulk requests can be discovered by 1950 querying the service provider configuration (see Section 4). The 1951 body of a a bulk operation contains a set of HTTP resource operations 1952 using one of the API supported HTTP methods; i.e., POST, PUT, PATCH 1953 or DELETE. 1955 Bulk requests are identified using the following schemas URI: 1956 "urn:ietf:params:scim:api:messages:2.0:BulkRequest". Bulk responses 1957 are identified using the following URI: 1958 "urn:ietf:params:scim:api:messages:2.0:BulkResponse". Bulk requests 1959 and bulk responses share many attributes. Unless otherwise 1960 specified, each attribute below is present in both bulk requests and 1961 bulk responses. 1963 The following singular attribute is defined in addition to the common 1964 attributes defined in SCIM core schema. 1966 failOnErrors 1967 An Integer specifying the number of errors that the service 1968 provider will accept before the operation is terminated and an 1969 error response is returned. OPTIONAL in a request. Not valid in 1970 a response. 1972 The following complex multi-valued attribute is defined in addition 1973 to the common attributes defined in core schema. 1975 Operations 1976 Defines operations within a bulk job. Each operation corresponds 1977 to a single HTTP request against a resource endpoint. REQUIRED. 1978 Operations has the following sub-attributes: 1980 method The HTTP method of the current operation. Possible values 1981 are "POST", "PUT", "PATCH" or "DELETE". REQUIRED. 1983 bulkId The transient identifier of a newly created resource, 1984 unique within a bulk request and created by the client. The 1985 bulkId serves as a surrogate resource id enabling clients to 1986 uniquely identify newly created resources in the Response and 1987 cross reference new resources in and across operations within a 1988 bulk request. REQUIRED when method is POST. 1990 version The current resource version. Version MAY be used if the 1991 service provider supports ETags and the method is PUT, PATCH, 1992 or DELETE. 1994 path The resource's relative path to the SCIM service provider's 1995 root. If the method is POST the value must specify a resource 1996 type endpoint; e.g., /Users or /Groups whereas all other method 1997 values must specify the path to a specific resource; e.g., 1998 /Users/2819c223-7f76-453a-919d-413861904646. REQUIRED in a 1999 request. 2001 data The resource data as it would appear for a single POST, PUT 2002 or PATCH resource operation. REQUIRED in a request when method 2003 is POST, PUT and PATCH. 2005 location The resource endpoint URL. REQUIRED in a response, 2006 except in the event of a POST failure. 2008 response The HTTP response body to the specified request 2009 operation. When indicating a response with an HTTP status 2010 other than a 200 series response, the response body MUST be 2011 included. For normal completion, the server MAY elect to omit 2012 the response body. 2014 status The HTTP response status code to the requested operation. 2015 When indicating an error, the "response" attribute MUST contain 2016 the detailed error response as per Section 3.12. 2018 If a bulk job is processed successfully the HTTP response code 200 OK 2019 MUST be returned, otherwise an appropriate HTTP error code MUST be 2020 returned. 2022 The service provider MUST continue performing as many changes as 2023 possible and disregard partial failures. The client MAY override 2024 this behavior by specifying a value for the "failOnErrors" attribute. 2025 The failOnErrors attribute defines the number of errors that the 2026 service provider should accept before failing the remaining 2027 operations returning the response. 2029 To be able to reference a newly created resource the attribute bulkId 2030 MAY be specified when creating new resources. The "bulkId" is 2031 defined by the client as a surrogate identifier in a POST operation 2032 (see Section 3.7.2). The service provider MUST return the same 2033 "bulkId" together with the newly created resource. The "bulkId" can 2034 then be used by the client to map the service provider id with the 2035 "bulkId" of the created resource. 2037 A SCIM service provider MAY elect to optimize a sequence operations 2038 received (e.g., to improve processing performance). When doing so, 2039 the service provider MUST ensure the client's intent is preserved and 2040 the same stateful result is achieved as for non-optimized processing. 2041 For example, before a "User" can be added to a "Group", they must 2042 first be created. Processing these requests out of order, might 2043 result in a failure to add the new "User" to the "Group". 2045 3.7.1. Circular Reference Processing 2047 The service provider MUST try to resolve circular cross references 2048 between resources in a single bulk job but MAY stop after a failed 2049 attempt and instead return the status code 409 Conflict. The 2050 following example exhibits the potential conflict. 2052 POST /v2/Bulk 2053 Host: example.com 2054 Accept: application/scim+json 2055 Content-Type: application/scim+json 2056 Authorization: Bearer h480djs93hd8 2057 Content-Length: ... 2059 { 2060 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 2061 "Operations": [ 2062 { 2063 "method": "POST", 2064 "path": "/Groups", 2065 "bulkId": "qwerty", 2066 "data": { 2067 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 2068 "displayName": "Group A", 2069 "members": [ 2070 { 2071 "type": "Group", 2072 "value": "bulkId:ytrewq" 2073 } 2074 ] 2075 } 2076 }, 2077 { 2078 "method": "POST", 2079 "path": "/Groups", 2080 "bulkId": "ytrewq", 2081 "data": { 2082 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 2083 "displayName": "Group B", 2084 "members": [ 2085 { 2086 "type": "Group", 2087 "value": "bulkId:qwerty" 2088 } 2089 ] 2090 } 2091 } 2092 ] 2093 } 2095 If the service provider resolved the above circular references the 2096 following is returned from a subsequent GET request. 2098 GET /v2/Groups?filter=displayName sw 'Group' 2099 Host: example.com 2100 Accept: application/scim+json 2101 Authorization: Bearer h480djs93hd8 2103 HTTP/1.1 200 OK 2104 Content-Type: application/scim+json 2106 { 2107 "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 2108 "totalResults": 2, 2109 "Resources": [ 2110 { 2111 "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 2112 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 2113 "displayName": "Group A", 2114 "meta": { 2115 "resourceType": "Group", 2116 "created": "2011-08-01T18:29:49.793Z", 2117 "lastModified": "2011-08-01T18:29:51.135Z", 2118 "location": 2119 "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 2120 "version": "W\/\"mvwNGaxB5SDq074p\"" 2121 }, 2122 "members": [ 2123 { 2124 "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 2125 "$ref": 2126 "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 2127 "type": "Group" 2128 } 2129 ] 2130 }, 2131 { 2132 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3", 2133 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 2134 "displayName": "Group B", 2135 "meta": { 2136 "resourceType": "Group", 2137 "created": "2011-08-01T18:29:50.873Z", 2138 "lastModified": "2011-08-01T18:29:50.873Z", 2139 "location": 2140 "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3", 2141 "version": "W\/\"wGB85s2QJMjiNnuI\"" 2142 }, 2143 "members": [ 2144 { 2145 "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 2146 "$ref": 2147 "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", 2148 "type": "Group" 2149 } 2150 ] 2151 } 2152 ] 2153 } 2155 3.7.2. BulkdId Temporary Identifiers 2157 A SCIM client can, within one bulk operation, create a new "User", a 2158 new "Group" and add the newly created "User" to the newly created 2159 "Group". In order to add the new "User" to the "Group" the client 2160 must use the surrogate id attribute, "bulkId", to reference the User. 2161 The "bulkId" attribute value must be pre-pended with the literal 2162 "bulkId:"; e.g., if the bulkId is 'qwerty', the value is 2163 "bulkId:qwerty". The service provider MUST replace the string 2164 "bulkId:qwerty" with the permanent resource id once created. 2166 To create multiple distinct requests, each with their own "bulkId", 2167 the SCIM client specifies different "bulkId" values for each separate 2168 request. 2170 The following example creates a User with the "userName" 'Alice' and 2171 a "Group" with the "displayName" 'Tour Guides' with Alice as a 2172 member. Notice that each operation has its own "bulkId" value. 2173 However, the second operation (whose "bulkId" is "ytrewq") refers to 2174 the "bulkId" of "qwerty" in order to add Alice to new 'Tour Guides' 2175 group. 2177 POST /v2/Bulk 2178 Host: example.com 2179 Accept: application/scim+json 2180 Content-Type: application/scim+json 2181 Authorization: Bearer h480djs93hd8 2182 Content-Length: ... 2184 { 2185 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 2186 "Operations": [ 2187 { 2188 "method": "POST", 2189 "path": "/Users", 2190 "bulkId": "qwerty", 2191 "data": { 2192 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 2193 "userName": "Alice" 2194 } 2195 }, 2196 { 2197 "method": "POST", 2198 "path": "/Groups", 2199 "bulkId": "ytrewq", 2200 "data": { 2201 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 2202 "displayName": "Tour Guides", 2203 "members": [ 2204 { 2205 "type": "User", 2206 "value": "bulkId:qwerty" 2207 } 2208 ] 2209 } 2210 } 2211 ] 2212 } 2213 The service provider returns the following response: 2215 HTTP/1.1 200 OK 2216 Content-Type: application/json 2218 { 2219 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2220 "Operations": [ 2221 { 2222 "location": 2223 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2224 "method": "POST", 2225 "bulkId": "qwerty", 2226 "version": "W\/\"4weymrEsh5O6cAEK\"", 2227 "status": { 2228 "code": "201" 2229 } 2230 }, 2231 { 2232 "location": 2233 "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 2234 "method": "POST", 2235 "bulkId": "ytrewq", 2236 "version": "W\/\"lha5bbazU3fNvfe5\"", 2237 "status": { 2238 "code": "201" 2239 } 2240 } 2241 ] 2242 } 2244 In the above example, the Alice User resource has an "id" of 2245 "92b725cd-9465-4e7d-8c16-01f8e146b87a" and the Tour Guides Group has 2246 an "id" of "e9e30dba-f08f-4109-8486-d5c6a331660a". 2248 A subsequent GET request for the 'Tour Guides' Group (with an "id" of 2249 "e9e30dba-f08f-4109-8486-d5c6a331660a") returns the following with 2250 Alice's "id" as the value for the member in the Group 'Tour Guides': 2252 HTTP/1.1 200 OK 2253 Content-Type: application/scim+json 2254 Location: 2255 https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a 2256 ETag: W/"lha5bbazU3fNvfe5" 2258 { 2259 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], 2260 "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", 2261 "displayName": "Tour Guides", 2262 "meta": { 2263 "resourceType": "Group", 2264 "created": "2011-08-01T18:29:49.793Z", 2265 "lastModified": "2011-08-01T20:31:02.315Z", 2266 "location": 2267 "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", 2268 "version": "W\/\"lha5bbazU3fNvfe5\"" 2269 }, 2270 "members": [ 2271 { 2272 "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a", 2273 "$ref": 2274 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2275 "type": "User" 2276 } 2277 ] 2278 } 2280 Extensions that include references to other resources MUST be handled 2281 in the same way by the service provider. The following example uses 2282 the bulkId attribute within the enterprise extension managerId 2283 attribute. 2285 POST /v2/Bulk 2286 Host: example.com 2287 Accept: application/scim+json 2288 Content-Type: application/scim+json 2289 Authorization: Bearer h480djs93hd8 2290 Content-Length: ... 2292 { 2293 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 2294 "Operations": [ 2295 { 2296 "method": "POST", 2297 "path": "/Users", 2298 "bulkId": "qwerty", 2299 "data": { 2300 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 2301 "userName": "Alice" 2302 } 2303 }, 2304 { 2305 "method": "POST", 2306 "path": "/Users", 2307 "bulkId": "ytrewq", 2308 "data": { 2309 "schemas": [ 2310 "urn:ietf:params:scim:schemas:core:2.0:User", 2311 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" 2312 ], 2313 "userName": "Bob", 2314 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { 2315 "employeeNumber": "11250", 2316 "manager": { 2317 "value": "batchId:qwerty" 2318 } 2319 } 2320 } 2321 } 2322 ] 2323 } 2325 3.7.3. Response and Error Handling 2327 The service provider response MUST include the result of all 2328 processed operations. A "location" attribute that includes the 2329 resource's endpoint MUST be returned for all operations excluding 2330 failed POSTs. The status attribute includes information about the 2331 success or failure of one operation within the bulk job. The 2332 attribute status MUST include the code attribute that holds the HTTP 2333 response code that would have been returned if a single HTTP request 2334 would have been used. If an error occurred the status MUST also 2335 include the description attribute containing a human readable 2336 explanation of the error. 2338 "status": "201" 2340 The following is an example of a status in a failed operation. 2342 "status": "400", 2343 "response":{ 2344 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2345 "scimType":"invalidSyntax" 2346 "detail": 2347 "Request is unparsable, syntactically incorrect, or violates schema.", 2348 "status":"400" 2349 } 2351 The following example shows how to add, update, and remove a user. 2352 The "failOnErrors" attribute is set to '1' indicating the service 2353 provider should return on the first error. The POST operation's 2354 bulkId value is set to 'qwerty' enabling the client to match the new 2355 User with the returned resource id '92b725cd-9465-4e7d- 2356 8c16-01f8e146b87a'. 2358 POST /v2/Bulk 2359 Host: example.com 2360 Accept: application/scim+json 2361 Content-Type: application/scim+json 2362 Authorization: Bearer h480djs93hd8 2363 Content-Length: ... 2365 { 2366 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], 2367 "failOnErrors":1, 2368 "Operations":[ 2369 { 2370 "method":"POST", 2371 "path":"/Users", 2372 "bulkId":"qwerty", 2373 "data":{ 2374 "schemas": ["urn:ietf:params:scim:api:messages:2.0:User"], 2375 "userName":"Alice" 2376 } 2377 }, 2378 { 2379 "method":"PUT", 2380 "path":"/Users/b7c14771-226c-4d05-8860-134711653041", 2381 "version":"W\/\"3694e05e9dff591\"", 2382 "data":{ 2383 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 2384 "id":"b7c14771-226c-4d05-8860-134711653041", 2385 "userName":"Bob" 2386 } 2387 }, 2388 { 2389 "method": "PATCH", 2390 "path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2391 "version": "W/\"edac3253e2c0ef2\"", 2392 "data": {[ 2393 { 2394 "op": "remove", 2395 "path": "nickName" 2396 }, 2397 { 2398 "op": "add", 2399 "path": "userName", 2400 "value": "Dave" 2401 } 2402 ]} 2403 }, 2404 { 2405 "method":"DELETE", 2406 "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2407 "version":"W\/\"0ee8add0a938e1a\"" 2408 } 2409 ] 2410 } 2412 The service provider returns the following response. 2414 HTTP/1.1 200 OK 2415 Content-Type: application/scim+json 2417 { 2418 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2419 "Operations": [ 2420 { 2421 "location": 2422 "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", 2423 "method": "POST", 2424 "bulkId": "qwerty", 2425 "version": "W\/\"oY4m4wn58tkVjJxK\"", 2426 "status": "201" 2427 }, 2428 { 2429 "location": 2430 "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 2431 "method": "PUT", 2432 "version": "W\/\"huJj29dMNgu3WXPD\"", 2433 "status": "200" 2434 }, 2435 { 2436 "location": 2437 "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2438 "method": "PATCH", 2439 "version": "W\/\"huJj29dMNgu3WXPD\"", 2440 "status": "200" 2441 }, 2442 { 2443 "location": 2444 "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2445 "method": "DELETE", 2446 "status": "204" 2447 } 2448 ] 2449 } 2451 The following response is returned if an error occurred when 2452 attempting to create the User 'Alice'. The service provider stops 2453 processing the bulk operation and immediately returns a response to 2454 the client. The response contains the error and any successful 2455 results prior to the error. 2457 HTTP/1.1 200 OK 2458 Content-Type: application/scim+json 2460 { 2461 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2462 "Operations": [ 2463 { 2464 "method": "POST", 2465 "bulkId": "qwerty", 2466 "status": "400", 2467 "response":{ 2468 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2469 "scimType":"invalidSyntax" 2470 "detail": 2471 "Request is unparsable, syntactically incorrect, or violates schema.", 2472 "status":"400" 2473 } 2474 } 2475 ] 2476 } 2478 If the "failOnErrors" attribute is not specified or the service 2479 provider has not reached the error limit defined by the client the 2480 service provider will continue to process all operations. The 2481 following is an example in which all operations failed. 2483 HTTP/1.1 200 OK 2484 Content-Type: application/scim+json 2486 { 2487 "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], 2488 "Operations": [ 2489 { 2490 "method": "POST", 2491 "bulkId": "qwerty", 2492 "status": "400", 2493 "response":{ 2494 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2495 "scimType":"invalidSyntax" 2496 "detail": 2497 "Request is unparsable, syntactically incorrect, or violates schema.", 2498 "status":"400" 2499 } 2500 }, 2501 { 2502 "location": 2503 "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", 2504 "method": "PUT", 2505 "status": "412", 2506 "response":{ 2507 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2508 "detail":"Failed to update. Resource changed on the server.", 2509 "status":"412" 2510 } 2511 }, 2512 { 2513 "location": 2514 "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", 2515 "method": "PATCH", 2516 "status": "412", 2517 "response":{ 2518 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2519 "detail":"Failed to update. Resource changed on the server.", 2520 "status":"412" 2521 } 2522 }, 2523 { 2524 "location": 2525 "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", 2526 "method": "DELETE", 2527 "status": "404", 2528 "response":{ 2529 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2530 "detail":"Resource does not exist.", 2531 "status":"404" 2532 } 2533 } 2534 ] 2535 } 2537 3.7.4. Maximum Operations 2539 The service provider MUST define the maximum number of operations and 2540 maximum payload size a client may send in a single request. These 2541 limits MAY be retrieved from the service provider Configuration (see 2542 'bulk' in Section 5 and 8.5 of [I-D.ietf-scim-core-schema]). If 2543 either limits are exceeded the service provider MUST return the HTTP 2544 response code 413 Request Entity Too Large. The returned response 2545 MUST specify the limit exceeded in the body of the error response. 2547 The following example the client sent a request exceeding the service 2548 provider's max payload size of 1 megabyte: 2550 POST /v2/Bulk 2551 Host: example.com 2552 Accept: application/scim+json 2553 Content-Type: application/scim+json 2554 Authorization: Bearer h480djs93hd8 2555 Content-Length: 4294967296 2557 ... 2559 In response to the over-sized request, the server responds with the 2560 following error: 2562 HTTP/1.1 413 Request Entity Too Large 2563 Content-Type: application/scim+json 2565 { 2566 "schemas":["urn:ietf:params:scim:api:messages:2.0:Error"], 2567 "status": "413", 2568 "detail": 2569 "The size of the bulk operation exceeds the maxPayloadSize (1048576)." 2570 } 2572 3.8. Data Input/Output Formats 2574 Servers MUST accept requests and be able to respond with JSON 2575 structured responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be 2576 the default encoding format. Other media types MAY be supported by 2577 service providers but are beyond the scope of this specification. 2579 Clients using other encodings MUST specify the format in which the 2580 data is submitted via HTTP header "Content-Type" as specified in 2581 Section 3.1.1.5 [RFC7231] and MAY specify the desired response data 2582 format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g., 2583 "Accept: application/scim+json" or via URI suffix; e.g., 2585 GET /Users/2819c223-7f76-453a-919d-413861904646.scim 2586 Host: example.com 2588 Service providers MUST support the accept header "Accept: 2589 application/scim+json" and SHOULD support header "Accept: 2590 application/json" both of which specify JSON documents conforming to 2591 [RFC7159]. The format defaults to "application/scim+json" if no 2592 format is specified. 2594 Singular attributes are encoded as string name-value-pairs in JSON; 2595 e.g., 2597 "attribute": "value" 2599 Multi-valued attributes in JSON are encoded as arrays; e.g., 2601 "attributes": [ "value1", "value2" ] 2603 Elements with nested elements are represented as objects in JSON; 2604 e.g, 2606 "attribute": { "subattribute1": "value1", "subattribute2": "value2" } 2608 3.9. Additional Operation Response Parameters 2610 For any SCIM operation where a resource representation is returned 2611 (e.g., HTTP GET), the attributes returned are defined as the minimum 2612 attribute set plus default attributes set. The minimum set are those 2613 attributes that have their "returned" characteristic set to "always" 2614 (see Section 2.2 of [I-D.ietf-scim-core-schema]). The default 2615 attribute set are those attributes that have the "returned" 2616 characteristic set to "default". 2618 Clients MAY request a partial resource representation on any 2619 operation that returns a resource within the response by specifying 2620 either of the mutually exclusive URL query parameters "attributes" or 2621 "excludedAttributes" as follows: 2623 attributes When specified the default list of attributes SHALL be 2624 overridden and each resource returned MUST contain the 2625 minimum set of resource attributes and any attributes or sub- 2626 attributes explicitly requested by the "attributes" 2627 parameter. The query parameter attributes value is a comma 2628 separated list of resource attribute names in standard 2629 attribute notation (Section 3.10) form (e.g., userName, name, 2630 emails). 2632 excludedAttributes When specified, each resource returned MUST 2633 contain the minimal set of resource attributes. 2634 Additionally, the default set of attributes minus those 2635 attributes listed in "excludedAttributes" are also returned. 2636 The query parameter attributes value is a comma separated 2637 list of resource attribute names in standard attribute 2638 notation (Section 3.10) form (e.g., userName, name, emails). 2640 . 2642 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName 2643 Host: example.com 2644 Accept: application/scim+json 2645 Authorization: Bearer h480djs93hd8 2647 Giving the response 2649 HTTP/1.1 200 OK 2650 Content-Type: application/scim+json 2651 Location: 2652 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2653 ETag: W/"a330bc54f0671c9" 2655 { 2656 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2657 "id":"2819c223-7f76-453a-919d-413861904646", 2658 "userName":"bjensen" 2659 } 2661 3.10. Attribute Notation 2663 All operations share a common scheme for referencing simple and 2664 complex attributes. In general, attributes are uniquely identified 2665 by prefixing the attribute name with its schema URN separated by a 2666 colon (":") character; e.g., the core User resource attribute 2667 'userName' is identified as 2668 "urn:ietf:params:scim:schemas:core:2.0:User:userName". Clients MAY 2669 omit core schema attribute URN prefixes but SHOULD fully qualify 2670 extended attributes with the associated schema extension URN to avoid 2671 naming conflicts. For example, the attribute 'age' defined in 2672 "urn:ietf:params:scim:schemas:exampleCo:2.0:hr" is uniquely 2673 identified as "urn:ietf:params:scim:schemas:exampleCo:2.0:hr:age". 2674 Complex attributes' sub-attributes are referenced via nested, dot 2675 ('.') notation; i.e., {urn}:{Attribute name}.{Sub-Attribute name}. 2676 For example, the fully qualified path for a User's givenName is 2677 "urn:ietf:params:scim:schemas:core:2.0:User:name.givenName" All 2678 facets (URN, attribute and Sub-Attribute name) of the fully encoded 2679 Attribute name are case insensitive. 2681 3.11. "/Me" Authenticated Subject Alias 2683 A client MAY use a URL of the form "/Me" as a URI alias for 2684 the User or other resource associated with the currently 2685 authenticated subject for any SCIM operation. A service provider MAY 2686 respond in one of 3 ways: 2688 o A service provider that does NOT support this feature SHOULD 2689 respond with status 501 (NOT IMPLEMENTED). 2691 o A service provider MAY choose to redirect the client using HTTP 2692 status 308 to the resource associated with the authenticated 2693 subject. The client MAY then repeat the request at the indicated 2694 location. 2696 o A service provider MAY process the SCIM request directly. In any 2697 response, the HTTP "Location" header MUST be the permanent 2698 location of the aliased resource associated with the authenticated 2699 subject. 2701 When using the SCIM Create Resource command (HTTP POST) with the 2702 "/Me" alias, the desired resourceType being created is at the 2703 discretion of the service provider based on the authenticated subject 2704 (if not anonymous) making the request and any request body attributes 2705 (e.g., "schemas"). See Section 7.6 for information on security 2706 considerations related to this operation. 2708 3.12. HTTP Status and Error Response Handling 2710 The SCIM Protocol uses the HTTP status response status codes defined 2711 in Section 6 [RFC7231] to indicate operation success or failure. In 2712 addition to returning a HTTP response code implementers MUST return 2713 the errors in the body of the response in the client requested format 2714 containing the error response and, per the HTTP specification, human- 2715 readable explanations. Error responses are identified using the 2716 following "schema" URI: 2717 "urn:ietf:params:scim:api:messages:2.0:Error". The following 2718 attributes are defined for a SCIM error response using a JSON body: 2720 status 2721 The HTTP status code (see Section 6 [RFC7231]) expressed as a JSON 2722 String. REQUIRED 2724 scimType 2725 A SCIM detailed error keyword. See Table 9. OPTIONAL 2727 detail 2728 A detailed, human readable message. OPTIONAL 2730 Implementers SHOULD handle the identified HTTP status codes as 2731 described below. 2733 +--------------+---------------+------------------------------------+ 2734 | Status | Applicability | Suggested Explanation | 2735 +--------------+---------------+------------------------------------+ 2736 | 307 | GET, POST, | The client is directed to repeat | 2737 | TEMPORARY | PUT, PATCH, | the same HTTP request at the | 2738 | REDIRECT | DELETE | location identified. The client | 2739 | | | SHOULD NOT use the location | 2740 | | | provided in the response as a | 2741 | | | permanent reference to the | 2742 | | | resource and SHOULD continue to | 2743 | | | use the original request URI | 2744 | | | [RFC7231]. | 2745 | 308 | GET, POST, | The client is directed to repeat | 2746 | PERMANENT | PUT, PATCH, | the same HTTP request at the | 2747 | REDIRECT | DELETE | location identified. The client | 2748 | | | SHOULD use the location provided | 2749 | | | in the response as the permanent | 2750 | | | reference to the resource | 2751 | | | [RFC7538]. | 2752 | 400 BAD | GET, POST, | Request is unparsable, | 2753 | REQUEST | PUT, PATCH, | syntactically incorrect, or | 2754 | | DELETE | violates schema | 2755 | 401 | GET, POST, | Authorization failure. The | 2756 | UNAUTHORIZED | PUT, PATCH, | authorization header is invalid or | 2757 | | DELETE | missing. | 2758 | 403 | GET, POST, | Operation is not permitted based | 2759 | FORBIDDEN | PUT, PATCH, | on the supplied authorization. | 2760 | | DELETE | | 2761 | 404 NOT | GET, POST, | Specified resource (e.g., User) or | 2762 | FOUND | PUT, PATCH, | end-point, does not exist | 2763 | | DELETE | | 2764 | 409 CONFLICT | POST, PUT, | The specified version number does | 2765 | | PATCH, DELETE | not match the resource's latest | 2766 | | | version number or a service | 2767 | | | provider refused to create a new, | 2768 | | | duplicate resource | 2769 | 412 | PUT, PATCH,D | Failed to update as resource {id} | 2770 | PRECONDITION | ELETE | changed on the server last | 2771 | FAILED | | retrieved | 2772 | 413 REQUEST | POST | {"maxOperations": | 2773 | ENTITY TOO | | 1000,"maxPayload": 1048576} | 2774 | LARGE | | | 2775 | 500 INTERNAL | GET, POST, | An internal error. Implementers | 2776 | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive | 2777 | | DELETE | debugging advice | 2778 | 501 NOT | GET, POST, | Service Provider does not support | 2779 | IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH | 2780 | | DELETE | | 2781 +--------------+---------------+------------------------------------+ 2783 Table 8: SCIM HTTP Status Code Usage 2785 For HTTP Status 400 (Bad Request) responses, the following detail 2786 error types are defined: 2788 +--------------+------------------------------+---------------------+ 2789 | scimType | Description | Applicability | 2790 +--------------+------------------------------+---------------------+ 2791 | invalidFilte | The specified filter syntax | GET(Section 3.4.2), | 2792 | r | was invalid (does not comply | POST (Search - | 2793 | | with Figure 1) or the | Section 3.4.3), | 2794 | | specified attribute and | PATCH (Path Filter | 2795 | | filter comparison | - Section 3.5.2) | 2796 | | combination is not | | 2797 | | supported. | | 2798 | tooMany | The specified filter yields | GET(Section 3.4.2), | 2799 | | many more results than the | POST (Search - | 2800 | | server is willing calculate | Section 3.4.3) | 2801 | | or process. For example, a | | 2802 | | filter such as "(userName | | 2803 | | pr)" by itself would return | | 2804 | | all entries with a | | 2805 | | "userName" and MAY not be | | 2806 | | acceptable to the service | | 2807 | | provider. | | 2808 | uniqueness | One or more of attribute | POST (Create - | 2809 | | values is already in use or | Section 3.3), PUT | 2810 | | is reserved. | (Section 3.5.1), | 2811 | | | PATCH (Section | 2812 | | | 3.5.2) | 2813 | mutability | The attempted modification | PUT (Section | 2814 | | is not compatible with the | 3.5.1), PATCH | 2815 | | target attributes mutability | (Section 3.5.2) | 2816 | | or current state (e.g., | | 2817 | | modification of an immutable | | 2818 | | attribute with an existing | | 2819 | | value). | | 2820 | invalidSynta | The request body message | POST (Search - | 2821 | x | structure was invalid or did | Section 3.4.2, | 2822 | | not conform to the request | Create - Section | 2823 | | schema. | 3.3, Bulk - Section | 2824 | | | 3.7), PUT (Section | 2825 | | | 3.5.1) | 2826 | invalidPath | The path attribute was | PATCH (Section | 2827 | | invalid or malformed (see | 3.5.2) | 2828 | | Figure 7). | | 2829 | noTarget | The specified "path" did not | PATCH (Section | 2830 | | yield an attribute or | 3.5.2) | 2831 | | attribute value that could | | 2832 | | be operated on. This occurs | | 2833 | | when the specified "path" | | 2834 | | value contains a filter that | | 2835 | | yields no match. | | 2836 | invalidValue | A required value was | GET (Section | 2837 | | missing, or the value | 3.4.2), POST | 2838 | | specified was not compatible | (Create - Section | 2839 | | with the operation or | 3.3, Query - | 2840 | | attribute type (see Section | Section 3.4.2), PUT | 2841 | | 2.2 [I-D.ietf-scim-core-sche | (Section 3.5.1), | 2842 | | ma]), or resource schema | PATCH (Section | 2843 | | (see Section 4 [I-D.ietf-sci | 3.5.2) | 2844 | | m-core-schema]). | | 2845 | invalidVers | The specified SCIM protocol | GET (Section | 2846 | | version is not supported | 3.4.2), POST (ALL), | 2847 | | (see Section 3.13). | PUT (Section | 2848 | | | 3.5.1), PATCH | 2849 | | | (Section 3.5.2), | 2850 | | | DELETE (Section | 2851 | | | 3.6) | 2852 | sensitive | The specified request cannot | GET (Section | 2853 | | be completed due to passing | 3.4.2). | 2854 | | of sensitive (e.g., | | 2855 | | personal) information in a | | 2856 | | request URI. For example, | | 2857 | | personal information SHALL | | 2858 | | NOT be transmitted over | | 2859 | | request URIs. See Section | | 2860 | | 7.5.2. | | 2861 +--------------+------------------------------+---------------------+ 2863 Table 9: Table of SCIM Detail Error Keyword Values 2865 Note that in the table above (Table 9), the applicability table 2866 applies to the normal HTTP method but MAY apply within a SCIM Bulk 2867 operation (via HTTP POST). 2869 Error example in response to a non-existent GET request. 2871 HTTP/1.1 404 NOT FOUND 2873 { 2874 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2875 "detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found", 2876 "status": "404" 2877 } 2879 Error example in response to a PUT request. 2881 HTTP/1.1 400 BAD REQUEST 2883 { 2884 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 2885 "scimType":"mutability" 2886 "detail":"Attribute 'id' is readOnly", 2887 "status": "400" 2888 } 2890 3.13. SCIM Protocol Versioning 2892 The Base URL MAY be appended with a version identifier as a separate 2893 segment in the URL path. At this time of this specification, the 2894 identifier is 'v2'. If specified, the version identifier MUST appear 2895 in the URL path immediately preceding the resource endpoint and 2896 conform to the following scheme: the character 'v' followed by the 2897 desired SCIM version number; e.g., a version 'v2' User request is 2898 specified as /v2/Users. When specified service providers MUST 2899 perform the operation using the desired version or reject the 2900 request. When omitted service providers SHOULD perform the operation 2901 using the most recent SCIM protocol version supported by the service 2902 provider. 2904 3.14. Versioning Resources 2906 The SCIM protocol supports resource versioning via standard HTTP 2907 ETags Section 2.3 [RFC7232]. Service providers MAY support weak 2908 ETags as the preferred mechanism for performing conditional 2909 retrievals and ensuring clients do not inadvertently overwrite each 2910 others changes, respectively. When supported, SCIM ETags MUST be 2911 specified as an HTTP header and SHOULD be specified within the 2912 'version' attribute contained in the resource's 'meta' attribute. 2914 Example create request: 2916 POST /Users HTTP/1.1 2917 Host: example.com 2918 Content-Type: application/scim+json 2919 Authorization: Bearer h480djs93hd8 2920 Content-Length: ... 2922 { 2923 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2924 "userName":"bjensen", 2925 "externalId":"bjensen", 2926 "name":{ 2927 "formatted":"Ms. Barbara J Jensen III", 2928 "familyName":"Jensen", 2929 "givenName":"Barbara" 2930 } 2931 } 2933 The server responds with an ETag in the response header and meta 2934 structure. 2936 HTTP/1.1 201 Created 2937 Content-Type: application/scim+json 2938 Location: 2939 https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 2940 ETag: W/"e180ee84f0671b1" 2942 { 2943 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 2944 "id":"2819c223-7f76-453a-919d-413861904646", 2945 "meta":{ 2946 "resourceType":"User", 2947 "created":"2011-08-01T21:32:44.882Z", 2948 "lastModified":"2011-08-01T21:32:44.882Z", 2949 "location": 2950 "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", 2951 "version":"W\/\"e180ee84f0671b1\"" 2952 }, 2953 "name":{ 2954 "formatted":"Ms. Barbara J Jensen III", 2955 "familyName":"Jensen", 2956 "givenName":"Barbara" 2957 }, 2958 "userName":"bjensen" 2959 } 2960 With the returned ETag, clients MAY choose to retrieve the resource 2961 only if the resource has been modified. 2963 Conditional retrieval example using If-None-Match Section 3.2 2964 [RFC7233] header: 2966 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName 2967 Host: example.com 2968 Accept: application/scim+json 2969 Authorization: Bearer h480djs93hd8 2970 If-None-Match: W/"e180ee84f0671b1" 2972 If the resource has not changed the service provider simply returns 2973 an empty body with a 304 "Not Modified" response code. 2975 If the service providers supports versioning of resources the client 2976 MAY supply an If-Match Section 3.2 [RFC7233] header for PUT and PATCH 2977 operations to ensure that the requested operation succeeds only if 2978 the supplied ETag matches the latest service provider resource; e.g., 2979 If-Match: W/"e180ee84f0671b1" 2981 4. Service Provider Configuration Endpoints 2983 SCIM 2 defines 3 endpoints to facilitate discovery of SCIM service 2984 provider features and schema that MAY be retrieved using HTTP GET: 2986 /ServiceProviderConfig 2987 An HTTP GET to this endpoint will return a JSON structure that 2988 describes the SCIM specification features available on a service 2989 provider. This endpoint SHALL return responses with a JSON object 2990 using a "schemas" attribute of 2991 "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig". 2992 The attributes returned in the JSON object are defined in 2993 Section 5 [I-D.ietf-scim-core-schema]. An example representation 2994 of SCIM service provider configuration may be found in Section 8.5 2995 [I-D.ietf-scim-core-schema]. 2997 /Schemas 2998 An HTTP GET to this endpoint is used to retrieve information about 2999 resource schemas supported by a SCIM service provider. An HTTP 3000 GET to the endpoint "/Schemas" SHALL return all supported schemas 3001 in ListResponse format (see Figure 3). Individual schema 3002 definitions can be returned by appending the schema URI to the 3003 schemas endpoint. For example: 3005 /Schemas/urn:ietf:params:scim:schemas:core:2.0:User 3007 The contents of each schema returned is described in Section 7 3008 [I-D.ietf-scim-core-schema]. An example representation of SCIM 3009 schemas may be found in Section 8.7 [I-D.ietf-scim-core-schema]. 3011 /ResourceTypes 3012 An HTTP GET to this endpoint is used to discover the types of 3013 resources available on a SCIM service provider (e.g., Users and 3014 Groups). Each resource type defines the endpoints, the core 3015 schema URI that defines the resource, and any supported schema 3016 extensions. The attributes defining a resource type can be found 3017 in Section 6 [I-D.ietf-scim-core-schema], and an example 3018 representation can be found in Section 8.6 3019 [I-D.ietf-scim-core-schema]. 3021 In cases where a request is for a specific "ResourceType" or 3022 "Schema", the single JSON object is returned in the same way a single 3023 User or Group is retrieved as per Section 3.4.1. When returning 3024 multiple ResourceTypes or Schemas, the message form described by 3025 "urn:ietf:params:scim:api:messages:2.0:ListResponse" (ListResponse) 3026 form SHALL be used as shown in Figure 3 and Figure 9 below. Query 3027 parameters described in section 3.2 such as, sorting, attributes, and 3028 paging SHALL be ignored. If a "filter" is provided, the service 3029 provider SHOULD respond with HTTP Status 403 (FORBIDDEN) to ensure 3030 clients cannot incorrectly assume any matching conditions specified 3031 in a filter are true. 3033 The following is a non-normative example of an HTTP GET to the 3034 /ResourceTypes endpoint: 3036 { 3037 "totalResults":2, 3038 "itemsPerPage":10, 3039 "startIndex":1, 3040 "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], 3041 "Resources":[{ 3042 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"], 3043 "id":"User", 3044 "name":"User", 3045 "endpoint": "/Users", 3046 "description": "User Account", 3047 "schema": "urn:ietf:params:scim:schemas:core:2.0:User", 3048 "schemaExtensions": [{ 3049 "schema": 3050 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", 3051 "required": true 3052 }], 3053 "meta": { 3054 "location":"https://example.com/v2/ResourceTypes/User", 3055 "resourceType": "ResourceType" 3056 } 3057 }, 3058 { 3059 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"], 3060 "id":"Group", 3061 "name":"Group", 3062 "endpoint": "/Groups", 3063 "description": "Group", 3064 "schema": "urn:ietf:params:scim:schemas:core:2.0:Group", 3065 "meta": { 3066 "location":"https://example.com/v2/ResourceTypes/Group", 3067 "resourceType": "ResourceType" 3068 } 3069 }] 3070 } 3072 Figure 9: Example Resource Type JSON Representation 3074 5. Preparation and Comparison of Internationalized Strings 3076 To increase the likelihood that the input and comparison of usernames 3077 and passwords will work in ways that make sense for typical users 3078 throughout the world, there are rules for preparing, enforcing, and 3079 comparing internationalized strings that represent usernames and 3080 passwords. Before comparing or evaluating uniqueness of a "userName" 3081 or "password" attribute, service providers MUST use the "PRECIS" 3082 profile described in Sections 4 and 5 respectively of 3083 [I-D.ietf-precis-saslprepbis] which is based on the "PRECIS" 3084 framework specification [I-D.ietf-precis-framework]. 3086 6. Multi-Tenancy 3088 A single service provider may expose the SCIM protocol to multiple 3089 clients. Depending on the nature of the service, the clients may 3090 have authority to access and alter resources initially created by 3091 other clients. Alternatively, clients may expect to access disjoint 3092 sets of resources, and may expect that their resources are 3093 inaccessible by other clients. These scenarios are called "multi- 3094 tenancy", where each client is understood to be or represent a 3095 "tenant" of the service provider. Clients may also be multi- 3096 tenanted. 3098 The following common cases may occur: 3100 1. All clients share all resources (no tenancy) 3102 2. Each single client creates and accesses a private subset of 3103 resources (1 client:1 Tenant) 3105 3. Sets of clients share sets of resources (M clients:1 Tenant) 3107 4. One client to Multiple Tenants (1 client:M Tenants) 3109 Service providers may implement any subset of the above cases. 3111 Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a 3112 scheme for multi-tenancy. 3114 The SCIM protocol does not prescribe the mechanisms whereby clients 3115 and service providers interact for: 3117 o Registering or provisioning Tenants 3119 o Associating a subset of clients with a subset of the Tenants 3121 o Indicating which tenant is associated with the data in a request 3122 or response, or indicating which Tenant is the subject of a query 3124 6.1. Associating Clients to Tenants 3126 The service provider MAY use the authentication mechanism (Section 2) 3127 to determine the identity of the client, and thus infer the 3128 associated Tenant. 3130 For implementations where a client is associated with more than one 3131 Tenant, the service provider MAY use one of the following methods for 3132 explicit specification of the Tenant. 3134 If any of these methods of allowing the client to explicitly specify 3135 the Tenant are employed, the service provider should ensure that 3136 access controls are in place to prevent or allow cross-tenant use 3137 cases. 3139 The service provider should consider precedence in cases where a 3140 client may explicitly specify a Tenant while being implicitly 3141 associated with a different Tenant. 3143 In all of these methods, the {tenant_id} is a unique identifier for 3144 the Tenant as defined by the service provider. 3146 o A URL prefix: "https://www.example.com/Tenants/{tenant_id}/v2/ 3147 Users" 3149 o A sub-domain: "https://{tenant_id}.example.com/v2/Groups" 3151 o The service provider may recognize a {tenant_id} provided by the 3152 client in an HTTP Header as the indicator of the desired target 3153 Tenant. 3155 6.2. SCIM Identifiers with Multiple Tenants 3157 Considerations for a Multi-Tenant Implementation: 3159 The service provider may choose to implement SCIM ids which are 3160 unique across all resources for all Tenants, but this is not 3161 required. 3163 The externalId, defined by the client, is required to be unique ONLY 3164 within the resources associated with the associated Tenant. 3166 7. Security Considerations 3168 7.1. HTTP Considerations 3170 SCIM Protocol layers on top of Hypertext Transfer Protocol and thus 3171 subject to the security considerations of HTTP Section 9 [RFC7230] 3172 and its related specifications. 3174 As stated in Section 2.7.1 [RFC7230], a SCIM client MUST NOT generate 3175 the "userinfo" (i.e., username and password) component (and its "@" 3176 delimiter) when an "http" URI reference is generated with a message 3177 as they are now disallowed in HTTP. 3179 7.2. TLS Support Considerations 3181 SCIM resources (e.g., Users and Groups) contain sensitive information 3182 including passwords. Therefore, SCIM clients and service providers 3183 MUST require the use of a transport-layer security mechanism when 3184 communicating with SCIM service providers. The SCIM service provider 3185 MUST support TLS 1.2 [RFC5246] and MAY support additional transport- 3186 layer mechanisms meeting its security requirements. When using TLS, 3187 the client MUST perform a TLS/SSL server certificate check, per 3188 [RFC6125]. Implementation security considerations for TLS can be 3189 found in "Recommendations for Secure Use of TLS and DTLS" [RFC7525]. 3191 7.3. Authorization Token Considerations 3193 When using authorization tokens such as those issued by OAuth 2.0 3194 [RFC6749], implementers MUST take into account threats and 3195 countermeasures documented in Section 8 of 3196 [I-D.ietf-oauth-assertions]. 3198 7.4. Bearer and Cookie Considerations 3200 Since the possession of a bearer token or cookie MAY authorize the 3201 holder to potentially read, modify, or delete resources, tokens and 3202 cookies MUST contain sufficient entropy to prevent a random guessing 3203 attack, such as described in Section 5.2 of [RFC6750] and 3204 Section 5.1.4.2.2 of [RFC6819]. 3206 As with all SCIM communications, Bearer tokens and HTTP cookies MUST 3207 be exchanged using TLS. 3209 Bearer tokens MUST have a limited lifetime that can be determined 3210 directly or indirectly (e.g., by checking with a validation service) 3211 by the service provider. By expiring tokens, clients are forced to 3212 obtain a new token (which usually involves re-authentication) for 3213 continued authorized access. For example, in OAuth2, a client MAY 3214 use OAuth token refresh to obtain a new bearer token after 3215 authenticating to an authorization server. See Section 6 of 3216 [RFC6749]. 3218 As with Bearer tokens, an HTTP cookie SHOULD last no longer than the 3219 lifetime of a browser session. An expiry time should be set that 3220 limits session cookie lifetime as per Section 5.2.1 of [RFC6265]. 3222 Implementations supporting OAuth bearer tokens need to factor in 3223 security considerations of this authorization method 3224 [I-D.ietf-oauth-assertions]. Since security is only as good as the 3225 weakest link, implementers also need to consider authentication 3226 choices coupled with OAuth bearer tokens. The security 3227 considerations of the default authentication method for OAuth bearer 3228 tokens, HTTP BASIC, are well documented in 3229 [I-D.ietf-httpauth-basicauth-update], therefore implementers are 3230 encouraged to prefer stronger authentication methods. Designating 3231 the specific methods of authentication and authorization are out-of- 3232 scope for SCIM, however this information is provided as a resource to 3233 implementers. 3235 7.5. Privacy Considerations 3237 7.5.1. Personal Information 3239 The SCIM Core Schema specifications defines attributes that may 3240 contain personally identifying information as well as other sensitive 3241 personal data. The privacy considerations in the Security 3242 Considerations Section of [I-D.ietf-scim-core-schema] MUST be 3243 considered. 3245 7.5.2. Disclosure of Sensitive Information in URIs 3247 As mentioned in Section 9.4 [RFC7231], SCIM clients requesting 3248 information using query filters using HTTP GET SHOULD give 3249 consideration to the information content of the filters and whether 3250 their exposure in a URI would represent a breach of security or 3251 confidentiality through leakage in a web browsers or server logs. 3252 This is particularly true for information that is legally considered 3253 "personally identifiable information" or is otherwise restricted by 3254 privacy laws. In these situations to ensure maximum security and 3255 confidentiality, clients SHOULD query using HTTP POST (see 3256 Section 3.4.3 ). 3258 Servers that receive HTTP GET requests using filters that contain 3259 sensitive or confidential personal information SHOULD respond with 3260 HTTP status 403 indicating the operation is FORBIDDEN. A "scimType" 3261 error of "sensitive" may be returned indicating the request must be 3262 submitted using POST. A non-normative example: 3264 HTTP/1.1 403 FORBIDDEN 3266 { 3267 "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], 3268 "detail": 3269 "Query filter involving 'name' is restricted or confidential", 3270 "scimType": "sensitive", 3271 "status": "404" 3272 } 3274 7.6. Anonymous Requests 3276 If a SCIM service provider accepts anonymous requests such as SCIM 3277 resource creation requests (via HTTP POST), appropriate security 3278 measures should be put in place to prevent or limit exposure to 3279 attacks. The following counter-measures MAY be used: 3281 o Try to authenticate web UI components that formulate the SCIM 3282 creation request. While the end-user may be anonymous, the web 3283 user interface component often has its own way to authenticate to 3284 the SCIM service provider (e.g., has an OAuth client credential 3285 [RFC6749]) and the web user interface component may implement its 3286 own measures (e.g., such as CAPTCHA) to ensure a legitimate 3287 request is being made. 3289 o Limit the number of requests any particular client MAY make in a 3290 period of time. 3292 o For User resources, default newly created resource with an 3293 "active" setting of "false" and use a secondary confirmation 3294 process (e.g., email confirmation) to ensure the resource created 3295 is real. 3297 7.7. Secure Storage and Handling of Sensitive Data 3299 An attacker may obtain valid username/password combinations from the 3300 SCIM service provider's underlying database by gaining access to the 3301 database and/or launching injection attacks. This could lead to 3302 unintended disclosure of username/password combinations. The impact 3303 may extend beyond the domain of the SCIM service provider if the data 3304 was provisioned from other domains. 3306 Administrators should undertake industry best practices to protect 3307 the storage of credentials and in particular SHOULD follow 3308 recommendations outlines in Section 5.1.4.1 [RFC6819]. These 3309 recommendations include but are not limited to: 3311 o Provide injection attack counter measures (e.g., by validating all 3312 inputs and parameters), 3314 o No cleartext storage of credentials, 3316 o Store credentials using an encrypted protection mechanism, and 3318 o Avoid passwords and consider use of asymmetric cryptography based 3319 credentials. 3321 As outlined in Section 5.1.4.2 [RFC6819], administrators SHOULD take 3322 counter measures to prevent online attacks on secrets such as: 3324 o Utilize secure password policy in order to increase user password 3325 entropy to hinder online attacks and password guessing, 3327 o Mitigate attacks on passwords by locking respective accounts have 3328 a number of failed attempts, 3330 o Use "tar pit" techniques by temporarily locking a respective 3331 account and delaying responses for a certain duration. The 3332 duration may increase with the number of failed attempts, and 3334 o Use authentication system that use CAPTCHA's and other factors for 3335 authenticating users further reducing the possibility of automated 3336 attacks. 3338 Service providers SHOULD define an access control model that 3339 differentiates between individual client applications and their 3340 specific need to access information, and any User self-service rights 3341 to review and update personal profile information. This may include 3342 OAuth 2.0 delegation profiles, that allow client systems to act on 3343 behalf of user's with their permission. 3345 7.8. Case Insensitive Comparison & International Languages 3347 When comparing unicode strings such as in query filters or testing 3348 for uniqueness of usernames and passwords, strings MUST be 3349 appropriately prepared before comparison. See Section 5. 3351 8. IANA Considerations 3353 8.1. Media Type Registration 3355 To: ietf-types@iana.org 3357 Subject: Registration of media type application/scim+json 3359 Type name: application 3361 Subtype name: scim+json 3363 Required parameters: none 3365 Optional parameters: none 3367 Encoding considerations: 8bit 3368 Security considerations: See Section 7 3370 Interoperability considerations: The "application/scim+json" media 3371 type is intended to identify JSON structure data that conforms to 3372 the SCIM protocol and schema specifications. Older versions of 3373 SCIM are known to informally use "application/json". 3375 Published specification: [[this document]] 3377 Applications that use this media type: It is expected that 3378 applications that use this type may be special purpose 3379 applications intended for inter-domain provisioning. Clients may 3380 also be applications (e.g., mobile applications) that need to use 3381 SCIM for self-registration of user accounts. SCIM services may be 3382 offered by web applications that offer support for standards based 3383 provisioning or may be a dedicated SCIM service provider such as a 3384 "cloud directory". Content may be treated as equivalent to 3385 "application/json" type for the purpose of displaying in web 3386 browsers. 3388 Additional information: 3390 Magic number(s): 3392 File extension(s): .scim .scm 3394 Macintosh file type code(s): 3396 Person & email address to contact for further information: SCIM 3397 mailing list "" 3399 Intended usage: COMMON* (see restrictions) 3401 Restrictions on usage: For most client types, it is sufficient to 3402 recognize the content as equivalent to "application/json". 3403 Applications intending to use SCIM protocol SHOULD use the 3404 application/scim+json media type. 3406 Author: Phil Hunt 3408 Change controller: IETF 3410 8.2. SCIM Message URI Registry 3412 As per the IANA SCIM Schema Registry in [I-D.ietf-scim-core-schema], 3413 the following registers and extends the SCIM Schema Registry to 3414 define SCIM protocol request/response JSON schema URN identifier 3415 prefix of "urn:ietf:params:scim:api:messages:2.0" which is part of 3416 the URN sub-Namespace for SCIM. There is no specific associated 3417 resource type. 3419 +---------------------------------+-----------------+---------------+ 3420 | Schema URI | Name | Reference | 3421 +---------------------------------+-----------------+---------------+ 3422 | urn:ietf:params:scim:api: | List/Query | See Section | 3423 | messages:2.0:ListResponse | Response | 3.4.2 | 3424 | urn:ietf:params:scim:api: | POST Query | See Section | 3425 | messages:2.0:SearchRequest | Request | 3.4.3 | 3426 | urn:ietf:params:scim:api: | Patch Operation | See Section | 3427 | messages:2.0:PatchOp | | 3.5.2 | 3428 | urn:ietf:params:scim:api: | Bulk Operations | See Section | 3429 | messages:2.0:BulkRequest | Request | 3.7 | 3430 | urn:ietf:params:scim:api: | Bulk Operations | See Section | 3431 | messages:2.0:BulkResponse | Response | 3.7 | 3432 | urn:ietf:params:scim:api: | Error Response | See Section | 3433 | messages:2.0:Error | | 3.12 | 3434 +---------------------------------+-----------------+---------------+ 3436 Table 10: SCIM Schema URIs for Data Resources 3438 9. References 3440 9.1. Normative References 3442 [I-D.ietf-precis-saslprepbis] 3443 Saint-Andre, P. and A. Melnikov, "Preparation, 3444 Enforcement, and Comparison of Internationalized Strings 3445 Representing Usernames and Passwords", draft-ietf-precis- 3446 saslprepbis-16 (work in progress), April 2015. 3448 [I-D.ietf-scim-core-schema] 3449 Hunt, P., Grizzle, K., Wahlstroem, E., and C. Mortimore, 3450 "System for Cross-Domain Identity Management: Core 3451 Schema", draft-ietf-scim-core-schema-20 (work in 3452 progress), May 2015. 3454 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3455 Requirement Levels", BCP 14, RFC 2119, March 1997. 3457 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3458 10646", STD 63, RFC 3629, November 2003. 3460 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3461 Resource Identifier (URI): Generic Syntax", STD 66, RFC 3462 3986, January 2005. 3464 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 3465 Specifications: ABNF", STD 68, RFC 5234, January 2008. 3467 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3468 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3470 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 3471 5789, March 2010. 3473 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3474 Verification of Domain-Based Application Service Identity 3475 within Internet Public Key Infrastructure Using X.509 3476 (PKIX) Certificates in the Context of Transport Layer 3477 Security (TLS)", RFC 6125, March 2011. 3479 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 3480 6749, October 2012. 3482 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 3483 Framework: Bearer Token Usage", RFC 6750, October 2012. 3485 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 3486 Interchange Format", RFC 7159, March 2014. 3488 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3489 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 3490 2014. 3492 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3493 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 3495 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3496 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 3498 [RFC7233] Fielding, R., Lafon, Y., and J. Reschke, "Hypertext 3499 Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, 3500 June 2014. 3502 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 3503 (HTTP/1.1): Authentication", RFC 7235, June 2014. 3505 [RFC7538] Reschke, J., "The Hypertext Transfer Protocol Status Code 3506 308 (Permanent Redirect)", RFC 7538, April 2015. 3508 9.2. Informative References 3510 [I-D.ietf-httpauth-basicauth-update] 3511 Reschke, J., "The 'Basic' HTTP Authentication Scheme", 3512 draft-ietf-httpauth-basicauth-update-07 (work in 3513 progress), February 2015. 3515 [I-D.ietf-oauth-assertions] 3516 Campbell, B., Mortimore, C., Jones, M., and Y. Goland, 3517 "Assertion Framework for OAuth 2.0 Client Authentication 3518 and Authorization Grants", draft-ietf-oauth-assertions-18 3519 (work in progress), October 2014. 3521 [I-D.ietf-oauth-pop-architecture] 3522 Hunt, P., Richer, J., Mills, W., Mishra, P., and H. 3523 Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security 3524 Architecture", draft-ietf-oauth-pop-architecture-01 (work 3525 in progress), March 2015. 3527 [I-D.ietf-precis-framework] 3528 Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 3529 Preparation, Enforcement, and Comparison of 3530 Internationalized Strings in Application Protocols", 3531 draft-ietf-precis-framework-23 (work in progress), 3532 February 2015. 3534 [OpenSearch] 3535 Clinton, D., "OpenSearch Protocol 1.1, Draft 5", Dec 2005. 3537 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3538 April 2011. 3540 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 3541 Threat Model and Security Considerations", RFC 6819, 3542 January 2013. 3544 [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation 3545 (JSON) Patch", RFC 6902, April 2013. 3547 [RFC7486] Farrell, S., Hoffman, P., and M. Thomas, "HTTP Origin- 3548 Bound Authentication (HOBA)", RFC 7486, March 2015. 3550 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 3551 "Recommendations for Secure Use of Transport Layer 3552 Security (TLS) and Datagram Transport Layer Security 3553 (DTLS)", BCP 195, RFC 7525, May 2015. 3555 [XML-Schema] 3556 Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes 3557 Second Edition", October 2004. 3559 Appendix A. Contributors 3561 Samuel Erdtman (samuel@erdtman.se) 3563 Patrick Harding (pharding@pingidentity.com) 3565 Appendix B. Acknowledgments 3567 The editors would like to acknowledge the contribution and work of 3568 the past draft editors: 3570 Trey Drake, UnboundID 3572 Chuck Mortimore, Salesforce 3574 The editor would like to thank the participants in the the SCIM 3575 working group for their support of this specification. 3577 Appendix C. Change Log 3579 [[This section to be removed prior to publication as an RFC]] 3581 Draft 02 - KG - Addition of schema extensibility 3583 Draft 03 - PH - Revisions based on following tickets: 3585 24 - Add filter negation 3587 39 - Clarification on response for DELETE 3589 42 - Make root searches optional 3591 49 - Add "ew" filter 3593 50 - Filters for multi-valued complex attributes 3595 51 - Search by Schema 3597 53 - Standard use of term client (some was consumer) 3599 55 - Redirect support (3xx) 3601 56 - Make manager attribute consistent with other $ref attrs 3602 57 - Update all "/v1" examples to '/v2" 3604 59 - Fix capitalization per IETF editor practices 3606 60 - Changed tags to normal and tags 3608 Draft 04 - PH - Revisions based on the following tickets: 3610 18 - New PATCH command based on JSON Patch (RFC6902) 3612 - Provided ABNF specification for filters (used in PATCH) 3614 - Updated references to RFC4627 to RFC7159 3616 Draft 05 - PH - Revisions based on the following tickets: 3618 03 - Support for excludedAttributes parameter 3620 13 - Change client use of Etags from MUST to MAY (correction) 3622 23 - Clarifications regarding case exact processing. 3624 41 - Add IANA considerations 3626 65 - Removed X-HTTP-Method-Override support 3628 69 - Added clarifications to intro to align with draft-nottingham- 3629 uri-get-off-my-lawn 3631 70 - Remove SCIM_TENANT_ID header 3633 72 - Added text to indicate UTF-8 is default and mandatory 3634 encoding format per BCP18 3636 74 - Added security considerations for using GET with confidential 3637 attribute filters 3639 - corrected error response in JSON PATCH operation 3641 Draft 06 - PH - Revisions based on the following tickets and 3642 editorial changes 3644 41 - Revised content types from application/json to application/ 3645 scim+json, registered API schemas 3647 63 - Revised uri schema prefixes for API json message schemas 3649 66 - Updated references for RFC2616 to HTTPbis 3650 75 - Added security considerations for International Strings and 3651 "PRECIS" support 3653 76 - Clarified handling of PUT (& POST) with regards to mutability 3654 and default values 3656 - Corrected version numbers in sec 3.11 API Versioning to v2 (from 3657 v1) 3659 - Clarified that no filter matches should return success 3660 totalResults=0 3662 Draft 07 - PH - Revisions regarding support of detailed errors 3663 (Tickets 37, 46, 67) 3665 Draft 08 - PH - Revisions as follows 3667 - Added clarification on schemas handling during PATCH operation 3669 - Revised example URN in Attribute Notation section to comply with 3670 IANA namespace rules 3672 - Fixed typo in ABNF, attrExpr should be attrExp 3674 - Added more security considerations for HTTP and sensitive data 3676 - Revised authentication and authorization sections for greater 3677 clarity. 3679 - Replaced the word "search" with "query" for consistency 3681 - Clarified sucessful resource creation response 3683 - Added clarification on primary value handling in PATCH 3684 (consistent with draft 03) 3686 - Revised SCIM Bullk error handling to conform with draft 07 error 3687 handling 3689 Draft 09 - PH - Revisions as follows 3691 - Aligned API with new URN namespace per RFC3553 and IETF90 3692 meeting 3694 - Clarified URN usage within patch (what schema urn applies) 3696 - Made 'path' optional in PATCH for Add and Replace 3698 Draft 10 - PH - Revisions as follows 3700 Restructuring of Bulk into sub-sections 3702 General clarifications 3704 Improved Base URI section 3706 Authorization section clarifications 3708 Draft 11 - PH - Revisions as follows 3710 Made mutability processing rules for CREATE more editorially 3711 obvious 3713 Added clarfications and security considerations for Anonymous 3714 operations 3716 Added clarifications to "/Me" for POST requests 3718 Clarified use of bulkids with multiple requests 3720 Corrected JSON parsing issue by adding "Operations" attribute to 3721 PATCH operation 3723 Draft 12 - PH - Editorial NITs 3725 Fix line lengths in artwork to be 72 chars or less 3727 Remove unused references 3729 Fix normative terms per RFC2119 3731 Updated reference to draft-reschke-http-status-308 to RFC7238 3733 Draft 13 - PH - Added clarification to error response for improperly 3734 formated email/phonenumbers 3736 Draft 14 - PH - Nits and clarifications 3738 Added new Service Provider Discovery section that clarifies use of 3739 ResourceTypes, Schemas, and ServiceProviderConfigs 3741 As Complex attributes cannot support sub-attributes that are 3742 complex, the filter ABNF was corrected to prevent nested 3743 valueFilters (which presumes support for nested Complex 3744 Attributes) 3745 Corrections to ABNF: Added missing space (SP) values to logicExp 3746 ABNF rule. Corrected "not(" to make "not" optional. 3748 Added additional filter example showing full path with schema URI 3749 (to disambiguate duplicate names between schemas) 3751 Missing POST verb added to HTTP errors (table 7) since a POST 3752 endpoint might be undefined or NOT FOUND. 3754 Corrected JSON example in sec 3.3.2.1 (removed extraneous " ) 3756 Corrected filter in Figure 3 so that multiple resoruce types can 3757 be returned per the response example in figure 4. 3759 Clarifications and improvements to examples in PATCH replace 3760 operations 3762 Updated references to saslprep and precis frameworks 3764 Draft 15 - PH - Clarifications on returning "path" handling during 3765 PATCH "replace" operations. Updated references. 3767 Draft 16 - PH - Clarification of SCIM protocol definitions of 3768 resources vs messages and general process rules regarding schema 3769 including validation. 3771 Draft 17 - PH - Edits based on Gen-ART review 3773 Draft 18 - PH - Edits based on IESG feedback 3775 Clarified use of authentication schemes 3777 Nits and wording clarifications 3779 Corrected definitions of HTTP Status 401/403 3781 Manager corrected in PATCH example operation (consistent with 3782 schema and examples) 3784 Removed editor's note regarding Service Provider unique error 3785 codes 3787 Updated references to SCIM Core Schema and other documents. 3789 Made capitalization of 'client' and 'service provider' terms 3790 consistent (lower case) 3791 Add references to draft-ietf-oauth-assertions-18 and draft-ietf- 3792 httpauth-basicauth-update-07 3794 Draft 19 - PH - IESG review 3796 Corrections as per IESG review comments from Ben Campbell 3798 Corrections as per IESG review comments from Stephen Farrell 3800 Clarified that other media types may be supported 3802 Corrected non-normative (statements of fact) use of 'MAY' to 3803 'may'. 3805 Changed use of SHOULD use security considerations to MUST 3807 Servers that do not support /Me corrected to return 501 instead of 3808 403 3810 Removed reference to wikipedia and order of operations 3812 General edits to clarify awkward text and typos 3814 Authors' Addresses 3816 Phil Hunt (editor) 3817 Oracle Corporation 3819 Email: phil.hunt@yahoo.com 3821 Kelly Grizzle 3822 SailPoint 3824 Email: kelly.grizzle@sailpoint.com 3826 Morteza Ansari 3827 Cisco 3829 Email: morteza.ansari@cisco.com 3831 Erik Wahlstroem 3833 Email: erik.wahlstrom@nexusgroup.com 3834 Chuck Mortimore 3835 Salesforce.com 3837 Email: cmortimore@salesforce.com