idnits 2.17.1
draft-scim-api-01.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 :
----------------------------------------------------------------------------
** The document seems to lack an IANA Considerations section. (See Section
2.2 of https://www.ietf.org/id-info/checklist for how to handle the case
when there are no actions for IANA.)
** There are 32 instances of too long lines in the document, the longest
one being 28 characters in excess of 72.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD',
or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please
use uppercase 'NOT' together with RFC 2119 keywords (if that is what you
mean).
Found 'MUST not' in this paragraph:
+------------+-------------------+----------------------------------+ |
Parameter | Description | Default |
+------------+-------------------+----------------------------------+ |
startIndex | The 1-based index | 1 | |
| of the first | | |
| search result. | | | count
| Non-negative | None. When specified the | | |
Integer. | Service Provider MUST not return | | |
Specifies the | more results than specified | | |
desired maximum | though MAY return fewer results. | | |
number of search | If unspecified, the maximum | | |
results per page; | number of results is set by the | | |
e.g., 10. | Service Provider. |
+------------+-------------------+----------------------------------+
== Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD',
or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please
use uppercase 'NOT' together with RFC 2119 keywords (if that is what you
mean).
Found 'MUST not' in this paragraph:
Consumers request Resource removal via DELETE. Service Providers
MAY choose not to permanently delete the Resource, but MUST return a 404
error code for all operations associated with the previously deleted Id.
Service Providers MUST also omit the Resource from future query results.
In addition the Service Provider MUST not consider the deleted resource
in conflict calculation. For example if a User resource is deleted, a
CREATE request for a User resource with the same userName as the
previously deleted resource should not fail with a 409 error due to
userName conflict.
-- The document date (July 09, 2012) is 4302 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)
-- Missing reference section? 'RFC2119' on line 114 looks like a reference
-- Missing reference section? '1' on line 134 looks like a reference
-- Missing reference section? '2' on line 386 looks like a reference
-- Missing reference section? '3' on line 571 looks like a reference
-- Missing reference section? '4' on line 635 looks like a reference
-- Missing reference section? '5' on line 1684 looks like a reference
-- Missing reference section? '6' on line 1685 looks like a reference
-- Missing reference section? '7' on line 1774 looks like a reference
-- Missing reference section? 'RFC2616' on line 1937 looks like a reference
Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 10 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group T. Drake, Ed.
3 Internet-Draft UnboundID
4 Intended status: Standards Track C. Mortimore
5 Expires: January 10, 2013 SalesForce
6 M. Ansari
7 Cisco
8 K. Grizzle
9 SailPoint
10 E. Wahlstroem
11 Technology Nexus
12 July 09, 2012
14 System for Cross-Domain Identity Management:Protocol 1.1
15 draft-scim-api-01
17 Abstract
19 The System for Cross-Domain Identity Management (SCIM) specification
20 is designed to make managing user identity in cloud based
21 applications and services easier. The specification suite seeks to
22 build upon experience with existing schemas and deployments, placing
23 specific emphasis on simplicity of development and integration, while
24 applying existing authentication, authorization, and privacy models.
25 It's intent is to reduce the cost and complexity of user management
26 operations by providing a common user schema and extension model, as
27 well as binding documents to provide patterns for exchanging this
28 schema using standard protocols. In essence, make it fast, cheap,
29 and easy to move users in to, out of, and around the cloud.
31 Status of this Memo
33 This Internet-Draft is submitted in full conformance with the
34 provisions of BCP 78 and BCP 79.
36 Internet-Drafts are working documents of the Internet Engineering
37 Task Force (IETF). Note that other groups may also distribute
38 working documents as Internet-Drafts. The list of current Internet-
39 Drafts is at http://datatracker.ietf.org/drafts/current/.
41 Internet-Drafts are draft documents valid for a maximum of six months
42 and may be updated, replaced, or obsoleted by other documents at any
43 time. It is inappropriate to use Internet-Drafts as reference
44 material or to cite them other than as "work in progress."
46 This Internet-Draft will expire on January 10, 2013.
48 Copyright Notice
49 Copyright (c) 2012 IETF Trust and the persons identified as the
50 document authors. All rights reserved.
52 This document is subject to BCP 78 and the IETF Trust's Legal
53 Provisions Relating to IETF Documents
54 (http://trustee.ietf.org/license-info) in effect on the date of
55 publication of this document. Please review these documents
56 carefully, as they describe your rights and restrictions with respect
57 to this document. Code Components extracted from this document must
58 include Simplified BSD License text as described in Section 4.e of
59 the Trust Legal Provisions and are provided without warranty as
60 described in the Simplified BSD License.
62 Table of Contents
64 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
65 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3
66 1.2. Notational Conventions . . . . . . . . . . . . . . . . . . 3
67 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3
68 2. Authentication and Authorization . . . . . . . . . . . . . . . 3
69 3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
70 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . . 6
71 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . . 7
72 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 7
73 3.2.2. List/Query Resources . . . . . . . . . . . . . . . . . 8
74 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 15
75 3.3.1. Modifying with PUT . . . . . . . . . . . . . . . . . . 15
76 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . . 17
77 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . . 25
78 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
79 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 41
80 3.7. Additional retrieval query parameters . . . . . . . . . . 42
81 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . . 42
82 3.9. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 43
83 3.10. API Versioning . . . . . . . . . . . . . . . . . . . . . . 44
84 3.11. Versioning Resources . . . . . . . . . . . . . . . . . . . 44
85 3.12. HTTP Method Overloading . . . . . . . . . . . . . . . . . 46
86 4. Security Considerations . . . . . . . . . . . . . . . . . . . 46
87 5. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 47
88 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47
89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 47
91 1. Introduction and Overview
93 The SCIM Protocol is an application-level, REST protocol for
94 provisioning and managing identity data on the web. The protocol
95 supports creation, modification, retrieval, and discovery of core
96 identity Resources; i.e., Users and Groups, as well as custom
97 Resource extensions.
99 1.1. Intended Audience
101 This document is intended as a guide to SCIM API usage for both
102 identity Service Providers and Consumers.
104 1.2. Notational Conventions
106 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
107 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
108 document are to be interpreted as described in [RFC2119]. These
109 keywords are capitalized when used to unambiguously specify
110 requirements of the protocol or application features and behavior
111 that affect the interoperability and security of implementations.
112 When these words are not capitalized, they are meant in their
113 natural-language sense.
115 For purposes of readability examples are not URL encoded.
116 Implementers MUST percent encode URLs as described in RFC3896 2.1.
118 1.3. Definitions
120 Base URL: The SCIM REST API is always relative to a Base URL. The
121 Base URL MUST NOT contain a query string as Consumers may append
122 additional path information and query parameters as part of
123 forming the request. Example: https://example.com/scim/v1/
125 2. Authentication and Authorization
127 The SCIM protocol does not define a scheme for authentication and
128 authorization therefore implementers are free to choose mechanisms
129 appropriate to their use cases. The choice of authentication
130 mechanism will impact interoperability. It is RECOMMENDED that
131 clients be implemented in such a way that new authentication schemes
132 can be deployed. Implementers SHOULD support existing
133 authentication/authorization schemes. In particular, OAuth2 Bearer
134 Token [1] is RECOMMENDED. Appropriate security considerations of the
135 selected authentication and authorization schemes SHOULD be taken.
136 Because this protocol uses HTTP response status codes as the primary
137 means of reporting the result of a request, servers are advised to
138 respond to unauthorized or unauthenticated requests using the 401
139 response code in accordance with section 10.4.2 of RFC2616.
141 All examples assume OAuth2 bearer token; e.g.,
143 GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1
144 Host: example.com
145 Authorization: Bearer h480djs93hd8
147 The context of the request (i.e. the user for whom data is being
148 requested) MUST be inferred by Service Providers.
150 3. API
152 The SCIM protocol specifies well known endpoints and HTTP methods for
153 managing Resources defined in the core schema; i.e., User and Group
154 Resources correspond to /Users and /Groups respectively. Service
155 Providers that support extended Resources SHOULD define Resource
156 endpoints using the established convention; pluralize the Resource
157 name defined in the extended schema by appending an 's'. Given there
158 are cases where Resource pluralization is ambiguous; e.g., a Resource
159 named 'person' is legitimately 'persons' and 'people' Consumers
160 SHOULD discover Resource endpoints via the Schema Sub-Attribute
161 'endpoint'.
163 GET Retrieves a complete or partial Resource.
165 POST Create new Resource or bulk modify Resources.
167 PUT Modifies a Resource with a complete, Consumer specified Resource
168 (replace).
170 PATCH Modifies a Resource with a set of Consumer specified changes
171 (partial update).
173 DELETE Deletes a Resource.
175 +------------+--------------------+---------------+-----------------+
176 | Resource | Endpoint | Operations | Description |
177 +------------+--------------------+---------------+-----------------+
178 | User | /Users | GET | Retrieve/Add/Mo |
179 | | | (Section 3.2. | dify Users |
180 | | | 1), POST | |
181 | | | (Section 3.1 | |
182 | | | ),PUT | |
183 | | | (Section 3. | |
184 | | | 3.1), PATCH | |
185 | | | (Section 3 | |
186 | | | .3.2), DELETE | |
187 | | | (Section | |
188 | | | 3.4) | |
189 | Group | /Groups | GET | Retrieve/Add/Mo |
190 | | | (Section 3.2. | dify Groups |
191 | | | 1), POST | |
192 | | | (Section 3.1 | |
193 | | | ),PUT | |
194 | | | (Section 3. | |
195 | | | 3.1), PATCH | |
196 | | | (Section 3 | |
197 | | | .3.2), DELETE | |
198 | | | (Section | |
199 | | | 3.4) | |
200 | Service | /ServiceProviderCo | GET | Retrieve the |
201 | Provider | nfigs | (Section 3.2. | Service |
202 | Configurat | | 1) | Provider's |
203 | ion | | | Configuration |
204 | Schema | /Schemas | GET | Retrieve a |
205 | | | (Section 3.2. | Resource's |
206 | | | 1) | Schema |
207 | Bulk | /Bulk | POST | Bulk modify |
208 | | | (Section 3.5) | Resources |
209 +------------+--------------------+---------------+-----------------+
211 Table 1: Defined endpoints
213 All requests to the Service Provider are made via HTTP operations on
214 a URL derived from the Base URL. Responses are returned in the body
215 of the HTTP response, formatted as JSON or XML, depending on what is
216 requested. Response and error codes SHOULD be transmitted via the
217 HTTP status code of the response (if possible), and SHOULD also be
218 specified in the body of the response.
220 3.1. Creating Resources
222 To create new Resources, clients send POST requests to the Resource
223 endpoint; i.e., /Users or /Groups.
225 Successful Resource creation is indicated with a 201 ("Created")
226 response code. Upon successful creation, the response body MUST
227 contain the newly created Resource. Since the server is free to
228 alter and/or ignore POSTed content, returning the full representation
229 can be useful to the client, enabling it to correlate the client and
230 server views of the new Resource. When a Resource is created, its
231 URI must be returned in the response Location header.
233 If the Service Provider determines creation of the requested Resource
234 conflicts with existing resources; e.g., a User Resource with a
235 duplicate userName, the Service Provider MUST return a 409 error and
236 SHOULD indicate the conflicting attribute(s) in the body of the
237 response.
239 Below, the client sends a POST request containing a User
241 POST /Users HTTP/1.1
242 Host: example.com
243 Accept: application/json
244 Content-Type: application/json
245 Authorization: Bearer h480djs93hd8
246 Content-Length: ...
248 {
249 "schemas":["urn:scim:schemas:core:1.0"],
250 "userName":"bjensen",
251 "externalId":"bjensen",
252 "name":{
253 "formatted":"Ms. Barbara J Jensen III",
254 "familyName":"Jensen",
255 "givenName":"Barbara"
256 }
257 }
259 The server signals a successful creation with a status code of 201.
260 The response includes a Location header indicating the User URI, and
261 a representation of that User in the body of the response.
263 HTTP/1.1 201 Created
264 Content-Type: application/json
265 Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646
266 ETag: W/"e180ee84f0671b1"
268 {
269 "schemas":["urn:scim:schemas:core:1.0"],
270 "id":"2819c223-7f76-453a-919d-413861904646",
271 "externalId":"bjensen",
272 "meta":{
273 "created":"2011-08-01T21:32:44.882Z",
274 "lastModified":"2011-08-01T21:32:44.882Z",
275 "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
276 "version":"W\/\"e180ee84f0671b1\""
277 },
278 "name":{
279 "formatted":"Ms. Barbara J Jensen III",
280 "familyName":"Jensen",
281 "givenName":"Barbara"
282 },
283 "userName":"bjensen"
284 }
286 3.2. Retrieving Resources
288 Users and Group Resources are retrieved via opaque, unique URLs or
289 via Query. Service Providers MAY choose to respond with a sub-set of
290 Resource attributes, though MUST minimally return the Resource id and
291 meta attributes.
293 3.2.1. Retrieving a known Resource
295 To retrieve a known Resource, clients send GET requests to the
296 Resource endpoint; e.g., /Users/{id} or /Groups/{id}.
298 If the Resource exists the server responds with a status code of 200
299 and includes the result in the body of the response.
301 The below example retrieves a single User via the /Users endpoint.
303 GET /Users/2819c223-7f76-453a-919d-413861904646
304 Host: example.com
305 Accept: application/json
306 Authorization: Bearer h480djs93hd8
307 The server responds with:
309 HTTP/1.1 200 OK
310 Content-Type: application/json
311 Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646
312 ETag: W/"f250dd84f0671c3"
314 {
315 "schemas":["urn:scim:schemas:core:1.0"],
316 "id":"2819c223-7f76-453a-919d-413861904646,
317 "externalId":"bjensen",
318 "meta":{
319 "created":"2011-08-01T18:29:49.793Z",
320 "lastModified":"2011-08-01T18:29:49.793Z",
321 "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
322 "version":"W\/\"f250dd84f0671c3\""
323 },
324 "name":{
325 "formatted":"Ms. Barbara J Jensen III",
326 "familyName":"Jensen",
327 "givenName":"Barbara"
328 },
329 "userName":"bjensen",
330 "phoneNumbers":[
331 {
332 "value":"555-555-8377",
333 "type":"work"
334 }
335 ],
336 "emails":[
337 {
338 "value":"bjensen@example.com",
339 "type":"work"
340 }
341 ]
342 }
344 3.2.2. List/Query Resources
346 SCIM defines a standard set of operations that can be used to filter,
347 sort, and paginate response results. The operations are specified by
348 adding query parameters to the Resource's endpoint. Service
349 Providers MAY support additional query parameters not specified here,
350 and Providers SHOULD ignore any query parameters they don't
351 recognize.
353 The below example returns the userName for all Users:
355 GET /Users?attributes=userName
356 Host: example.com
357 Accept: application/json
358 Authorization: Bearer h480djs93hd8
360 HTTP/1.1 200 OK
361 Content-Type: application/json
363 {
364 "totalResults":2,
365 "schemas":["urn:scim:schemas:core:1.0"],
366 "Resources":[
367 {
368 "userName":"bjensen"
369 },
370 {
371 "userName":"jsmith"
372 }
373 ]
374 }
376 3.2.2.1. Filtering
378 Filtering is OPTIONAL. Consumers may request a subset of Resources
379 by specifying the 'filter' URL query parameter containing a filter
380 expression. When specified only those Resources matching the filter
381 expression SHALL be returned. The expression language that is used
382 in the filter parameter supports references to attributes and
383 literals. The literal values can be strings enclosed in double
384 quotes, numbers, date times enclosed in double quotes, and Boolean
385 values; i.e., true or false. String literals MUST be valid JSON
386 strings [2].
388 The attribute name and attribute operator are case insensitive. For
389 example, the following two expressions will evaluate to the same
390 logical value:
392 filter=userName Eq "john"
394 filter=Username eq "john"
396 The filter parameter MUST contain at least one valid Boolean
397 expression. Each expression MUST contain an attribute name followed
398 by an attribute operator and optional value. Multiple expressions
399 MAY be combined using the two logical operators. Furthermore
400 expressions can be grouped together using "()".
402 The operators supported in the expression are listed in the following
403 table.
405 +----------+-------------+------------------------------------------+
406 | Operator | Description | Behavior |
407 +----------+-------------+------------------------------------------+
408 | eq | equal | The attribute and operator values must |
409 | | | be identical for a match. |
410 | co | contains | The entire operator value must be a |
411 | | | substring of the attribute value for a |
412 | | | match. |
413 | sw | starts with | The entire operator value must be a |
414 | | | substring of the attribute value, |
415 | | | starting at the beginning of the |
416 | | | attribute value. This criterion is |
417 | | | satisfied if the two strings are |
418 | | | identical. |
419 | pr | present | If the attribute has a non-empty value, |
420 | | (has value) | or if it contains a non-empty node for |
421 | | | complex attributes there is a match. |
422 | gt | greater | If the attribute value is greater than |
423 | | than | operator value, there is a match. The |
424 | | | actual comparison is dependent on the |
425 | | | attribute type. For string attribute |
426 | | | types, this is a lexicographical |
427 | | | comparison and for DateTime types, it is |
428 | | | a chronological comparison. |
429 | ge | greater | If the attribute value is greater than |
430 | | than or | or equal to the operator value, there is |
431 | | equal | a match. The actual comparison is |
432 | | | dependent on the attribute type. For |
433 | | | string attribute types, this is a |
434 | | | lexicographical comparison and for |
435 | | | DateTime types, it is a chronological |
436 | | | comparison. |
437 | lt | less than | If the attribute value is less than |
438 | | | operator value, there is a match. The |
439 | | | actual comparison is dependent on the |
440 | | | attribute type. For string attribute |
441 | | | types, this is a lexicographical |
442 | | | comparison and for DateTime types, it is |
443 | | | a chronological comparison. |
444 | le | less than | If the attribute value is less than or |
445 | | or equal | equal to the operator value, there is a |
446 | | | match. The actual comparison is |
447 | | | dependent on the attribute type. For |
448 | | | string attribute types, this is a |
449 | | | lexicographical comparison and for |
450 | | | DateTime types, it is a chronological |
451 | | | comparison. |
452 +----------+-------------+------------------------------------------+
454 Table 2: Attribute Operators
456 +----------+-------------+------------------------------------------+
457 | Operator | Description | Behavior |
458 +----------+-------------+------------------------------------------+
459 | and | Logical And | The filter is only a match if both |
460 | | | expressions evaluate to true. |
461 | or | Logical or | The filter is a match if either |
462 | | | expression evaluates to true. |
463 +----------+-------------+------------------------------------------+
465 Table 3: Logical Operators
467 +----------+-------------+------------------------------------------+
468 | Operator | Description | Behavior |
469 +----------+-------------+------------------------------------------+
470 | () | Precedence | Boolean expressions may be grouped using |
471 | | grouping | parentheses to change the standard order |
472 | | | of operations; i.e., evaluate OR logical |
473 | | | operators before logical AND operators. |
474 +----------+-------------+------------------------------------------+
476 Table 4: Grouping Operators
478 Filters MUST be evaluated using standard order of operations.
479 Attribute operators have the highest precedence, followed by the
480 grouping operator (i.e, parentheses), followed by the logical AND
481 operator, followed by the logical OR operator.
483 If the specified attribute in a filter expression is a multi-valued
484 attribute, the Resource MUST match if any of the instances of the
485 given attribute match the specified criterion; e.g. if a User has
486 multiple emails values, only one has to match for the entire User to
487 match. For complex attributes, a fully qualified Sub-Attribute MUST
488 be specified using standard attribute notation (Section 3.8). For
489 example, to filter by userName the parameter value is userName and to
490 filter by first name, the parameter value is name.givenName.
492 Providers MAY support additional filter operations if they choose.
493 Providers MUST decline to filter results if the specified filter
494 operation is not recognized and return a HTTP 400 error with an
495 appropriate human readable response. For example, if a Consumer
496 specified an unsupported operator named 'regex' the Service Provider
497 should specify an error response description identifying the Consumer
498 error; e.g., 'The operator 'regex' is not supported.'
500 String type attributes are case insensitive by default unless the
501 attribute type is defined as a caseExact string. Attribute operators
502 'eq', 'co', and 'sw' MUST perform caseIgnore matching for all string
503 attributes unless the attribute is defined as caseExact. By default
504 all string attributes are caseIgnore.
506 Examples:
508 filter=userName eq "bjensen"
510 filter=name.familyName co "O'Malley"
512 filter=userName sw "J"
514 filter=title pr
516 filter=meta.lastModified gt "2011-05-13T04:42:34Z"
518 filter=meta.lastModified ge "2011-05-13T04:42:34Z"
520 filter=meta.lastModified lt "2011-05-13T04:42:34Z"
522 filter=meta.lastModified le "2011-05-13T04:42:34Z"
524 filter=title pr and userType eq "Employee"
526 filter=title pr or userType eq "Intern"
528 filter=userType eq "Employee" and (emails co "example.com" or emails
529 co "example.org")
531 3.2.2.2. Sorting
533 Sort is OPTIONAL. Sorting allows Consumers to specify the order in
534 which Resources are returned by specifying a combination of sortBy
535 and sortOrder URL parameters.
537 sortBy: The sortBy parameter specifies the attribute whose value
538 SHALL be used to order the returned responses. If the sortBy
539 attribute corresponds to a Singular Attribute, Resources are
540 sorted according to that attribute's value; if it's a Multi-valued
541 Attribute, Resources are sorted by the value of the primary
542 attribute, if any, or else the first value in the list, if any.
543 If the attribute is complex the attribute name must be a path to a
544 Sub-Attribute in standard attribute notation (Section 3.8) ; e.g.,
545 sortBy=name.givenName. For all attribute types, if there is no
546 data for the specified sortBy value they are sorted via the
547 'sortOrder' parameter; i.e., they are ordered last if ascending
548 and first if descending.
550 sortOrder: The order in which the sortBy parameter is applied.
551 Allowed values are "ascending" and "descending". If a value for
552 sortBy is provided and no sortOrder is specified, the sortOrder
553 SHALL default to ascending. String type attributes are case
554 insensitive by default unless the attribute type is defined as a
555 caseExact string. sortOrder MUST sort according to the attribute
556 type; i.e., for caseIgnore attributes, sort the result using case
557 insensitive, Unicode alphabetic sort order, with no specific
558 locale implied and for caseExact attribute types, sort the result
559 using case sensitive, Unicode alphabetic sort order.
561 3.2.2.3. Pagination
563 Pagination parameters can be used together to "page through" large
564 numbers of Resources so as not to overwhelm the Consumer or Service
565 Provider. Pagination is not session based hence Consumers SHOULD
566 never assume repeatable results. For example, a request for a list
567 of 10 Resources beginning with a startIndex of 1 may return different
568 results when repeated as a Resource in the original result could be
569 deleted or new ones could be added in-between requests. Pagination
570 parameters and general behavior are derived from the OpenSearch
571 Protocol [3].
573 The following table describes the URL pagination parameters.
575 +------------+-------------------+----------------------------------+
576 | Parameter | Description | Default |
577 +------------+-------------------+----------------------------------+
578 | startIndex | The 1-based index | 1 |
579 | | of the first | |
580 | | search result. | |
581 | count | Non-negative | None. When specified the |
582 | | Integer. | Service Provider MUST not return |
583 | | Specifies the | more results than specified |
584 | | desired maximum | though MAY return fewer results. |
585 | | number of search | If unspecified, the maximum |
586 | | results per page; | number of results is set by the |
587 | | e.g., 10. | Service Provider. |
588 +------------+-------------------+----------------------------------+
590 Table 5: Pagination Request parameters
592 The following table describes the query response pagination
593 attributes specified by the Service Provider.
595 +--------------+----------------------------------------------------+
596 | Element | Description |
597 +--------------+----------------------------------------------------+
598 | itemsPerPage | Non-negative Integer. Specifies the number of |
599 | | search results returned in a query response page; |
600 | | e.g., 10. |
601 | totalResults | Non-negative Integer. Specifies the total number |
602 | | of results matching the Consumer query; e.g., |
603 | | 1000. |
604 | startIndex | The 1-based index of the first result in the |
605 | | current set of search results; e.g., 1. |
606 +--------------+----------------------------------------------------+
608 Table 6: Pagination Response Elements
610 For example, to retrieve the first 10 Users set the startIndex to 1
611 and the count to 10.
613 GET /Users?startIndex=1&count=10
614 Host: example.com
615 Accept: application/json
616 Authorization: Bearer h480djs93hd8
618 {
619 "totalResults":100,
620 "itemsPerPage":10,
621 "startIndex":1,
622 "schemas":["urn:scim:schemas:core:1.0"],
623 "Resources":[{
624 ...
625 }]
626 }
627 Given the example above, to continue paging set the startIndex to 11
628 and re-fetch; i.e., /Users?startIndex=11&count=10
630 3.3. Modifying Resources
632 Resources can be modified in whole or in part via PUT or PATCH,
633 respectively. Implementers MUST support PUT as specified in RFC2616
634 . Resources such as Groups may be very large hence implementers
635 SHOULD support PATCH [4] to enable partial resource modifications.
637 3.3.1. Modifying with PUT
639 PUT performs a full update. Consumers must retrieve the entire
640 Resource and PUT the desired modifications as the operation
641 overwrites all previously stored data with the exception of the
642 password attribute. If the password attribute of the User resource
643 is unspecified, it should be left in-tact. Since this performs a
644 full update, Consumers MAY send read-only attributes of the retrieved
645 resource and Service Provider MUST ignore any read-only attributes
646 that are present in the payload of a PUT request. Unless otherwise
647 specified a successful PUT operation returns a 200 OK response code
648 and the entire Resource within the response body, enabling the
649 Consumer to correlate the Consumer's and Provider's views of the
650 updated Resource. Example:
652 PUT /Users/2819c223-7f76-453a-919d-413861904646
653 Host: example.com
654 Accept: application/json
655 Content-Type: application/json
656 Authorization: Bearer h480djs93hd8
657 If-Match: W/"a330bc54f0671c9"
659 {
660 "schemas":["urn:scim:schemas:core:1.0"],
661 "id":"2819c223-7f76-453a-919d-413861904646",
662 "userName":"bjensen",
663 "externalId":"bjensen",
664 "name":{
665 "formatted":"Ms. Barbara J Jensen III",
666 "familyName":"Jensen",
667 "givenName":"Barbara",
668 "middleName":"Jane"
669 },
670 "emails":[
671 {
672 "value":"bjensen@example.com"
673 },
674 {
675 "value":"babs@jensen.org"
676 }
677 ]
678 }
680 The service responds with the entire, updated User
682 HTTP/1.1 200 OK
683 Content-Type: application/json
684 ETag: W/"b431af54f0671a2"
685 Location:"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646"
686 {
687 "schemas":["urn:scim:schemas:core:1.0"],
688 "id":"2819c223-7f76-453a-919d-413861904646",
689 "userName":"bjensen",
690 "externalId":"bjensen",
691 "name":{
692 "formatted":"Ms. Barbara J Jensen III",
693 "familyName":"Jensen",
694 "givenName":"Barbara",
695 "middleName":"Jane"
696 },
697 "emails":[
698 {
699 "value":"bjensen@example.com"
700 },
701 {
702 "value":"babs@jensen.org"
703 }
704 ],
705 "meta": {
706 "created":"2011-08-08T04:56:22Z",
707 "lastModified":"2011-08-08T08:00:12Z",
708 "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
709 "version":"W\/\"b431af54f0671a2\""
710 }
711 }
713 3.3.2. Modifying with PATCH
715 PATCH is OPTIONAL. PATCH enables consumers to send only those
716 attributes requiring modification, reducing network and processing
717 overhead. Attributes may be deleted, replaced, merged, or added in a
718 single request.
720 The body of a PATCH request MUST contain a partial Resource with the
721 desired modifications. The server MUST return either a 200 OK
722 response code and the entire Resource (subject to the "attributes"
723 query parameter - see Additional Retrieval Query Parameters
724 (Section 3.7)) within the response body, or a 204 No Content response
725 code and the appropriate response headers for a successful PATCH
726 request. The server MUST return a 200 OK if the "attributes"
727 parameter is specified on the request.
729 The server MUST process a PATCH request by first removing any
730 attributes specified in the meta.attributes Sub-Attribute (if
731 present) and then merging the attributes in the PATCH request body
732 into the Resource.
734 The meta.attributes Sub-Attribute MAY contain a list of attributes to
735 be removed from the Resource. If the PATCH request body contains an
736 attribute that is present in the meta.attributes list, the attribute
737 on the Resource is replaced with the value from the PATCH body. If
738 the attribute is complex the attribute name must be a path to a Sub-
739 Attribute in standard attribute notation (Section 3.8); e.g.,
740 name.givenName.
742 Attributes that exist in the PATCH request body but not in the
743 meta.attributes Sub-Attribute will be either be updated or added to
744 the Resource according to the following rules.
746 Singular attributes: Singular attributes in the PATCH request body
747 replace the attribute on the Resource.
749 Complex attributes: Complex Sub-Attribute values in the PATCH
750 request body are merged into the complex attribute on the
751 Resource.
753 Multi-valued attributes: An attribute value in the PATCH request
754 body is added to the value collection if the value does not exist
755 and merged if a matching value is present. Values are matched by
756 comparing the value Sub-Attribute from the PATCH request body to
757 the value Sub-Attribute of the Resource. Attributes that do not
758 have a value Sub-Attribute; e.g., addresses, or do not have unique
759 value Sub-Attributes cannot be matched and must instead be deleted
760 then added. Specific values can be removed from a Resource by
761 adding an "operation" Sub-Attribute with the value "delete" to the
762 attribute in the PATCH request body. As with adding/updating
763 attribute value collections, the value to delete is determined by
764 comparing the value Sub-Attribute from the PATCH request body to
765 the value Sub-Attribute of the Resource. Attributes that do not
766 have a value Sub-Attribute or that have a non-unique value Sub-
767 Attribute are matched by comparing all Sub-Attribute values from
768 the PATCH request body to the Sub-Attribute values of the
769 Resource. A delete operation is ignored if the attribute's name
770 is in the meta.attributes list. If the requested value to delete
771 does not match a unique value on the Resource the server MAY
772 return a HTTP 400 error.
774 The following example shows how to add a member to a group:
776 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
777 Host: example.com
778 Accept: application/json
779 Content-Type: application/json
780 Authorization: Bearer h480djs93hd8
781 If-Match: W/"a330bc54f0671c9"
783 {
784 "schemas": ["urn:scim:schemas:core:1.0"],
785 "members": [
786 {
787 "display": "Babs Jensen",
788 "value": "2819c223-7f76-453a-919d-413861904646"
789 }
790 ]
791 }
793 The "display" Sub-Attribute in this request is optional since the
794 value attribute uniquely identifies the user to be added. If the
795 user was already a member of this group, no changes should be made to
796 the Resource and a success response should be returned. The server
797 responds with either the entire updated Group or no response body:
799 HTTP/1.1 204 No Content
800 Authorization: Bearer h480djs93hd8
801 ETag: W/"b431af54f0671a2"
802 Location: "https://example.com/v1/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce"
804 The following example shows how to remove a member from a group. As
805 with the previous example, the "display" Sub-Attribute is optional.
806 If the user was not a member of this group, no changes should be made
807 to the Resource and a success response should be returned.
809 Note that server responses have been omitted for the rest of the
810 PATCH examples.
812 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
813 Host: example.com
814 Accept: application/json
815 Content-Type: application/json
816 Authorization: Bearer h480djs93hd8
817 If-Match: W/"a330bc54f0671c9"
819 {
820 "schemas": ["urn:scim:schemas:core:1.0"],
821 "members": [
822 {
823 "display": "Babs Jensen",
824 "value": "2819c223-7f76-453a-919d-413861904646"
825 "operation": "delete"
826 }
827 ]
828 }
830 The following example shows how to remove all members from a group:
832 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
833 Host: example.com
834 Accept: application/json
835 Content-Type: application/json
836 Authorization: Bearer h480djs93hd8
837 If-Match: W/"a330bc54f0671c9"
839 {
840 "schemas": ["urn:scim:schemas:core:1.0"],
841 "meta": {
842 "attributes": [
843 "members"
844 ]
845 }
846 }
848 The following example shows how to replace all of the members of a
849 group with a different members list:
851 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
852 Host: example.com
853 Accept: application/json
854 Content-Type: application/json
855 Authorization: Bearer h480djs93hd8
856 If-Match: W/"a330bc54f0671c9"
858 {
859 "schemas": ["urn:scim:schemas:core:1.0"],
860 "meta": {
861 "attributes": [
862 "members"
863 ]
864 },
865 "members": [
866 {
867 "display": "Babs Jensen",
868 "value": "2819c223-7f76-453a-919d-413861904646"
869 },
870 {
871 "display": "James Smith",
872 "value": "08e1d05d-121c-4561-8b96-473d93df9210"
873 }
874 ]
875 }
877 The following example shows how to add a member to and remove a
878 member from a Group in a single request:
880 PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
881 Host: example.com
882 Accept: application/json
883 Content-Type: application/json
884 Authorization: Bearer h480djs93hd8
885 If-Match: W/"a330bc54f0671c9"
887 {
888 "schemas": ["urn:scim:schemas:core:1.0"],
889 "members": [
890 {
891 "display": "Babs Jensen",
892 "value": "2819c223-7f76-453a-919d-413861904646"
893 "operation": "delete"
894 },
895 {
896 "display": "James Smith",
897 "value": "08e1d05d-121c-4561-8b96-473d93df9210"
898 }
899 ]
900 }
902 The following example shows how to change a User's primary email. If
903 the User already has the email address, it is made the primary
904 address and the current primary address (if present) is made non-
905 primary. If the User does not already have the email address, it is
906 added and made the primary address.
908 PATCH /Users/2819c223-7f76-453a-919d-413861904646
909 Host: example.com
910 Accept: application/json
911 Content-Type: application/json
912 Authorization: Bearer h480djs93hd8
913 If-Match: W/"a330bc54f0671c9"
915 {
916 "schemas": ["urn:scim:schemas:core:1.0"],
917 "emails": [
918 {
919 "value": "bjensen@example.com",
920 "primary": true
921 }
922 ]
923 }
925 The following example shows how to change a User's address. Since
926 address does not have a value Sub-Attribute, the existing address
927 must be removed and the modified address added.
929 PATCH /Users/2819c223-7f76-453a-919d-413861904646
930 Host: example.com
931 Accept: application/json
932 Content-Type: application/json
933 Authorization: Bearer h480djs93hd8
934 If-Match: W/"a330bc54f0671c9"
936 {
937 "schemas": ["urn:scim:schemas:core:1.0"],
938 "addresses": [
939 {
940 "type": "work",
941 "streetAddress": "100 Universal City Plaza",
942 "locality": "Hollywood",
943 "region": "CA",
944 "postalCode": "91608",
945 "country": "US",
946 "formatted": "100 Universal City Plaza\nHollywood, CA 91608 US",
947 "primary": true
948 "operation": "delete"
949 },
950 {
951 "type": "work",
952 "streetAddress": "911 Universal City Plaza",
953 "locality": "Hollywood",
954 "region": "CA",
955 "postalCode": "91608",
956 "country": "US",
957 "formatted": "911 Universal City Plaza\nHollywood, CA 91608 US",
958 "primary": true
959 }
960 ]
961 }
963 The following example shows how to change a User's nickname:
965 PATCH /Users/2819c223-7f76-453a-919d-413861904646
966 Host: example.com
967 Accept: application/json
968 Content-Type: application/json
969 Authorization: Bearer h480djs93hd8
970 If-Match: W/"a330bc54f0671c9"
972 {
973 "schemas": ["urn:scim:schemas:core:1.0"],
974 "nickName": "Barbie"
975 }
976 The following example shows how to remove a User's nickname:
978 PATCH /Users/2819c223-7f76-453a-919d-413861904646
979 Host: example.com
980 Accept: application/json
981 Content-Type: application/json
982 Authorization: Bearer h480djs93hd8
983 If-Match: W/"a330bc54f0671c9"
985 {
986 "schemas": ["urn:scim:schemas:core:1.0"],
987 "meta": {
988 "attributes": [
989 "nickName"
990 ]
991 }
992 }
994 The following example shows how to change a User's familyName. This
995 only updates the familyName and formatted on the "name" complex
996 attribute. Any other name Sub-Attributes on the Resource remain
997 unchanged.
999 PATCH /Users/2819c223-7f76-453a-919d-413861904646
1000 Host: example.com
1001 Accept: application/json
1002 Content-Type: application/json
1003 Authorization: Bearer h480djs93hd8
1004 If-Match: W/"a330bc54f0671c9"
1006 {
1007 "schemas": ["urn:scim:schemas:core:1.0"],
1008 "name": {
1009 "formatted": "Ms. Barbara J Jensen III",
1010 "familyName": "Jensen"
1011 }
1012 }
1014 The following example shows how to remove a complex Sub-Attribute and
1015 an extended schema attribute from a User.
1017 PATCH /Users/2819c223-7f76-453a-919d-413861904646
1018 Host: example.com
1019 Accept: application/json
1020 Content-Type: application/json
1021 Authorization: Bearer h480djs93hd8
1022 If-Match: W/"a330bc54f0671c9"
1024 {
1025 "schemas": ["urn:scim:schemas:core:1.0"],
1026 "meta": {
1027 "attributes": [
1028 "name.formatted",
1029 "urn:hr:schemas:user:age"
1030 ]
1031 }
1032 }
1034 3.4. Deleting Resources
1036 Consumers request Resource removal via DELETE. Service Providers MAY
1037 choose not to permanently delete the Resource, but MUST return a 404
1038 error code for all operations associated with the previously deleted
1039 Id. Service Providers MUST also omit the Resource from future query
1040 results. In addition the Service Provider MUST not consider the
1041 deleted resource in conflict calculation. For example if a User
1042 resource is deleted, a CREATE request for a User resource with the
1043 same userName as the previously deleted resource should not fail with
1044 a 409 error due to userName conflict.
1046 DELETE /Users/2819c223-7f76-453a-919d-413861904646
1047 Host: example.com
1048 Authorization: Bearer h480djs93hd8
1049 If-Match: W/"c310cd84f0281b7"
1051 HTTP/1.1 200 OK
1053 Example: Consumer attempt to retrieve the previously deleted User
1055 GET /Users/2819c223-7f76-453a-919d-413861904646
1056 Host: example.com
1057 Authorization: Bearer h480djs93hd8
1059 HTTP/1.1 404 NOT FOUND
1061 {
1062 "Errors":[
1063 {
1064 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
1065 "code":"404"
1066 }
1067 ]
1068 }
1070 3.5. Bulk
1072 Bulk is OPTIONAL. The bulk operation enables Consumers to send a
1073 potentially large collection of Resource operations in a single
1074 request. The body of a a bulk operation contains a set of HTTP
1075 Resource operations using one of the API supported HTTP methods;
1076 i.e., POST, PUT, PATCH or DELETE.
1078 The following Singular Attribute is defined in addition to the common
1079 attributes defined in SCIM core schema.
1081 failOnErrors An Integer specifying the number of errors that the
1082 Service Provider will accept before the operation is terminated
1083 and an error response is returned. OPTIONAL.
1085 The following Complex Multi-valued Attribute is defined in addition
1086 to the common attributes defined in core schema.
1088 Operations Defines operations within a bulk job. Each operation
1089 corresponds to a single HTTP request against a Resource endpoint.
1090 REQUIRED.
1092 method The HTTP method of the current operation. Possible values
1093 are POST, PUT, PATCH or DELETE. REQUIRED.
1095 bulkId The transient identifier of a newly created Resource,
1096 unique within a bulk request and created by the Consumer. The
1097 bulkId serves as a surrogate Resource id enabling Consumers to
1098 uniquely identify newly created Resources in the Response and
1099 cross reference new Resources in and across operations within a
1100 bulk request. REQUIRED when method is POST.
1102 version The current Resource version. Version is REQUIRED if the
1103 Service Provider supports ETags and the method is PUT, DELETE,
1104 or PATCH.
1106 path The Resource's relative path. If the method is POST the
1107 value must specify a Resource type endpoint; e.g., /Users or
1108 /Groups whereas all other method values must specify the path
1109 to a specific Resource; e.g., /Users/
1110 2819c223-7f76-453a-919d-413861904646. REQUIRED in a request.
1112 data The Resource data as it would appear for a single POST, PUT
1113 or PATCH Resource operation. REQUIRED in a request when method
1114 is POST, PUT and PATCH.
1116 location The Resource endpoint URL. REQUIRED in a response,
1117 except in the event of a POST failure.
1119 status A complex type that contains information about the success
1120 or failure of one operation within the bulk job. REQUIRED in a
1121 response.
1123 code The HTTP response code that would have been returned if a
1124 a single HTTP request would have been used. REQUIRED.
1126 description A human readable error message. REQUIRED when an
1127 error occurred.
1129 If a bulk job is processed successfully the HTTP response code 200 OK
1130 MUST be returned, otherwise an appropriate HTTP error code MUST be
1131 returned.
1133 The Service Provider MUST continue performing as many changes as
1134 possible and disregard partial failures. The Consumer MAY override
1135 this behavior by specifying a value for failOnErrors attribute. The
1136 failOnErrors attribute defines the number of errors that the Service
1137 Provider should accept before failing the remaining operations
1138 returning the response.
1140 To be able to reference a newly created Resource the attribute bulkId
1141 MUST be specified when creating new Resources. The bulkId is defined
1142 by the Consumer as a surrogate identifier in a POST operation. The
1143 Service Provider MUST return the same bulkId together with the newly
1144 created Resource. The bulkId can then be used by the Consumer to map
1145 the Service Provider id with the bulkId of the created Resource.
1147 There can be more then one operation per Resource in each bulk job.
1148 The Service Consumer MUST take notice of the unordered structure of
1149 JSON and the Service Provider can process operations in any order.
1150 For example, if the Service Consumer sends two PUT operations in one
1151 request, the outcome is non-deterministic.
1153 The Service Provider response MUST include the result of all
1154 processed operations. A location attribute that includes the
1155 Resource's end point MUST be returned for all operations excluding
1156 failed POSTs. The status attribute includes information about the
1157 success or failure of one operation within the bulk job. The
1158 attribute status MUST include the code attribute that holds the HTTP
1159 response code that would have been returned if a single HTTP request
1160 would have been used. If an error occurred the status MUST also
1161 include the description attribute containing a human readable
1162 explanation of the error.
1164 "status": {
1165 "code": "201"
1166 }
1168 The following is an example of a status in a failed operation.
1170 "status": {
1171 "code": "400",
1172 "description": "Request is unparseable, syntactically incorrect, or violates schema."
1173 }
1175 The following example shows how to add, update, and remove a user.
1176 The failOnErrors attribute is set to '1' indicating the Service
1177 Provider should return on the first error. The POST operation's
1178 bulkId value is set to 'qwerty' enabling the Consumer to match the
1179 new User with the returned Resource id '92b725cd-9465-4e7d-8c16-
1180 01f8e146b87a'.
1182 POST /v1/Bulk
1183 Host: example.com
1184 Accept: application/json
1185 Content-Type: application/json
1186 Authorization: Bearer h480djs93hd8
1187 Content-Length: ...
1189 {
1190 "schemas":[
1191 "urn:scim:schemas:core:1.0"
1192 ],
1193 "failOnErrors":1,
1194 "Operations":[
1195 {
1196 "method":"POST",
1197 "path":"/Users",
1198 "bulkId":"qwerty",
1199 "data":{
1200 "schemas":[
1201 "urn:scim:schemas:core:1.0"
1202 ],
1203 "userName":"Alice"
1204 }
1205 },
1206 {
1207 "method":"PUT",
1208 "path":"/Users/b7c14771-226c-4d05-8860-134711653041",
1209 "version":"W\/\"3694e05e9dff591\"",
1210 "data":{
1211 "schemas":[
1212 "urn:scim:schemas:core:1.0"
1213 ],
1214 "id":"b7c14771-226c-4d05-8860-134711653041",
1215 "userName":"Bob"
1216 }
1217 },
1218 {
1219 "method":"PATCH",
1220 "path":"/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
1221 "version":"W\/\"edac3253e2c0ef2\"",
1222 "data":{
1223 "schemas":[
1224 "urn:scim:schemas:core:1.0"
1225 ],
1226 "id":"5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
1227 "userName":"Dave",
1228 "meta":{
1229 "attributes":[
1230 "nickName"
1231 ]
1232 }
1233 }
1234 },
1235 {
1236 "method":"DELETE",
1237 "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b",
1238 "version":"W\/\"0ee8add0a938e1a\""
1239 }
1240 ]
1241 }
1243 The Service Provider returns the following response.
1245 HTTP/1.1 200 OK
1246 Content-Type: application/json
1248 {
1249 "schemas": [
1250 "urn:scim:schemas:core:1.0"
1251 ],
1252 "Operations": [
1253 {
1254 "location": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
1255 "method": "POST",
1256 "bulkId": "qwerty",
1257 "version": "W\/\"oY4m4wn58tkVjJxK\"",
1258 "status": {
1259 "code": "201"
1260 }
1261 },
1262 {
1263 "location": "https://example.com/v1/Users/b7c14771-226c-4d05-8860-134711653041",
1264 "method": "PUT",
1265 "version": "W\/\"huJj29dMNgu3WXPD\"",
1266 "status": {
1267 "code": "200"
1268 }
1269 },
1270 {
1271 "location": "https://example.com/v1/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
1272 "method": "PATCH",
1273 "version": "W\/\"huJj29dMNgu3WXPD\"",
1274 "status": {
1275 "code": "200"
1276 }
1277 },
1278 {
1279 "location": "https://example.com/v1/Users/e9025315-6bea-44e1-899c-1e07454e468b",
1280 "method": "DELETE",
1281 "status": {
1282 "code": "200"
1283 }
1284 }
1285 ]
1286 }
1288 The following response is returned if an error occurred when
1289 attempting to create the User 'Alice'. The Service Provider stops
1290 processing the bulk operation and immediately returns a response to
1291 the Consumer. The response contains the error and any successful
1292 results prior to the error.
1294 HTTP/1.1 200 OK
1295 Content-Type: application/json
1297 {
1298 "schemas": [
1299 "urn:scim:schemas:core:1.0"
1300 ],
1301 "Operations": [
1302 {
1303 "method": "POST",
1304 "bulkId": "qwerty",
1305 "status": {
1306 "code": "400",
1307 "description": "Request is unparseable, syntactically incorrect, or violates schema."
1308 }
1309 }
1310 ]
1311 }
1313 If the failOnErrors attribute is not specified or the Service
1314 Provider has not reached the error limit defined by the Consumer the
1315 Service Provider will continue to process all operations. The
1316 following is an example in which all operations failed.
1318 HTTP/1.1 200 OK
1319 Content-Type: application/json
1321 {
1322 "schemas": [
1323 "urn:scim:schemas:core:1.0"
1324 ],
1325 "Operations": [
1326 {
1327 "method": "POST",
1328 "bulkId": "qwerty",
1329 "status": {
1330 "code": "400",
1331 "description": "Request is unparseable, syntactically incorrect, or violates schema."
1332 }
1333 },
1334 {
1335 "location": "https://example.com/v1/Users/b7c14771-226c-4d05-8860-134711653041",
1336 "method": "PUT",
1337 "status": {
1338 "code": "412",
1339 "description": "Failed to update as user changed on the server since you last retrieved it."
1340 }
1341 },
1342 {
1343 "location": "https://example.com/v1/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
1344 "method": "PATCH",
1345 "status": {
1346 "code": "412",
1347 "description": "Failed to update as user changed on the server since you last retrieved it."
1348 }
1349 },
1350 {
1351 "location": "https://example.com/v1/Users/e9025315-6bea-44e1-899c-1e07454e468b",
1352 "method": "DELETE",
1353 "status": {
1354 "code": "404",
1355 "description": "Specified resource; e.g., User, does not exist."
1356 }
1357 }
1358 ]
1359 }
1361 The Consumer can, within one bulk operation, create a new User, a new
1362 Group and add the newly created User to the newly created Group. In
1363 order to add the new User to the Group the Consumer must use the
1364 surrogate id attribute, bulkId, to reference the User. The bulkId
1365 attribute value must be pre-pended with the literal "bulkId:"; e.g.,
1366 if the bulkId is 'qwerty' the value is "bulkId:qwerty". The Service
1367 Provider MUST replace the string "bulkId:qwerty" with the permanent
1368 Resource id once created.
1370 The following example creates a User with the userName 'Alice' and a
1371 Group with the displayName 'Tour Guides' with Alice as a member.
1373 POST /v1/Bulk
1374 Host: example.com
1375 Accept: application/json
1376 Content-Type: application/json
1377 Authorization: Bearer h480djs93hd8
1378 Content-Length: ...
1380 {
1381 "schemas": [
1382 "urn:scim:schemas:core:1.0"
1383 ],
1384 "Operations": [
1385 {
1386 "method": "POST",
1387 "path": "/Users",
1388 "bulkId": "qwerty",
1389 "data": {
1390 "schemas": [
1391 "urn:scim:schemas:core:1.0"
1392 ],
1393 "userName": "Alice"
1394 }
1395 },
1396 {
1397 "method": "POST",
1398 "path": "/Groups",
1399 "bulkId": "ytrewq",
1400 "data": {
1401 "schemas": [
1402 "urn:scim:schemas:core:1.0"
1403 ],
1404 "displayName": "Tour Guides",
1405 "members": [
1406 {
1407 "type": "user",
1408 "value": "bulkId:qwerty"
1409 }
1410 ]
1411 }
1412 }
1414 ]
1415 }
1417 The Service Provider returns the following response.
1419 HTTP/1.1 200 OK
1420 Content-Type: application/json
1422 {
1423 "schemas": [
1424 "urn:scim:schemas:core:1.0"
1425 ],
1426 "Operations": [
1427 {
1428 "location": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
1429 "method": "POST",
1430 "bulkId": "qwerty",
1431 "version": "W\/\"4weymrEsh5O6cAEK\"",
1432 "status": {
1433 "code": "201"
1434 }
1435 },
1436 {
1437 "location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
1438 "method": "POST",
1439 "bulkId": "ytrewq",
1440 "version": "W\/\"lha5bbazU3fNvfe5\"",
1441 "status": {
1442 "code": "201"
1443 }
1444 }
1445 ]
1446 }
1448 A subsequent request for the 'Tour Guides' Group ('e9e30dba-f08f-
1449 4109-8486-d5c6a331660a') returns the following:
1451 GET /v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
1452 Host: example.com
1453 Accept: application/json
1454 Authorization: Bearer h480djs93hd8
1456 HTTP/1.1 200 OK
1457 Content-Type: application/json
1458 Location: https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
1459 ETag: W/"lha5bbazU3fNvfe5"
1461 {
1462 "schemas":["urn:scim:schemas:core:1.0"],
1463 "id": "e9e30dba-f08f-4109-8486-d5c6a331660a",
1464 "displayName": "Tour Guides",
1465 "meta": {
1466 "created":"2011-08-01T18:29:49.793Z",
1467 "lastModified":"2011-08-01T20:31:02.315Z",
1468 "location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
1469 "version": "W\/\"lha5bbazU3fNvfe5\""
1470 },
1471 "members": [
1472 {
1473 "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a",
1474 "type": "user"
1475 }
1476 ]
1477 }
1479 Extensions that include references to other Resources MUST be handled
1480 in the same way by the Service Provider. The following example uses
1481 the bulkId attribute within the enterprise extension managerId
1482 attribute.
1484 POST /v1/Bulk
1485 Host: example.com
1486 Accept: application/json
1487 Content-Type: application/json
1488 Authorization: Bearer h480djs93hd8
1489 Content-Length: ...
1491 {
1492 "schemas": [
1493 "urn:scim:schemas:core:1.0"
1494 ],
1495 "Operations": [
1496 {
1497 "method": "POST",
1498 "path": "/Users",
1499 "bulkId": "qwerty",
1500 "data": {
1501 "schemas": [
1502 "urn:scim:schemas:core:1.0"
1503 ],
1504 "userName": "Alice"
1505 }
1506 },
1507 {
1508 "method": "POST",
1509 "path": "/Users",
1510 "bulkId": "ytrewq",
1511 "data": {
1512 "schemas": [
1513 "urn:scim:schemas:core:1.0",
1514 "urn:scim:schemas:extension:enterprise:1.0"
1515 ],
1516 "userName": "Bob",
1517 "urn:scim:schemas:extension:enterprise:1.0": {
1518 "employeeNumber": "11250",
1519 "manager": {
1520 "managerId": "batchId:qwerty",
1521 "displayName": "Alice"
1522 }
1523 }
1524 }
1525 }
1526 ]
1527 }
1529 The Service Provider MUST try to resolve circular cross references
1530 between Resources in a single bulk job but MAY stop after a failed
1531 attempt and instead return the status code 409 Conflict. The
1532 following example exhibits the potential conflict.
1534 POST /v1/Bulk
1535 Host: example.com
1536 Accept: application/json
1537 Content-Type: application/json
1538 Authorization: Bearer h480djs93hd8
1539 Content-Length: ...
1541 {
1542 "schemas": [
1543 "urn:scim:schemas:core:1.0"
1544 ],
1545 "Operations": [
1546 {
1547 "method": "POST",
1548 "path": "/Groups",
1549 "bulkId": "qwerty",
1550 "data": {
1551 "schemas": [
1552 "urn:scim:schemas:core:1.0"
1553 ],
1554 "displayName": "Group A",
1555 "members": [
1556 {
1557 "type": "group",
1558 "value": "bulkId:ytrewq"
1559 }
1560 ]
1561 }
1562 },
1563 {
1564 "method": "POST",
1565 "path": "/Groups",
1566 "bulkId": "ytrewq",
1567 "data": {
1568 "schemas": [
1569 "urn:scim:schemas:core:1.0"
1570 ],
1571 "displayName": "Group B",
1572 "members": [
1573 {
1574 "type": "group",
1575 "value": "bulkId:qwerty"
1576 }
1577 ]
1578 }
1579 }
1580 ]
1581 }
1582 If the Service Provider resolved the above circular references the
1583 following is returned from a subsequent GET request.
1585 GET /v1/Groups?filter=displayName sw 'Group'
1586 Host: example.com
1587 Accept: application/json
1588 Authorization: Bearer h480djs93hd8
1590 HTTP/1.1 200 OK
1591 Content-Type: application/json
1593 {
1594 "totalResults": 2,
1595 "schemas": [
1596 "urn:scim:schemas:core:1.0"
1597 ],
1598 "Resources": [
1599 {
1600 "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
1601 "schemas": [
1602 "urn:scim:schemas:core:1.0"
1603 ],
1604 "displayName": "Group A",
1605 "meta": {
1606 "created":"2011-08-01T18:29:49.793Z",
1607 "lastModified":"2011-08-01T18:29:51.135Z",
1608 "location":"https://example.com/v1/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
1609 "version":"W\/\"mvwNGaxB5SDq074p\""
1610 },
1611 "members": [
1612 {
1613 "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
1614 "type": "group"
1615 }
1616 ]
1617 },
1618 {
1619 "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
1620 "schemas": [
1621 "urn:scim:schemas:core:1.0"
1622 ],
1623 "displayName": "Group B",
1624 "meta": {
1625 "created":"2011-08-01T18:29:50.873Z",
1626 "lastModified":"2011-08-01T18:29:50.873Z",
1627 "location":"https://example.com/v1/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
1628 "version":"W\/\"wGB85s2QJMjiNnuI\""
1629 },
1630 "members": [
1631 {
1632 "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
1633 "type": "group"
1634 }
1635 ]
1636 }
1637 ]
1638 }
1640 The Service Provider MUST define the maximum number of operations and
1641 maximum payload size a Consumer may send in a single request. If
1642 either limits are exceeded the Service Provider MUST return the HTTP
1643 response code 413 Request Entity Too Large. The returned response
1644 MUST specify the limit exceeded in the body of the error response.
1646 The following example the Consumer sent a request exceeding the
1647 Service Provider's max payload size of 1 megabyte.
1649 POST /v1/Bulk
1650 Host: example.com
1651 Accept: application/json
1652 Content-Type: application/json
1653 Authorization: Bearer h480djs93hd8
1654 Content-Length: 4294967296
1656 ...
1658 HTTP/1.1 413 Request Entity Too Large
1659 Content-Type: application/json
1660 Location: https://example.com/v1/Bulk/yfCrVJhFIJagAHj8
1662 {
1663 "Errors":[
1664 {
1665 "description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).",
1666 "code":"413"
1667 }
1668 ]
1669 }
1670 3.6. Data Input/Output Formats
1672 Consumers MUST specify the format in which the data is submitted via
1673 the HTTP header content-type and MAY specify the desired response
1674 data format via an HTTP Accept Header; e.g.,"Accept: application/
1675 json" or via URI suffix; e.g.,
1677 GET /Users/2819c223-7f76-453a-919d-413861904646.json
1678 Host: example.com
1680 GET /Users/2819c223-7f76-453a-919d-413861904646.xml
1681 Host: example.com
1683 Service Providers MUST support the Accept Headers "Accept:
1684 application/json" for JSON [5] and, if supported, "Accept:
1685 application/xml" for XML [6]. The format defaults to JSON if no
1686 format is specified. The data structure returned is equivalent in
1687 both formats; the only difference is in the encoding of the data.
1689 Singular attributes are encoded as string name-value-pairs in JSON;
1690 e.g.,
1692 "attribute": "value"
1694 and elements in XML; e.g.,
1696 value
1698 Multi-valued attributes in JSON are encoded as arrays; e.g.,
1700 "attributes": [ "value1", "value2" ]
1702 and repeated tags in XML; e.g.,
1704 value1
1705 value2
1707 Elements with nested elements are represented as objects in JSON;
1708 e.g,
1710 "attribute": { "subattribute1": "value1", "subattribute2": "value2" }
1712 and repeated tags in XML; e.g.,
1714
1715 value1
1716 value2
1718
1720 3.7. Additional retrieval query parameters
1722 Consumers MAY request a partial Resource representation on any
1723 operation that returns a Resource within the response by specifying
1724 the URL query parameter 'attributes'. When specified, each Resource
1725 returned MUST contain the minimal set of Resource attributes and,
1726 MUST contain no other attributes or Sub-Attributes than those
1727 explicitly requested. The query parameter attributes value is a
1728 comma separated list of Resource attribute names in standard,
1729 attribute notation (Section 3.8) form (e.g. userName, name, emails).
1731 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName
1732 Host: example.com
1733 Accept: application/json
1734 Authorization: Bearer h480djs93hd8
1736 Giving the response
1738 HTTP/1.1 200 OK
1739 Content-Type: application/json
1740 Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646
1741 ETag: W/"a330bc54f0671c9"
1743 {
1744 "schemas":["urn:scim:schemas:core:1.0"],
1745 "id":"2819c223-7f76-453a-919d-413861904646",
1746 "userName":"bjensen",
1747 "meta":{
1748 "created":"2011-08-01T18:29:49.793Z",
1749 "lastModified":"2011-08-01T18:29:49.793Z",
1750 "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
1751 "version":"W\/\"a330bc54f0671c9\""
1752 }
1753 }
1755 3.8. Attribute Notation
1757 All operations share a common scheme for referencing simple and
1758 complex attributes. In general, attributes are identified by
1759 prefixing the attribute name with its schema URN separated by a ':'
1760 character; e.g., the core User Resource attribute 'userName' is
1761 identified as 'urn:scim:schemas:core:1.0:userName'. Consumers MAY
1762 omit core schema attribute URN prefixes though MUST fully qualify
1763 extended attributes with the associated Resource URN; e.g., the
1764 attribute 'age' defined in 'urn:hr:schemas:user' is fully encoded as
1765 'urn:hr:schemas:user:age'. A Complex attributes' Sub-Attributes are
1766 referenced via nested, dot ('.') notation; i.e., {urn}:{Attribute
1767 name}.{Sub-Attribute name}. For example, the fully qualified path
1768 for a User's givenName is urn:scim:schemas:core:1.0:name.givenName
1769 All facets (URN, attribute and Sub-Attribute name) of the fully
1770 encoded Attribute name are case insensitive.
1772 3.9. HTTP Response Codes
1774 The SCIM Protocol uses the response status codes defined in HTTP [7]
1775 to indicate operation success or failure. In addition to returning a
1776 HTTP response code implementers MUST return the errors in the body of
1777 the response in the client requested format containing the error
1778 response and, per the HTTP specification, human-readable
1779 explanations. Implementers SHOULD handle the identified errors as
1780 described below.
1782 +--------------+---------------------------+------------------------+
1783 | Code | Applicability | Suggested Explanation |
1784 +--------------+---------------------------+------------------------+
1785 | 400 BAD | GET,POST,PUT,PATCH,DELETE | Request is |
1786 | REQUEST | | unparseable, |
1787 | | | syntactically |
1788 | | | incorrect, or violates |
1789 | | | schema |
1790 | 401 | GET,POST,PUT,PATCH,DELETE | Authorization failure |
1791 | UNAUTHORIZED | | |
1792 | 403 | GET,POST,PUT,PATCH,DELETE | Server does not |
1793 | FORBIDDEN | | support requested |
1794 | | | operation |
1795 | 404 NOT | GET,PUT,PATCH,DELETE | Specified resource; |
1796 | FOUND | | e.g., User, does not |
1797 | | | exist |
1798 | 409 CONFLICT | POST, PUT,PATCH,DELETE | The specified version |
1799 | | | number does not match |
1800 | | | the resource's latest |
1801 | | | version number or a |
1802 | | | Service Provider |
1803 | | | refused to create a |
1804 | | | new, duplicate |
1805 | | | resource |
1806 | 412 | PUT,PATCH,DELETE | Failed to update as |
1807 | PRECONDITION | | Resource {id} changed |
1808 | FAILED | | on the server last |
1809 | | | retrieved |
1810 | 413 REQUEST | POST | {"maxOperations": |
1811 | ENTITY TOO | | 1000,"maxPayload": |
1812 | LARGE | | 1048576} |
1813 | 500 INTERNAL | GET,POST,PUT,PATCH,DELETE | An internal error. |
1814 | SERVER ERROR | | Implementers SHOULD |
1815 | | | provide descriptive |
1816 | | | debugging advice |
1817 | 501 NOT | GET,POST,PUT,PATCH,DELETE | Service Provider does |
1818 | IMPLEMENTED | | not support the |
1819 | | | request operation; |
1820 | | | e.g., PATCH |
1821 +--------------+---------------------------+------------------------+
1823 Table 7: Defined error cases
1825 Error example in response to a non-existent GET request.
1827 HTTP/1.1 404 NOT FOUND
1829 {
1830 "Errors":[
1831 {
1832 "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
1833 "code":"404"
1834 }
1835 ]
1836 }
1838 3.10. API Versioning
1840 The Base URL MAY be appended with a version identifier as a separate
1841 segment in the URL path. At this time the only valid identifier is
1842 'v1'. If specified, the version identifier MUST appear in the URL
1843 path immediately preceding the Resource endpoint and conform to the
1844 following scheme: the character 'v' followed by the desired SCIM
1845 version number; e.g., a version 'v1' User request is specified as
1846 /v1/Users. When specified Service Providers MUST perform the
1847 operation using the desired version or reject the request. When
1848 omitted Service Providers SHOULD perform the operation using the most
1849 recent API supported by the Service Provider.
1851 3.11. Versioning Resources
1853 The API supports resource versioning via standard,HTTP ETags.
1854 Service providers MAY support weak ETags as the preferred mechanism
1855 for performing conditional retrievals and ensuring Consumers do not
1856 inadvertently overwrite each others changes, respectively. When
1857 supported SCIM ETags MUST be specified as an HTTP header and SHOULD
1858 be specified within the 'version' attribute contained in the
1859 Resource's 'meta' attribute.
1861 Example:
1863 POST /Users HTTP/1.1
1864 Host: example.com
1865 Content-Type: application/json
1866 Authorization: Bearer h480djs93hd8
1867 Content-Length: ...
1869 {
1870 "schemas":["urn:scim:schemas:core:1.0"],
1871 "userName":"bjensen",
1872 "externalId":"bjensen",
1873 "name":{
1874 "formatted":"Ms. Barbara J Jensen III",
1875 "familyName":"Jensen",
1876 "givenName":"Barbara"
1877 }
1878 }
1880 The server responds with an ETag in the response header and meta
1881 structure.
1883 HTTP/1.1 201 Created
1884 Content-Type: application/json
1885 Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646
1886 ETag: W/"e180ee84f0671b1"
1888 {
1889 "schemas":["urn:scim:schemas:core:1.0"],
1890 "id":"2819c223-7f76-453a-919d-413861904646",
1891 "meta":{
1892 "created":"2011-08-01T21:32:44.882Z",
1893 "lastModified":"2011-08-01T21:32:44.882Z",
1894 "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
1895 "version":"W\/\"e180ee84f0671b1\""
1896 },
1897 "name":{
1898 "formatted":"Ms. Barbara J Jensen III",
1899 "familyName":"Jensen",
1900 "givenName":"Barbara"
1901 },
1902 "userName":"bjensen"
1903 }
1904 With the returned ETag, Consumers MAY choose to retrieve the Resource
1905 only if the Resource has been modified.
1907 Conditional retrieval example using If-None-Match header:
1909 GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName
1910 Host: example.com
1911 Accept: application/json
1912 Authorization: Bearer h480djs93hd8
1913 If-None-Match: W/"e180ee84f0671b1"
1915 If the Resource has not changed the Service Provider simply returns
1916 an empty body with a 304 "Not Modified" response code.
1918 If the Service Providers supports versioning of resources the
1919 Consumer MUST supply an If-Match header for PUT and PATCH operations
1920 to ensure that the requested operation succeeds only if the supplied
1921 ETag matches the latest Service Provider Resource; e.g., If-Match:
1922 W/"e180ee84f0671b1"
1924 3.12. HTTP Method Overloading
1926 In recognition that some clients, servers and firewalls prevent PUT,
1927 PATCH and DELETE operations a client MAY override the POST operation
1928 by specifying the custom header "X-HTTP-Method-Override" with the
1929 desired PUT, PATCH, DELETE operation. For example:
1931 POST /Users/2819c223-7f76-453a-919d-413861904646
1932 X-HTTP-Method-Override: DELETE
1934 4. Security Considerations
1936 The SCIM Protocol is based on HTTP and thus subject to the security
1937 considerations found in Section 15 of [RFC2616]. SCIM Resources
1938 (e.g., Users and Groups) can contain sensitive information.
1939 Therefore, SCIM Consumers and Service Providers MUST implement TLS.
1940 Which version(s) ought to be implemented will vary over time, and
1941 depend on the widespread deployment and known security
1942 vulnerabilities at the time of implementation. At the time of this
1943 writing, TLS version 1.2 [RFC5246 [8]] is the most recent version,
1944 but has very limited actual deployment, and might not be readily
1945 available in implementation toolkits. TLS version 1.0 [RFC2246 [8]]
1946 is the most widely deployed version, and will give the broadest
1947 interoperability.
1949 5. Contributors
1951 Samuel Erdtman (samuel@erdtman.se)
1953 Patrick Harding (pharding@pingidentity.com)
1955 6. Acknowledgments
1957 The editor would like to thank the participants in the the SCIM
1958 working group for their support of this specification.
1960 Authors' Addresses
1962 Trey Drake (editor)
1963 UnboundID
1965 Email: trey.drake@unboundid.com
1967 Chuck Mortimore
1968 SalesForce
1970 Email: cmortimore@salesforce.com
1972 Morteza Ansari
1973 Cisco
1975 Email: morteza.ansari@cisco.com
1977 Kelly Grizzle
1978 SailPoint
1980 Email: kelly.grizzle@sailpoint.com
1982 Erik Wahlstroem
1983 Technology Nexus
1985 Email: erik.wahlstrom@nexussafe.com